swagger: '2.0' info: title: Dates description: >- The Dates API provides various operations relating to calendars and dates. For example, the `/eventDates` method can be used to find upcoming events given one or more schedules and a calendar of exclusions. version: 0.1.0 contact: name: Apiture url: 'https://developer.aptiture.com' email: api@apiture.com termsOfService: 'TODO: Terms of Service is TBD; need input from Legal team.' schemes: - https basePath: /dates consumes: - application/hal+json - application/json produces: - application/hal+json - application/json tags: - name: API description: Endpoints which describe this API. - name: Event Dates description: List of event dates paths: /: get: summary: Top-level resources and operations in this API description: >- Return links to the top-level resources and operations in this API. Links included in this response include: * *`apiture:findEventDates`* - a `POST` operation for finding dates corresponding to recurring scheduled events operationId: getApi x-apiture-implemented: true responses: '200': description: OK schema: $ref: '#/definitions/root' tags: - API /apiDoc: get: summary: Return API definition document description: Return the OpenAPI document that describes this API. operationId: getApiDoc x-apiture-implemented: true produces: - application/json - application/openapi+json;version=2.0 - application/openapi+yaml;version=2.0 responses: '200': description: OK schema: type: object tags: - API /eventDates: post: summary: Return a collection of event dates description: >- Finds upcoming event dates given one or more schedules of events and exclusions. Available parameters include `start`, `limit`, `startDate`, and `period`. There are two modes of pagination available: * Indexed pages defined by a `start` index and a `limit` * `period` based pagination beginning at `startDate` Only one mode of pagination can be used at a time and the default mode is `period` with a value of `P1Y`. To obtain the next page of results, use the `next` link in the response (if it exists) with a `POST` verb. Pass the same request body as passed to this operation (this operation is fully stateless.) If there is no `next` link, the collection has been exhausted. Note that some queries may not have a terminating collection (for example, if the schedule does not have a start date). The service will update the query parameters in the link to access the next page, according to the type of pagination in use. Thait is, it will increment the `start` if initially invoked with indexed-based pagination, or it will adjust the `startDate` if initially invoked with period-based pagination. The `limit` passed to this operation will also be passed to the `next` page. operationId: findEventDates x-apiture-implemented: true parameters: - name: start in: query description: >- The zero-based index of the first event date item to include in this page. The default 0 denotes the beginning of the collection. If `startDate` is also provided `start` will be ignored. type: integer format: int64 default: 0 - name: limit in: query description: >- The maximum number of event dates to return in this page. If `period` is also provided, `limit` will be ignored. type: integer format: int32 default: 100 - name: startDate in: query description: >- The start date of the period in which to look for events. If `period` pagination mode is being used and no `startDate` is provided, the current date will be used. `startDate` will override `start` if both are provided. type: string format: date - name: period in: query description: >- The length of time used to paginate event date results. `period` will override `limit` if both are provided. This value is an [ISO 8601 duration](https://en.wikipedia.org/wiki/ISO_8601#Durations) string of the form `P[n]Y[n]M[n]D` to specify the number of years/months/days between dates. For example, use `P7D` to paginate by weeks, `P2M` to paginate by 2 months. Time values in `period` are ignored but may be honored in the future. type: string default: "P1Y" - name: eventDatesRequest in: body description: The data necessary to find event dates. required: true schema: $ref: '#/definitions/eventDatesRequest' produces: - application/json - application/openapi+json;version=2.0 - application/openapi+yaml;version=2.0 responses: '200': description: OK schema: $ref: '#/definitions/eventDates' '400': $ref: '#/responses/400' '422': $ref: '#/responses/422' tags: - Event Dates responses: '400': description: >- Bad Request. The request body or one or more of the query parameters was not well formed. The `_error` field in the response will contain details about the request error. schema: $ref: '#/definitions/errorResponse' '422': description: >- Unprocessable Entity. One or more of the query parameters was well formed but otherwise invalid. The `_error` field in the response will contain details about the request error. schema: $ref: '#/definitions/errorResponse' definitions: abstractResource: title: Abstract Resource description: >- An augmented [HAL](https://tools.ietf.org/html/draft-kelly-json-hal-08) resource representation. This model contains hypermedia `_links`, and either optional domain object data with `_profile` and optional `_embedded` objects, or an `_error` object. In responses, if the operation was successful, this object will not include the `_error`, but if the operation was a 4xx or 5xx error, this object will not include `_embedded` or any data fields, only `_error` and optionally `_links`. example: _profile: 'http://api.apiture.com/schemas/example/v1.0.0/profile.json' _links: self: href: '{uri of current resource}' properties: _links: $ref: '#/definitions/links' _embedded: description: >- An optional map of nested resources, mapping each nested resource name to a nested resource representation. type: object _profile: description: >- The URI of a [resource profile](http://doc.apiture.com/api/concepts/resource-profile) which describes the representation. type: string format: uri _error: description: >- An object which describes an error. This value is omitted if the operation succeeded without error. type: object allOf: - $ref: '#/definitions/error' root: title: Dates API Root description: >- A HAL response, with hypermedia `_links` for the top-level resources and operations in API. example: id: dates name: dates apiVersion: 0.1.0 _profile: 'https://api.apiture.com/schemas/root/v1.0.0/profile.json' _links: {} allOf: - $ref: '#/definitions/abstractResource' - type: object properties: _id: type: string description: This API's unique ID. name: type: string description: This API's name. apiVersion: type: string description: This API's version. errorResponse: title: Error Response description: >- Describes an error response, typically returned on 4xx or 5xx errors from API operations. The `_error` object contains the error details. allOf: - $ref: '#/definitions/abstractResource' example: _profile: 'http://api.apiture.com/schemas/error/v1.0.0/profile.json' _error: _id: 2eae46e1-575c-4d69-8a8f-0a7b0115a4b3 _profile: 'https://api.apiture.com/schemas/error/v1.0.0/profile.json' message: The value for deposit must be greater than 0. statusCode: 422 type: integer attributes: value: -125.5 remediation: Provide a value which is greater than 0 occurredAt: 2018-01-25T05:50:52.375Z _links: describedby: href: 'http://doc.apiture.com/errors/positiveNumberRequired' _embedded: errors: [] error: title: Error description: >- An error description. Nested source errors are contained in the `_embedded` object with the key `"errors"`; this is an array of nested error objects. For example, an API which validates its request body may find multiple errors in the request, which may be detailed here. The `_links` may contain a `describedby` link which refers to a web page with details about the error. The `attributes` field An optional map of name/value pairs which provide structured data about the error. For example, if the error is a value out of range, the attributes may specify the range values `min` and `max`. This allows clients to present error messages as they see fit (the API does not assume the client/presentation tier). required: - message properties: message: type: string description: A localized message string describing the error condition. _id: type: string description: >- A unique identifier for this error instance. This may be used as a correlation ID with the root cause error (i.e. this ID may be logged at the source of the error). This is is an opaque string. statusCode: description: The HTTP status code associate with this error. type: integer minimum: 100 maximum: 599 example: 422 type: type: string description: >- An error identifier which indicates the category of error and associate it with API support documentation or which the UI tier can use to render an appropriate message or hint. This provides a finer level of granularity than the `statusCode`. For example, instead of just 400 Bad Request, the `type` may be much more specific. such as `integerValueNotInAllowedRange` or `numericValueExceedsMaximum` or `stringValueNotInAllowedSet`. occurredAt: type: string format: date-time description: An ISO 8601 UTC time stamp indicating when the error occurred. example: '2018-02-02T03:37:15.375Z' attributes: description: >- Data attribute associated with the error, such as values or constraints. allOf: - $ref: '#/definitions/attributes' remediation: type: string description: >- An optional localized string which provides hints for how the user or client can resolve the error. _embedded: description: >- Optional embedded array of errors. This field may not exist if the error does not have nested errors. type: object properties: items: description: An array of error objects. type: array items: $ref: '#/definitions/errorResponse' example: _id: 2eae46e1-575c-4d69-8a8f-0a7b0115a4b3 _profile: 'https://api.apiture.com/schemas/error/v1.0.0/profile.json' message: The value for deposit must be greater than 0. statusCode: 422 type: positiveNumberRequired attributes: value: -125.5 remediation: Provide a value which is greater than 0 occurredAt: '2018-01-25T05:50:52.375Z' _links: describedby: href: 'http://doc.apiture.com/errors/positiveNumberRequired' _embedded: errors: [] attributes: title: Attributes description: >- An optional map of name/value pairs which contains additional dynamic data about the resource. type: object eventDatesRequest: title: Event Dates Request description: >- The request body for invoking `/eventDates`. Contains an array of scheduled events and a calendar representing excluded dates. type: object required: - schedules properties: schedules: type: array items: $ref: '#/definitions/schedule' exclusions: $ref: '#/definitions/calendar' eventDates: title: Event Date Collection description: >- Collection of event dates. The items in the collection are ordered in the `_embedded` object with name `items`. The top-level `_links` object may contain pagination links (`self`, `next`, `prev`, `first`, `last`, `collection`.) These pagination links require using `POST` and should pass the same Event Dates Request object as described in the `findEventsDate` operation. allOf: - $ref: '#/definitions/collection' - type: object properties: startDate: description: The start date of events on this page. type: string period: description: >- The length of time used to paginate event date results. type: string _embedded: type: object properties: items: description: An array containing a page of event dates. type: array items: $ref: '#/definitions/eventDate' example: _profile: 'http://api.apiture.com/schemas/collection/eventDate/v0.1.0/profile.json' start: 0 limit: 5 count: 28 name: eventDates _links: self: href: /dates/eventDates?start=0&limit=5 first: href: /dates/eventDates?start=0&limit=5 next: href: /dates/eventDates?start=5&limit=5 collection: href: /dates/eventDates _embedded: items: - labels: ["Core Schedule"] date: "2018-06-14" - labels: ["Core Schedule"] date: "2018-06-16" - labels: ["Core Schedule"] date: "2018-06-18" - labels: ["Core Schedule", "Second Schedule"] date: "2018-06-20" - labels: ["Core Schedule", "Second Schedule"] date: "2018-06-22" eventDate: title: Event Date description: >- A date and one or more events that occur on that date. The `labels` property will reference the associated schedules. type: object required: - labels - date properties: labels: description: >- The text `label` for this event, suitable for presentation to the client. This label references the one or more associated schedules. type: array items: type: string date: description: >- This date is in the [ISO 8601 Date](https://en.wikipedia.org/wiki/ISO_8601#Calendar_dates) format, `yyyy-mm-dd`. type: string format: date example: '2018-04-05' schedule: title: Schedule description: A definition for a one-time or recurring scheduled event. required: - label properties: label: description: >- The text `label` for this schedule, suitable for presentation to the client. Events will use this label to reference a schedule. type: string example: Retirement savings transfer start: description: >- When the event occurs, or when a recurring event begins. This may be either a date in `yyyy-mm-dd` format, or a date-time in `yyyy-mm-ddTHH:MM:SSZ` format. If present, the time portion is a _hint_; the FI may not be able to schedule events at specific times. If `start` is omitted, the event will be scheduled for the next processing day. If `start` is the current day, the event may be scheduled for the next processing day if event processing has stopped for the day. If `start` is not provided, the current date will be used. type: string example: '2018-06-10' every: description: >- The `every` period indicates the interval at which the event recurs, such as every week, every month, every 3 months. If omitted or empty, this event is a one-time event. `every` is **required** if either `maximumCount` is greater than 1 or if `end` is greater than `start`. This value is an [ISO 8601 duration](https://en.wikipedia.org/wiki/ISO_8601#Durations) string of the form `P[n]Y[n]M[n]D` to specify the number of years/months/days between events. For example, use `P7D` to schedule every week, `P2M` to schedule every other month, `P4Y` to schedule every four years on the anniversary set by `start`. Time values in `every` are ignored but may be honored in the future. (That is, it is not possible to schedule an event every 8 hours; the minimum is `P1D`.) To specify semi-monthly or semi-annually, use `P0.5M` or `P0.5Y`. Fractional values are only allowed for month and year, and `0.5` is the only allowed fractional value. Some financial institutions may limit recurring events such that the period must be a year (`P1Y`, 'P12M`, 'P365D`) or less. Scheduling may adjust event dates if `start` occurs near boundary dates which do occur not every year/month, such as `start: "2018-01-31", every: "P1M"`. For example, the next event may occur on the 30th for months which have only 30 days (Apr, Jun, Sep, Nov), or 29th or 28th for February. Actual event dates may also be adjusted to account for holidays or other days when processing does not occur. type: string example: P14D count: description: >- For a recurring event, this is the number of events which have occurred. It is a derived value and ignored on updates. type: integer example: 5 skippedCount: description: >- For a recurring event, this is the number of events which have been skipped, either because a processing date passed when a recurring event had a value of `true` for `skipNext`, or a recurring event was suspended. It is a derived value and ignored on updates. type: integer example: 0 maximumCount: description: >- The maximum number of events to schedule for a recurring event. (Events in the recurrence will stop if the current date is beyond that set by `end, even if fewer than `maximumCount` events have occurred.) The `every` period is required if `maximumCount` or `end` is set. It is an error (422) if `maximumCount` is anything other than 0 or 1 and `every` is not set. If a schedule contains both `end` and `maximumCount`, the _earliest_ will determine when the recurrence ends. type: integer example: 10 skipNext: description: >- This field is *ignored* for one-time events. If true for recurring schedules, skip (do not schedule) the next event. After that instance is skipped, this field is reset to false (only one instance may be skipped). type: boolean example: true end: description: >- The date when the recurring event ends (inclusive). Events will occur until the `maximumCount` of events have occurred _or_ the next scheduled event will be _after_ the date or date-time specified in `end`. (Earliest of `maximumCount` or `end` wins.) If specified, `end` must be no earlier than `start`.

This has the same format as `start` (may be a ISO 8601 date or a date-time).

When scheduling an event, the request should contain either `maximumCount` or `end`, but not both. The other field will be computed. type: string example: '2018-08-01' calendar: title: Calendar description: A definition of a calendar required: - holidays - unprocessableDays properties: holidays: description: >- A collection of dates on which events cannot occur. These dates should be in the [ISO 8601 Date](https://en.wikipedia.org/wiki/ISO_8601#Calendar_dates) format, `yyyy-mm-dd`. type: array items: type: string format: date uniqueItems: true example: - '2018-12-24' - '2018-12-25' unprocessableDays: description: >- A collection of days of the week on which events cannot occur. type: array items: type: string enum: ['sunday', 'monday', 'tuesday', 'wednesday', 'thursday', 'friday', 'saturday'] uniqueItems: true example: - 'sunday' - 'saturday' collection: title: Collection description: >- A collection of resources. This is an abstract model schema which is extended to define specific resource collections. allOf: - $ref: '#/definitions/abstractResource' - type: object properties: count: description: The number of items in the full collection. type: integer start: description: The start index of this page of items. type: integer limit: description: The maximum number of items per page. type: integer name: description: The name of the collection. type: string links: title: Links description: >- An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations. type: object additionalProperties: $ref: '#/definitions/link' link: title: Link description: >- Describes a hypermedia link within a `_links` object in HAL representations. In Apiture APIs, links are [HAL links](https://tools.ietf.org/html/draft-kelly-json-hal-08#section-5), but Apiture APIs do not use the `name` or `hreflang` properties of HAL. Apiture links _may_ include a `method` property. required: - href properties: href: type: string format: uri description: >- The URI or URI template for the resource/operation this link refers to. type: type: string description: The media type for the resource. templated: type: boolean description: >- If true, the link's href is a [URI template](https://tools.ietf.org/html/rfc6570). title: type: string description: An optional human-readable localized title for the link. deprecation: type: string format: uri description: >- If present, the containing link is deprecated and the value is a URI which provides human-readable text information about the deprecation. profile: type: string format: uri description: >- The URI of a profile document, a JSON document which describes the target resource/operation. x-apiture-traits: - api: title: dates basePath: dates links: [ getApi, getApiDoc, findEventDates ]