openapi: 3.0.0
servers:
- url: 'https://api.devbank.apiture.com/notifications'
x-note: DO NOT EDIT THIS GENERATED FILE. Edit source file src/openapi/openapi.yaml
x-note-generated-by: openapi-schema-resolver
x-note-generated-on: '2020-09-14T08:46:54-0400'
info:
title: Notifications
description: |-
The Notifications API supports in-app notifications for Apiture digital banking clients. Using this API,
services can generate notifications and clients can pull notifications for different contexts, such as users
or accounts or a global context. These notifications are not related to operating system or devices
notifications.
This API manages two types of resources:
* Notification definitions
* Notification instances
(Unless explicitly stated, the term "notification" in this document refers to a _notification instance_. When
discussing _notification definitions_, we use the term "notification definition" or "definition".)
Services or administrative applications [create _notification definitions_](#op-createNotificationDefinition)
which act as templates for individual _notification instances_. A definition defines the context name for
the notifications, the notification type, its message text, etc. Definitions are not associated with specific users.
After creating a definition, services call [`createNotifications`](#op-createNotifications) to create
_instances_ from that definition. Instances contain contexts (usually the URI of a specific resource such as
an account or transfer, etc), a user, and optional expiration timestamp. Instances also derive the
notification message from their definition.
The client applications [fetch _notification instances_](#op-getActiveNotifications) for an authenticated
user in order to render an in-application message. Users may dismiss a notification and that is tracked with
the notification instance (they are exclude on the next `getActiveNotifications` call).
Users can only view their own notifications and notifications definitions. End users do not have access to
create or mofify definitions, create notification instances, expire or delete definitions, or expire or
delete notification instances. Those operations are reserved for administrators and services.
version: 0.10.1
contact:
name: Apiture
url: 'https://developer.apiture.com'
email: api@apiture.com
termsOfService: 'https://developer.apiture.com/docs/Apiture-Open-API-License-Agreement.pdf'
tags:
- name: Notification Definitions
description: Definitions of In-app Notifications
- name: Notification Definition Actions
description: Actions on Notification Definitions
- name: Notifications
description: In-app Notifications
- name: Notifications Actions
description: Actions on Notifications
- name: API
description: The Notifications API
paths:
/expiredDefinitions:
post:
operationId: expireDefinition
security:
- apiKey: []
accessToken:
- admin/write
summary: Expire a notification definition
description: >-
Expire a notification definition. This changes the `expired` property of the definition to `true`. This operation is available via the
`apiture:expire` link on the definition resource, if the current time is past the definition's `expiresAt` date-time value. This operation may
be invoked before the `expiresAt` time to expire it earlier.
This operation also expires all `active` notification instances defined by this definition. This operation does nothing if the definition has
already expired. this definition.
The response is the updated representation of the definition. The `If-Match` request header value, if passed, must match the current entity
tag value of the definition.
tags:
- Definition Actions
parameters:
- $ref: '#/components/parameters/definitionQueryParam'
- $ref: '#/components/parameters/ifMatchHeaderParam'
responses:
'200':
description: OK. The operation succeeded.
headers:
ETag:
description: >-
The `ETag` response header specifies an entity tag which may be provided in an `If-Match` request header for *`PUT`* or *`PATCH`*
operations which update the resource to perform conditional updates.
schema:
type: string
content:
application/hal+json:
schema:
$ref: '#/components/schemas/notificationDefinition'
application/json:
schema:
$ref: '#/components/schemas/notificationDefinition'
'400':
$ref: '#/components/responses/400ExpireNotificationDefinition'
'412':
$ref: '#/components/responses/412'
/definitions:
get:
summary: Return a collection of notification definitions
description: >-
Return a [paginated](https://developer.apiture.com/docs/concepts/pagination) [sortable](https://developer.apiture.com/docs/concepts/sorting)
[filterable](https://developer.apiture.com/docs/concepts/filtering) [searchable](https://developer.apiture.com/docs/concepts/searching)
collection of notification definitions. The [links](https://developer.apiture.com/docs/concepts/links) in the response include pagination
links.
operationId: getDefinitions
security:
- apiKey: []
accessToken:
- data/read
tags:
- Notification Definitions
parameters:
- name: start
in: query
description: The zero-based index of the first definition item to include in this page. The default 0 denotes the beginning of the collection.
schema:
type: integer
format: int64
default: 0
- name: limit
in: query
description: The maximum number of definition representations to return in this page.
schema:
type: integer
format: int32
default: 100
- name: sortBy
in: query
description: 'Optional sort criteria. See [sort criteria format](https://developer.apiture.com/docs/concepts/sorting), such as `?sortBy=field1,-field2`.'
schema:
type: string
- name: expired
in: query
description: Filter definitions whose `expired` property matches the given value.
schema:
type: boolean
- $ref: '#/components/parameters/definitionTypeQueryParam'
- $ref: '#/components/parameters/definitionContextNameQueryParam'
- $ref: '#/components/parameters/filterQueryParam'
- $ref: '#/components/parameters/qQueryParam'
responses:
'200':
description: OK
content:
application/hal+json:
schema:
$ref: '#/components/schemas/notificationDefinitions'
application/json:
schema:
$ref: '#/components/schemas/notificationDefinitions'
'400':
$ref: '#/components/responses/400'
'422':
$ref: '#/components/responses/422'
post:
summary: Create a new notification definition
description: >-
Create a new notification definition that specifies the notification type and message. After creating a notification, [create notification
instances](#op-createNotifications) for specific users and contexts.
**Note**: To add a global notification, use [`createGlobalDefinition`](#op-createGlobalDefinition) instead.
operationId: createDefinition
security:
- apiKey: []
accessToken:
- admin/write
tags:
- Notification Definitions
responses:
'201':
description: Created
headers:
Location:
description: >-
The URI of the new resource. If the URI begins with / it is relative to the API root context. Else, it is a full URI starting with
*`scheme`*`://host`
schema:
type: string
format: uri
ETag:
description: An entity tag which may be passed in the `If-Match` request header for *`PUT`* or *`PATCH`* operations which update the resource.
schema:
type: string
content:
application/hal+json:
schema:
$ref: '#/components/schemas/notificationDefinition'
application/json:
schema:
$ref: '#/components/schemas/notificationDefinition'
'400':
$ref: '#/components/responses/400'
'422':
$ref: '#/components/responses/422NotificationDefinition'
requestBody:
content:
application/hal+json:
schema:
$ref: '#/components/schemas/createNotificationDefinition'
application/json:
schema:
$ref: '#/components/schemas/createNotificationDefinition'
description: The data necessary to create a new notification definition.
required: true
/globalDefinitions:
post:
summary: Create a new global notification definition
description: >-
Create a new global notification definition with a message. A global notification definition is one whose `contextName` is `global`. This is
used for announcements targeted to all financial institution customers. The new definition is available in the
[`getDefinitions`](#op-getDefinitions) collection. Clients should request active global notifications for users via
[`getActiveNotifications`](#op-getActiveNotifications) and `?context=global` (or `?context=global|user`). The services does not create
Instances of a global notification for each user until a client requests them.
To add a non-global notification, use [`createDefinition`](#op-createDefinition) instead.
operationId: createGlobalDefinition
security:
- apiKey: []
accessToken:
- admin/write
tags:
- Notification Definitions
responses:
'201':
description: Created
headers:
Location:
description: >-
The URI of the new resource. If the URI begins with / it is relative to the API root context. Else, it is a full URI starting with
*`scheme`*`://host`
schema:
type: string
format: uri
ETag:
description: An entity tag which may be passed in the `If-Match` request header for *`PUT`* or *`PATCH`* operations which update the resource.
schema:
type: string
content:
application/hal+json:
schema:
$ref: '#/components/schemas/notificationDefinition'
application/json:
schema:
$ref: '#/components/schemas/notificationDefinition'
'400':
$ref: '#/components/responses/400'
'422':
$ref: '#/components/responses/422CreateNotification'
requestBody:
content:
application/hal+json:
schema:
$ref: '#/components/schemas/createGlobalNotificationDefinition'
application/json:
schema:
$ref: '#/components/schemas/createGlobalNotificationDefinition'
description: The data necessary to create a new global notification definition.
required: true
'/definitions/{definitionId}':
get:
summary: Fetch a representation of this notification definition
description: 'Return a [HAL](https://developer.apiture.com/docs/concepts/hal) representation of this notification definition resource.'
operationId: getDefinition
security:
- apiKey: []
accessToken:
- data/read
tags:
- Notification Definitions
parameters:
- $ref: '#/components/parameters/definitionIdPathParam'
- $ref: '#/components/parameters/ifNoneMatchHeaderParam'
responses:
'200':
description: OK
headers:
ETag:
description: >-
The `ETag` response header specifies an entity tag which may be provided in an `If-Match` request header for *`PUT`* or *`PATCH`*
operations which update this definition resource.
schema:
type: string
content:
application/hal+json:
schema:
$ref: '#/components/schemas/notificationDefinition'
application/json:
schema:
$ref: '#/components/schemas/notificationDefinition'
'304':
$ref: '#/components/responses/304'
'404':
$ref: '#/components/responses/404NotificationDefinition'
put:
summary: Update this definition
description: Perform a complete replacement of this definition.
operationId: updateDefinition
security:
- apiKey: []
accessToken:
- admin/write
tags:
- Notification Definitions
parameters:
- $ref: '#/components/parameters/definitionIdPathParam'
- $ref: '#/components/parameters/ifMatchHeaderParam'
responses:
'200':
description: OK
headers:
ETag:
description: >-
The `ETag` response header specifies an entity tag which may be provided in an `If-Match` request header for *`PUT`* or *`PATCH`*
operations which update this definition resource.
schema:
type: string
content:
application/hal+json:
schema:
$ref: '#/components/schemas/notificationDefinition'
application/json:
schema:
$ref: '#/components/schemas/notificationDefinition'
'400':
$ref: '#/components/responses/400'
'404':
$ref: '#/components/responses/404NotificationDefinition'
'412':
$ref: '#/components/responses/412'
'422':
$ref: '#/components/responses/422NotificationDefinition'
requestBody:
content:
application/hal+json:
schema:
$ref: '#/components/schemas/notificationDefinition'
application/json:
schema:
$ref: '#/components/schemas/notificationDefinition'
required: true
patch:
summary: Update this definition
description: >-
Perform a partial update of this definition. Fields which are omitted are not updated. Nested `_embedded` and `_links` are ignored if
included.
operationId: patchDefinition
security:
- apiKey: []
accessToken:
- admin/write
tags:
- Notification Definitions
parameters:
- $ref: '#/components/parameters/definitionIdPathParam'
- $ref: '#/components/parameters/ifMatchHeaderParam'
responses:
'200':
description: OK
headers:
ETag:
description: >-
The `ETag` response header specifies an entity tag which may be provided in an `If-Match` request header for *`PUT`* or *`PATCH`*
operations which update this definition resource.
schema:
type: string
content:
application/hal+json:
schema:
$ref: '#/components/schemas/notificationDefinition'
application/json:
schema:
$ref: '#/components/schemas/notificationDefinition'
'400':
$ref: '#/components/responses/400'
'404':
$ref: '#/components/responses/404NotificationDefinition'
'412':
$ref: '#/components/responses/412'
'422':
$ref: '#/components/responses/422NotificationDefinition'
requestBody:
content:
application/hal+json:
schema:
$ref: '#/components/schemas/notificationDefinition'
application/json:
schema:
$ref: '#/components/schemas/notificationDefinition'
required: true
delete:
summary: Delete this notification definition resource
description: >-
Delete this notification definition resource and any notification instances that are defined by it. Normally, the service deletes definitions
some time after they have expired.
operationId: deleteDefinition
security:
- apiKey: []
accessToken:
- admin/delete
tags:
- Notification Definitions
parameters:
- $ref: '#/components/parameters/definitionIdPathParam'
responses:
'204':
$ref: '#/components/responses/204Deleted'
'/definitions/{definitionId}/notifications':
parameters:
- $ref: '#/components/parameters/definitionIdPathParam'
post:
summary: Create notifications from a notification definition.
description: Create notification instances from a notification definition.
operationId: createNotifications
security:
- apiKey: []
accessToken:
- admin/write
tags:
- Notifications
responses:
'200':
description: OK. The instances have been created for this notification definition.
headers:
ETag:
description: An entity tag which may be passed in the `If-Match` request header for *`PUT`* or *`PATCH`* operations which update the resource.
schema:
type: string
content:
application/hal+json:
schema:
$ref: '#/components/schemas/notificationDefinition'
application/json:
schema:
$ref: '#/components/schemas/notificationDefinition'
'400':
$ref: '#/components/responses/400'
'409':
$ref: '#/components/responses/409InstancesConflict'
requestBody:
content:
application/hal+json:
schema:
$ref: '#/components/schemas/instances'
application/json:
schema:
$ref: '#/components/schemas/instances'
description: The data necessary to create new notification instances from this definition.
required: true
/dismissedNotifications:
post:
operationId: dismissNotification
security:
- apiKey: []
accessToken:
- data/write
summary: Dismiss a notification
description: >-
Dismiss a notification. This changes the `dismissed` property of a notification to `true` and records the `dismissedAt` timestamp. This
operation is available via the `apiture:dismiss` link on the notification resource if both `expired` and `dismissed` are `false`. Dismissing
an expired notification is allowed. Dismissing a previously dismissed notification is allowed, but does not change the state of the instance.
The response is the updated representation of the notification. The `If-Match` request header value, if passed, must match the current entity
tag value of the notification.
tags:
- Notification Actions
parameters:
- $ref: '#/components/parameters/notificationQueryParam'
- $ref: '#/components/parameters/ifMatchHeaderParam'
responses:
'200':
description: OK. The operation succeeded.
headers:
ETag:
description: >-
The `ETag` response header specifies an entity tag which may be provided in an `If-Match` request header for *`PUT`* or *`PATCH`*
operations which update the resource to perform conditional updates.
schema:
type: string
content:
application/hal+json:
schema:
$ref: '#/components/schemas/notification'
application/json:
schema:
$ref: '#/components/schemas/notification'
'400':
$ref: '#/components/responses/400DismissNotification'
'409':
$ref: '#/components/responses/409DismissNotificationConflict'
'412':
$ref: '#/components/responses/412'
/expiredNotifications:
post:
operationId: expireNotification
security:
- apiKey: []
accessToken:
- admin/write
summary: Expire a notification
description: >-
Expire a notification instance. This changes the `expired` property of the notification to `true`. This operation is available via the
`apiture:expire` link on the notification resource if both `dismissed` and `expired` are false. Expiring a dismissed notification is allowed.
Expiring a previously expired notification is allowed, but does not change the state of the instance.
Expiring a definition invokes this operation on all instances derived from that definition.
The response is the updated representation of the notification. The `If-Match` request header value, if passed, must match the current entity
tag value of the notification.
tags:
- Notification Actions
parameters:
- $ref: '#/components/parameters/notificationQueryParam'
- $ref: '#/components/parameters/ifMatchHeaderParam'
responses:
'200':
description: OK. The operation succeeded.
headers:
ETag:
description: >-
The `ETag` response header specifies an entity tag which may be provided in an `If-Match` request header for *`PUT`* or *`PATCH`*
operations which update the resource to perform conditional updates.
schema:
type: string
content:
application/hal+json:
schema:
$ref: '#/components/schemas/notification'
application/json:
schema:
$ref: '#/components/schemas/notification'
'400':
$ref: '#/components/responses/400ExpireNotification'
'409':
$ref: '#/components/responses/409ExpireNotificationConflict'
'412':
$ref: '#/components/responses/412'
/activeNotifications:
get:
summary: Return active notifications
description: |-
Return a list of active notifications for a user which match a context by
name or URI. The response excludes dismissed or expired notifications.
This is the primary operation clients used to fetch (a.k.a. _pull_) notifications
for a user for a given context, client type (`web` or `mobile`),
and user language preferences. Each active notification in the response
`_embedded.items` contains the details of the notification in its `_embedded.definition`
This operation returns the preferred text and image (based on the client type and languages) in
each active notification's `message` property.
The `message` in each instance in the response is the best match from the
notification definition's `message`, `webMessage` and `mobileMessage`, as determined by
the `?clientType=` and `?languages=` query parameters.
The service also resolves any `{variableName}` variables in the message text with the `values` from
the instance or definition.
The client should display the
notifications in the user interface. Notifications defined with `indicator: true`
should be displayed with the `message.imageUri` icon, although the client may use
the rendered `message.text` as a hover tip. This acts as a "badge".
Clients should display other (non-indicator) notifications as text notifications, with optional icon,
and with a **Dismiss** or **OK** or other control to dismiss the notification.
The client should convert the
[Markdown](https://help.github.com/articles/basic-writing-and-formatting-syntax/)
text to rich text before displaying it.
When the user dismisses a notification, the client should
`POST` to that notification's `apiture:dismiss` link so the
service can exclude the notification from the response the next time the
client calls this operation for this context.
operationId: getActiveNotifications
security:
- apiKey: []
accessToken:
- data/read
tags:
- Notifications
parameters:
- $ref: '#/components/parameters/contextQueryParam'
- name: clientType
in: query
description: >-
If `?clientType=web`, the notifications' `message` is derived from the `webMessage` in the corresponding notification definition, ignoring
the the definition's `mobileMessage`. If no `webMessage` is defined for the requested 'languages', the notifications' `message` is derived
from the definitions `message`. `?clientType=mobile` is handled analogously, using `mobileMessage`. The default uses the definition's
`message` if it is defined, else `webMessage`.
schema:
type: string
enum:
- web
- mobile
- name: languages
description: >-
Return message variants that match the user's language preference. The array is ordered by highest to lowest preference language tag(s).
For example, for `?languages=es,en`, the response will include message variants based on the following search priority: `es` ⇒ `en`
⇒ ⇒ (_default_)
Items are [RFC 3066](https://tools.ietf.org/html/rfc3066) language identifiers. If used, `Accept-Language`
header is ignored. Language codes are case insensitive.
in: query
style: form
schema:
type: array
items:
type: string
minLength: 2
maxLength: 8
format: language
pattern: '^[a-z]{2,3}(-[a-zA-Z0-9]{2,4})?$'
minItems: 1
maxItems: 6
- name: replace
in: query
description: >-
If `false`, the operation does not replace the variable references in the `message.text` of each [active
notification](#schema-activeNotification) with the corresponding value from the notification's `values`. The client should perform the
replacement before displaying the message.
schema:
type: boolean
default: true
- name: Accept-Language
in: header
description: >-
An [HTTP `Accept-Language`](https://tools.ietf.org/html/rfc7231#section-5.3.5) request header which specifies one or more languages with
weights. The response will include one string for each combination of group name and string name. This is ignored if `?languages=` query
parameter is used. `Accept-Language` is processed in a similar way as the `language` query parameter.
schema:
type: string
responses:
'200':
description: OK.
content:
application/hal+json:
schema:
$ref: '#/components/schemas/activeNotifications'
application/json:
schema:
$ref: '#/components/schemas/activeNotifications'
'400':
$ref: '#/components/responses/400'
'422':
$ref: '#/components/responses/422'
/notifications:
get:
summary: Return a collection of notifications
description: >-
Return a [paginated](https://developer.apiture.com/docs/concepts/pagination) [sortable](https://developer.apiture.com/docs/concepts/sorting)
[filterable](https://developer.apiture.com/docs/concepts/filtering) [searchable](https://developer.apiture.com/docs/concepts/searching)
collection of notifications. The [links](https://developer.apiture.com/docs/concepts/links) in the response include pagination links.
operationId: getNotifications
security:
- apiKey: []
accessToken:
- data/read
tags:
- Notifications
parameters:
- name: start
in: query
description: The zero-based index of the first notification item to include in this page. The default 0 denotes the beginning of the collection.
schema:
type: integer
format: int64
default: 0
- name: limit
in: query
description: The maximum number of notification representations to return in this page.
schema:
type: integer
format: int32
default: 100
- name: sortBy
in: query
description: 'Optional sort criteria. See [sort criteria format](https://developer.apiture.com/docs/concepts/sorting), such as `?sortBy=field1,-field2`.'
schema:
type: string
- name: expired
in: query
description: Filter definitions whose `expired` property matches the given value.
schema:
type: boolean
- name: dismissed
in: query
description: Filter definitions whose `dismissed` property matches the given value.
schema:
type: boolean
- $ref: '#/components/parameters/typeQueryParam'
- $ref: '#/components/parameters/contextNameQueryParam'
- $ref: '#/components/parameters/contextUriQueryParam'
- $ref: '#/components/parameters/filterQueryParam'
- $ref: '#/components/parameters/qQueryParam'
x-apiture-traits:
sortBy:
- type
- contextName
- expiredAt
- dismissedAt
filter:
dismissed:
filter:
- eq
- ne
expired:
filter:
- eq
- ne
type:
filter:
- eq
- ne
- in
- startsWith
- endsWith
- contains
- search
name:
filter:
- eq
- ne
- in
- startsWith
- endsWith
- contains
- search
expiredAt:
filter:
- lt
- le
- gt
- ge
dismissedAt:
filter:
- lt
- le
- gt
- ge
responses:
'200':
description: OK
content:
application/hal+json:
schema:
$ref: '#/components/schemas/notifications'
application/json:
schema:
$ref: '#/components/schemas/notifications'
'400':
$ref: '#/components/responses/400'
'422':
$ref: '#/components/responses/422'
post:
summary: Create a new notification
description: Create a new notification in the notifications collection.
operationId: createNotification
security:
- apiKey: []
accessToken:
- admin/write
tags:
- Notifications
responses:
'201':
description: Created
headers:
Location:
description: >-
The URI of the new resource. If the URI begins with / it is relative to the API root context. Else, it is a full URI starting with
*`scheme`*`://host`
schema:
type: string
format: uri
ETag:
description: An entity tag which may be passed in the `If-Match` request header for *`PUT`* or *`PATCH`* operations which update the resource.
schema:
type: string
content:
application/hal+json:
schema:
$ref: '#/components/schemas/notification'
application/json:
schema:
$ref: '#/components/schemas/notification'
'400':
$ref: '#/components/responses/400'
requestBody:
content:
application/hal+json:
schema:
$ref: '#/components/schemas/createNotification'
application/json:
schema:
$ref: '#/components/schemas/createNotification'
description: The data necessary to create a new notification.
required: true
'/notifications/{notificationId}':
get:
summary: Fetch a representation of this notification
description: 'Return a [HAL](https://developer.apiture.com/docs/concepts/hal) representation of this notification resource.'
operationId: getNotification
security:
- apiKey: []
accessToken:
- data/read
tags:
- Notifications
parameters:
- $ref: '#/components/parameters/notificationIdPathParam'
- $ref: '#/components/parameters/ifNoneMatchHeaderParam'
responses:
'200':
description: OK
headers:
ETag:
description: >-
The `ETag` response header specifies an entity tag which may be provided in an `If-Match` request header for *`PUT`* or *`PATCH`*
operations which update this notification resource.
schema:
type: string
content:
application/hal+json:
schema:
$ref: '#/components/schemas/notification'
application/json:
schema:
$ref: '#/components/schemas/notification'
'304':
$ref: '#/components/responses/304'
'404':
$ref: '#/components/responses/404Notification'
delete:
summary: Delete this notification resource
description: Delete this notification resource and any resources that are owned by it.
operationId: deleteNotification
security:
- apiKey: []
accessToken:
- admin/delete
tags:
- Notifications
parameters:
- $ref: '#/components/parameters/notificationIdPathParam'
responses:
'204':
$ref: '#/components/responses/204Deleted'
/:
get:
summary: Top-level resources and operations in this API
description: Return links to the top-level resources and operations in this API.
operationId: getApi
responses:
'200':
description: OK
content:
application/hal+json:
schema:
$ref: '#/components/schemas/root'
application/json:
schema:
$ref: '#/components/schemas/root'
tags:
- API
security:
- apiKey: []
/apiDoc:
get:
summary: Return API definition document
description: Return the OpenAPI document that describes this API.
operationId: getApiDoc
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
application/openapi+json;version=2.0:
schema:
type: object
application/openapi+yaml;version=2.0:
schema:
type: object
application/hal+json:
schema:
type: object
tags:
- API
security:
- apiKey: []
x-apiture-errors:
definitionRefNotFound:
description: The referenced notification definition is not found
remediation: Pass a reference to an existing notification definition
notificationRefNotFound:
description: The referenced notification instance is not found
remediation: Pass a reference to an existing notification instance
indicatorAndNotDismissibleMutuallyExclusive:
description: The `indicator` and `notDismissible` properties may not be both true
remediation: 'Choose either indicator or notDismissible, not both'
dismissNotAllowed:
description: Cannot dismiss a notification when the definition is an indicator or is not dismissible
remediation: Do not invoke dismissNotification if the definition is an indicator or not dismissible
idNotMatchPath:
description: 'The `_id` in the request body does not match the {definitionId} path parameter'
remediation: Use the representation from the correct notification definition
definitionExpired:
description: Cannot create new notification instances from an expired notification definition
remediation: Use an unexpired notification definition
mismatchedContextUriTemplate:
description: The request includes a contextUriTemplate that does not match the notification definition
remediation: Create a different notification definition if you need a different contextUriTemplate
definitionMissingContextUriTemplate:
description: The instances contain only context IDs but the definition has no contextUriTemplate
remediation: 'Either define a contextUriTemplate in the notification definition, or include full context URIs in the instances'
cannotCreateInstancesFromGlobalDefinition:
description: Cannot create notification instances for a `global` notification definition
remediation: Use a non-global notification definition to create user-specific notification instances
x-apiture-traits:
- api:
title: Notifications
basePath: notifications
applied: true
links:
- getApi
- getApiDoc
- getDefinitions
- createDefinition
- createGlobalDefinition
- getNotifications
- getActiveNotifications
- security:
baseScope: data
applied: true
- resource:
name: notification
applied: true
excludeMethods:
- put
- post
- patch
- resource:
name: definition
applied: true
components:
schemas:
notificationDefinition:
title: Notification Definition
description: Representation of a notification definition resource.
x-apiture-links:
- rel: 'apiture:expire'
operationId: expireDefinition
- rel: 'apiture:createNotifications'
operationId: createNotifications
example:
_id: 0399abed-fd3d-4830-a88b-30f38b8a365c
_profile: 'https://api.apiture.com/schemas/notifications/notificationDefinition/v1.0.0/profile.json'
type: cdMaturingSoon
contextName: account
indicator: true
notDismissible: false
priority: medium
expired: false
expiresAt: '2020-04-18T12:26:36.375Z'
updatedAt: '2020-04-16T12:00:22.100Z'
message:
text: 'This CD account is maturing on {maturityDate}. Now is a good time to review your account maturity settings.'
imageUri: 'https://cdn.assets.3rdpartybank.com/icons/en/notifications/cdMaturingSoon.png'
values:
maturityDate: '2020-04-09'
_links:
self:
href: /notifications/definitions/0399abed-fd3d-4830-a88b-30f38b8a365c
'apiture:expire':
href: /expiredDefinitions?definition=0399abed-fd3d-4830-a88b-30f38b8a365c
'apiture:createNotifications':
href: /notifications/definitions/0399abed-fd3d-4830-a88b-30f38b8a365c/notifications
x-apiture-composition:
- $ref: '#/components/schemas/summaryNotificationDefinition'
- properties:
- createdAt
- updatedAt
- expired
properties:
_links:
description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
allOf:
- $ref: '#/components/schemas/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](https://developer.apiture.com/docs/concepts/profiles/) 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: '#/components/schemas/error'
type:
description: >-
A programmatic name for the kind of notification this defines, such as `cdMaturingSoon` or `cdInGracePeriod`. Clients may elect to respond
differently or specially to different well-known notification types.
type: string
pattern: '^[a-z][a-zA-Z0-9_$]{1,31}$'
example: announcement
default: announcement
maxLength: 32
message:
description: >-
The default message text template for notification instances. This may be overridden for web or mobile client types with the `webMessage`
or `mobileMessage` properties. A definition must defined either the `message` property or both `webMessage` or `mobileMessage`
properties.
allOf:
- $ref: '#/components/schemas/notificationMessage'
webMessage:
description: >-
The message text template for this notification for web application clients, when using [`GET
/activeNotifications?clientType=web`](#op-activeNotifications. If this is not defined, notifications use `message`.
allOf:
- $ref: '#/components/schemas/notificationMessage'
mobileMessage:
description: >-
The message text template for this notification for mobile application clients, when using [`GET
/activeNotifications?clientType=mobile`](#op-activeNotifications. If this is not defined, notifications use `message`.
allOf:
- $ref: '#/components/schemas/notificationMessage'
values:
description: >-
An optional map of name/value variables to insert into the formatted message. For example, the for message text `We have increased the
rate of your CD from {oldApy}% to {newApy}%.`, the `values` should define `oldApy` and `newApy`:
`{ "oldApy": "1.750", "newApy":
"1.800"}`. These `values` are defaults for instances which do not override `values`.
x-apiture-key: variableName
additionalProperties:
$ref: '#/components/schemas/attributeValue'
priority:
description: The priority of this notification.
allOf:
- $ref: '#/components/schemas/notificationPriority'
default: medium
indicator:
description: >-
If `true`, each notification instantiated from this definition is a visual indicator (a.k.a. badge) rather than a dismissible visual
message, and the [`dismissNotification`](#op-dismissNotification) operation is not allowed. This may not be `true` if `notDismissible` is
true.
type: boolean
default: false
notDismissible:
description: >-
If `true`, each notification instantiated from this definition does not have a UI control to dismiss it, and the
[`dismissNotification`](#op-dismissNotification) operation is not allowed. This may not be `true` if `indicator` is true.
type: boolean
expiresAt:
description: >-
The notification definition's expiration timestamp in [RFC 3339](https://tools.ietf.org/html/rfc3339) UTF format:
`YYYY-MM-DDThh:mm:ss.sssZ`. When the definition expires, all active notifications also expire.
type: string
format: date-time
contextName:
description: >-
A programmatic name of the context for this notification. This could be `global` for a global notification directed at all users, or an
`account` if the notification applies to a banking account, or `user` if the notification applies to a user.
type: string
pattern: '^[a-z][a-zA-Z0-9_$]{1,31}$'
maxLength: 32
contextUriTemplate:
description: >-
An optional URI template for expanding simple identifiers in contexts to full URIs. For example, the value `/accounts/accounts/{id}` will
convert the simple id value `30f38b8a365c` to the URI `/accounts/accounts/30f38b8a365c`. This string must have the substring `{id}` in it.
type: string
maxLength: 2048
contextUri:
description: >-
The URI of a resource that defines the content of this notification, such as the global resource URI,
`https://api.apiture.com/domains/notifications/global`. For non-global notifications, instances supply their own `contextUri` explicitly
or by injecting a `contextId` into the definition's `contextUriTemplate`.
type: string
format: uri
maxLength: 2048
_id:
description: The unique identifier for this notification definition resource. This is an immutable opaque string.
type: string
readOnly: true
maxLength: 128
expired:
description: '`true` if this notification definition''s expiration date-time has passed.'
type: boolean
readOnly: true
createdAt:
description: >-
The the notification definition's creation date-time. This is an [RFC 3369](https://tools.ietf.org/html/rfc3339) formatted date-time
string, `YYYY-MM-DDThh:mm:ss.sssZ`. This is a derived field and is immutable.
type: string
format: date-time
readOnly: true
updatedAt:
description: >-
The notification definition's last update date-time. This is an [RFC 3369](https://tools.ietf.org/html/rfc3339) formatted date-time
string, `YYYY-MM-DDThh:mm:ss.sssZ`. This is a derived field and is immutable.
type: string
format: date-time
readOnly: true
type: object
x-apiture-flattened: true
createNotificationDefinition:
title: Create Notification Definition
description: >-
Representation used to create a new notification definition. The `message` property must be defined or both `webMessage` or `mobileMessage`
properties must be defined.
required:
- contextName
example:
_profile: 'https://api.apiture.com/schemas/notifications/createNotificationDefinition/v1.0.0/profile.json'
type: cdMaturingSoon
contextName: account
indicator: true
priority: medium
message:
text: 'We have increased the rate of your CD from {oldApy}% to {newApy}%.'
imageUri: 'https://cdn.assets.3rdpartybank.com/icons/es/notifications/cdRateIncreased.png'
variants:
es:
text: 'Hemos aumentado la velocidad de su CD de {oldApy}% a {newApy}%.'
imageUri: 'https://cdn.assets.3rdpartybank.com/icons/es/notifications/cdRateIncreased.png'
fr:
text: 'Nous avons augment\u00e9 le taux de votre CD de {oldApy}% \00e0 {newApy}%.'
imageUri: 'https://cdn.assets.3rdpartybank.com/icons/fr/notifications/cdRateIncreased.png'
values:
oldApy: '1.750'
newApy: 1.8.0
x-apiture-composition:
- $ref: '#/components/schemas/abstractRequest'
- $ref: '#/components/schemas/notificationDefinitionFields'
properties:
_links:
description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
allOf:
- $ref: '#/components/schemas/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](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.'
type: string
format: uri
type:
description: >-
A programmatic name for the kind of notification this defines, such as `cdMaturingSoon` or `cdInGracePeriod`. Clients may elect to respond
differently or specially to different well-known notification types.
type: string
pattern: '^[a-z][a-zA-Z0-9_$]{1,31}$'
example: announcement
default: announcement
maxLength: 32
message:
description: >-
The default message text template for notification instances. This may be overridden for web or mobile client types with the `webMessage`
or `mobileMessage` properties. A definition must defined either the `message` property or both `webMessage` or `mobileMessage`
properties.
allOf:
- $ref: '#/components/schemas/notificationMessage'
webMessage:
description: >-
The message text template for this notification for web application clients, when using [`GET
/activeNotifications?clientType=web`](#op-activeNotifications. If this is not defined, notifications use `message`.
allOf:
- $ref: '#/components/schemas/notificationMessage'
mobileMessage:
description: >-
The message text template for this notification for mobile application clients, when using [`GET
/activeNotifications?clientType=mobile`](#op-activeNotifications. If this is not defined, notifications use `message`.
allOf:
- $ref: '#/components/schemas/notificationMessage'
values:
description: >-
An optional map of name/value variables to insert into the formatted message. For example, the for message text `We have increased the
rate of your CD from {oldApy}% to {newApy}%.`, the `values` should define `oldApy` and `newApy`:
`{ "oldApy": "1.750", "newApy":
"1.800"}`. These `values` are defaults for instances which do not override `values`.
x-apiture-key: variableName
additionalProperties:
$ref: '#/components/schemas/attributeValue'
priority:
description: The priority of this notification.
allOf:
- $ref: '#/components/schemas/notificationPriority'
default: medium
indicator:
description: >-
If `true`, each notification instantiated from this definition is a visual indicator (a.k.a. badge) rather than a dismissible visual
message, and the [`dismissNotification`](#op-dismissNotification) operation is not allowed. This may not be `true` if `notDismissible` is
true.
type: boolean
default: false
notDismissible:
description: >-
If `true`, each notification instantiated from this definition does not have a UI control to dismiss it, and the
[`dismissNotification`](#op-dismissNotification) operation is not allowed. This may not be `true` if `indicator` is true.
type: boolean
expiresAt:
description: >-
The notification definition's expiration timestamp in [RFC 3339](https://tools.ietf.org/html/rfc3339) UTF format:
`YYYY-MM-DDThh:mm:ss.sssZ`. When the definition expires, all active notifications also expire.
type: string
format: date-time
contextName:
description: >-
A programmatic name of the context for this notification. This could be `global` for a global notification directed at all users, or an
`account` if the notification applies to a banking account, or `user` if the notification applies to a user.
type: string
pattern: '^[a-z][a-zA-Z0-9_$]{1,31}$'
maxLength: 32
contextUriTemplate:
description: >-
An optional URI template for expanding simple identifiers in contexts to full URIs. For example, the value `/accounts/accounts/{id}` will
convert the simple id value `30f38b8a365c` to the URI `/accounts/accounts/30f38b8a365c`. This string must have the substring `{id}` in it.
type: string
maxLength: 2048
contextUri:
description: >-
The URI of a resource that defines the content of this notification, such as the global resource URI,
`https://api.apiture.com/domains/notifications/global`. For non-global notifications, instances supply their own `contextUri` explicitly
or by injecting a `contextId` into the definition's `contextUriTemplate`.
type: string
format: uri
maxLength: 2048
type: object
x-apiture-flattened: true
createGlobalNotificationDefinition:
title: Create Global Notification Definition
description: >-
Representation used to create a new global notification definition. The `message` property must be defined or both `webMessage` or
`mobileMessage` properties must be defined.
example:
_profile: 'https://api.apiture.com/schemas/notifications/createGlobalNotificationDefinition/v1.0.0/profile.json'
priority: high
message:
text: >-
The bank branch at {address} will be closed until September 17 due to Hurricane Heathcliff. See [our
announcement](http://www.3rdpartybank.com/announcements/heathcliff) for more information.
imageUri: 'https://cdn.assets.3rdpartybank.com/icons/en/hurricane-flag.png'
variants:
es:
text: >-
La sucursal bancaria en {address} estar\u00e1 cerrada hasta el 17 de septiembre debido al hurac\u00e1n Heathcliff. Consulte [nuestro
anuncio](http://www.3rdpartybank.com/announcements/heathcliff) para obtener m\u00e1s informaci\u00f3n.
imageUri: 'https://cdn.assets.3rdpartybank.com/icons/es/hurricane-flag.png'
values:
address: 123 N. Main St. Wilmington
x-apiture-composition:
- $ref: '#/components/schemas/abstractRequest'
- $ref: '#/components/schemas/sharedNotificationDefinitionFields'
properties:
_links:
description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
allOf:
- $ref: '#/components/schemas/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](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.'
type: string
format: uri
type:
description: >-
A programmatic name for the kind of notification this defines, such as `cdMaturingSoon` or `cdInGracePeriod`. Clients may elect to respond
differently or specially to different well-known notification types.
type: string
pattern: '^[a-z][a-zA-Z0-9_$]{1,31}$'
example: announcement
default: announcement
maxLength: 32
message:
description: >-
The default message text template for notification instances. This may be overridden for web or mobile client types with the `webMessage`
or `mobileMessage` properties. A definition must defined either the `message` property or both `webMessage` or `mobileMessage`
properties.
allOf:
- $ref: '#/components/schemas/notificationMessage'
webMessage:
description: >-
The message text template for this notification for web application clients, when using [`GET
/activeNotifications?clientType=web`](#op-activeNotifications. If this is not defined, notifications use `message`.
allOf:
- $ref: '#/components/schemas/notificationMessage'
mobileMessage:
description: >-
The message text template for this notification for mobile application clients, when using [`GET
/activeNotifications?clientType=mobile`](#op-activeNotifications. If this is not defined, notifications use `message`.
allOf:
- $ref: '#/components/schemas/notificationMessage'
values:
description: >-
An optional map of name/value variables to insert into the formatted message. For example, the for message text `We have increased the
rate of your CD from {oldApy}% to {newApy}%.`, the `values` should define `oldApy` and `newApy`:
`{ "oldApy": "1.750", "newApy":
"1.800"}`. These `values` are defaults for instances which do not override `values`.
x-apiture-key: variableName
additionalProperties:
$ref: '#/components/schemas/attributeValue'
priority:
description: The priority of this notification.
allOf:
- $ref: '#/components/schemas/notificationPriority'
default: medium
indicator:
description: >-
If `true`, each notification instantiated from this definition is a visual indicator (a.k.a. badge) rather than a dismissible visual
message, and the [`dismissNotification`](#op-dismissNotification) operation is not allowed. This may not be `true` if `notDismissible` is
true.
type: boolean
default: false
notDismissible:
description: >-
If `true`, each notification instantiated from this definition does not have a UI control to dismiss it, and the
[`dismissNotification`](#op-dismissNotification) operation is not allowed. This may not be `true` if `indicator` is true.
type: boolean
expiresAt:
description: >-
The notification definition's expiration timestamp in [RFC 3339](https://tools.ietf.org/html/rfc3339) UTF format:
`YYYY-MM-DDThh:mm:ss.sssZ`. When the definition expires, all active notifications also expire.
type: string
format: date-time
type: object
x-apiture-flattened: true
sharedNotificationDefinitionFields:
title: Notification Definition Fields
x-apiture-fragment: true
description: Common fields used to build notification definition schemas.
properties:
type:
description: >-
A programmatic name for the kind of notification this defines, such as `cdMaturingSoon` or `cdInGracePeriod`. Clients may elect to respond
differently or specially to different well-known notification types.
type: string
pattern: '^[a-z][a-zA-Z0-9_$]{1,31}$'
example: announcement
default: announcement
maxLength: 32
message:
description: >-
The default message text template for notification instances. This may be overridden for web or mobile client types with the `webMessage`
or `mobileMessage` properties. A definition must defined either the `message` property or both `webMessage` or `mobileMessage`
properties.
allOf:
- $ref: '#/components/schemas/notificationMessage'
webMessage:
description: >-
The message text template for this notification for web application clients, when using [`GET
/activeNotifications?clientType=web`](#op-activeNotifications. If this is not defined, notifications use `message`.
allOf:
- $ref: '#/components/schemas/notificationMessage'
mobileMessage:
description: >-
The message text template for this notification for mobile application clients, when using [`GET
/activeNotifications?clientType=mobile`](#op-activeNotifications. If this is not defined, notifications use `message`.
allOf:
- $ref: '#/components/schemas/notificationMessage'
values:
description: >-
An optional map of name/value variables to insert into the formatted message. For example, the for message text `We have increased the
rate of your CD from {oldApy}% to {newApy}%.`, the `values` should define `oldApy` and `newApy`:
`{ "oldApy": "1.750", "newApy":
"1.800"}`. These `values` are defaults for instances which do not override `values`.
x-apiture-key: variableName
additionalProperties:
$ref: '#/components/schemas/attributeValue'
priority:
description: The priority of this notification.
allOf:
- $ref: '#/components/schemas/notificationPriority'
default: medium
indicator:
description: >-
If `true`, each notification instantiated from this definition is a visual indicator (a.k.a. badge) rather than a dismissible visual
message, and the [`dismissNotification`](#op-dismissNotification) operation is not allowed. This may not be `true` if `notDismissible` is
true.
type: boolean
default: false
notDismissible:
description: >-
If `true`, each notification instantiated from this definition does not have a UI control to dismiss it, and the
[`dismissNotification`](#op-dismissNotification) operation is not allowed. This may not be `true` if `indicator` is true.
type: boolean
expiresAt:
description: >-
The notification definition's expiration timestamp in [RFC 3339](https://tools.ietf.org/html/rfc3339) UTF format:
`YYYY-MM-DDThh:mm:ss.sssZ`. When the definition expires, all active notifications also expire.
type: string
format: date-time
type: object
x-apiture-flattened: true
summaryNotificationDefinition:
title: Notification Definition Summary
description: >-
Summary representation of a definition resource in notification definitions collections. This representation normally does not contain any
`_embedded` objects. If needed, call the `GET` operation on the item's `self` link to get `_embedded` objects.
example:
_id: 0399abed-fd3d-4830-a88b-30f38b8a365c
_profile: 'https://api.apiture.com/schemas/notifications/summaryNotificationDefinition/v1.0.0/profile.json'
type: cdMaturingSoon
contextName: account
indicator: true
notDismissible: false
expired: false
expiresAt: '2020-04-18T12:15:21.375Z'
message:
text: 'This CD account is maturing on {maturityDate}. Now is a good time to review your account maturity settings.'
imageUri: 'https://cdn.assets.3rdpartybank.com/icons/en/notifications/cdMaturingSoon.png'
values:
maturityDate: '2020-04-09'
_links:
self:
href: /notifications/definitions/0399abed-fd3d-4830-a88b-30f38b8a365c
x-apiture-composition:
- $ref: '#/components/schemas/abstractResource'
- $ref: '#/components/schemas/notificationDefinitionFields'
- properties:
- _id
- expired
properties:
_links:
description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
allOf:
- $ref: '#/components/schemas/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](https://developer.apiture.com/docs/concepts/profiles/) 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: '#/components/schemas/error'
type:
description: >-
A programmatic name for the kind of notification this defines, such as `cdMaturingSoon` or `cdInGracePeriod`. Clients may elect to respond
differently or specially to different well-known notification types.
type: string
pattern: '^[a-z][a-zA-Z0-9_$]{1,31}$'
example: announcement
default: announcement
maxLength: 32
message:
description: >-
The default message text template for notification instances. This may be overridden for web or mobile client types with the `webMessage`
or `mobileMessage` properties. A definition must defined either the `message` property or both `webMessage` or `mobileMessage`
properties.
allOf:
- $ref: '#/components/schemas/notificationMessage'
webMessage:
description: >-
The message text template for this notification for web application clients, when using [`GET
/activeNotifications?clientType=web`](#op-activeNotifications. If this is not defined, notifications use `message`.
allOf:
- $ref: '#/components/schemas/notificationMessage'
mobileMessage:
description: >-
The message text template for this notification for mobile application clients, when using [`GET
/activeNotifications?clientType=mobile`](#op-activeNotifications. If this is not defined, notifications use `message`.
allOf:
- $ref: '#/components/schemas/notificationMessage'
values:
description: >-
An optional map of name/value variables to insert into the formatted message. For example, the for message text `We have increased the
rate of your CD from {oldApy}% to {newApy}%.`, the `values` should define `oldApy` and `newApy`:
`{ "oldApy": "1.750", "newApy":
"1.800"}`. These `values` are defaults for instances which do not override `values`.
x-apiture-key: variableName
additionalProperties:
$ref: '#/components/schemas/attributeValue'
priority:
description: The priority of this notification.
allOf:
- $ref: '#/components/schemas/notificationPriority'
default: medium
indicator:
description: >-
If `true`, each notification instantiated from this definition is a visual indicator (a.k.a. badge) rather than a dismissible visual
message, and the [`dismissNotification`](#op-dismissNotification) operation is not allowed. This may not be `true` if `notDismissible` is
true.
type: boolean
default: false
notDismissible:
description: >-
If `true`, each notification instantiated from this definition does not have a UI control to dismiss it, and the
[`dismissNotification`](#op-dismissNotification) operation is not allowed. This may not be `true` if `indicator` is true.
type: boolean
expiresAt:
description: >-
The notification definition's expiration timestamp in [RFC 3339](https://tools.ietf.org/html/rfc3339) UTF format:
`YYYY-MM-DDThh:mm:ss.sssZ`. When the definition expires, all active notifications also expire.
type: string
format: date-time
contextName:
description: >-
A programmatic name of the context for this notification. This could be `global` for a global notification directed at all users, or an
`account` if the notification applies to a banking account, or `user` if the notification applies to a user.
type: string
pattern: '^[a-z][a-zA-Z0-9_$]{1,31}$'
maxLength: 32
contextUriTemplate:
description: >-
An optional URI template for expanding simple identifiers in contexts to full URIs. For example, the value `/accounts/accounts/{id}` will
convert the simple id value `30f38b8a365c` to the URI `/accounts/accounts/30f38b8a365c`. This string must have the substring `{id}` in it.
type: string
maxLength: 2048
contextUri:
description: >-
The URI of a resource that defines the content of this notification, such as the global resource URI,
`https://api.apiture.com/domains/notifications/global`. For non-global notifications, instances supply their own `contextUri` explicitly
or by injecting a `contextId` into the definition's `contextUriTemplate`.
type: string
format: uri
maxLength: 2048
_id:
description: The unique identifier for this notification definition resource. This is an immutable opaque string.
type: string
readOnly: true
maxLength: 128
expired:
description: '`true` if this notification definition''s expiration date-time has passed.'
type: boolean
readOnly: true
type: object
x-apiture-flattened: true
notificationDefinitions:
title: Notification Definition Collection
description: >-
Collection of notification definitions. The items in the collection are ordered in the `_embedded.items` array; the `name` is `definitions`.
The top-level `_links` object may contain pagination links (`self`, `next`, `prev`, `first`, `last`, `collection`).
x-apiture-links:
- rel: 'apiture:expireDefinition'
operationId: expireDefinition
example:
_profile: 'https://api.apiture.com/schemas/notifications/notificationDefinitions/v1.0.0/profile.json'
name: definitions
start: 10
limit: 10
count: 67
_links:
self:
href: /notifications/definitions?start=10&limit=10
first:
href: /notifications/definitions?start=0&limit=10
next:
href: /notifications/definitions?start=20&limit=10
collection:
href: /notifications/definitions
_embedded:
items:
_id: 0399abed-fd3d-4830-a88b-30f38b8a365c
_profile: 'https://api.apiture.com/schemas/notifications/summaryNotificationDefinition/v1.0.0/profile.json'
type: cdMaturingSoon
contextName: account
indicator: true
notDismissible: false
priority: medium
message:
text: 'This CD account is maturing on {maturityDate}. Now is a good time to review your account maturity settings.'
imageUri: 'https://cdn.assets.3rdpartybank.com/icons/en/notifications/cdMaturingSoon.png'
values:
maturityDate: '2020-04-09'
_links:
self:
href: /notifications/definitions/0399abed-fd3d-4830-a88b-30f38b8a365c
'apiture:expire':
href: /expiredDefinitions?definition=0399abed-fd3d-4830-a88b-30f38b8a365c
'apiture:createNotifications':
href: /notifications/definitions/0399abed-fd3d-4830-a88b-30f38b8a365c/notifications
x-apiture-composition:
- $ref: '#/components/schemas/collection'
- properties:
- _embedded
properties:
_links:
description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
allOf:
- $ref: '#/components/schemas/links'
_embedded:
type: object
description: Embedded objects.
properties:
items:
description: An array containing a page of definition items.
type: array
items:
$ref: '#/components/schemas/summaryNotificationDefinition'
_profile:
description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) 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: '#/components/schemas/error'
count:
description: >-
The number of items in the collection. This value is _optional_ and may be omitted if the count is not computable efficiently. If a filter
is applied to the collection (either implicitly or explicitly), the count, if present, indicates the number of items that satisfy the
filter.
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
type: object
x-apiture-flattened: true
instances:
title: Notification Instances
description: |-
Collection of instances to create and add to a notification definition.
Each instance contains properties to create an notification instance
from this definition, each with their own context, user, and optional expiration date-time
and optional values to inject into the message
The request also contains a `contextUriTemplate`
to map a context ID to a URI, so that thousands of contexts can be expressed in a more concise
notation, consisting of just the IDs instead of thousands of URIs.
Thus, the caller does not have to build full URIs.
Message bodies are limited to 20,000 instances per call. If a caller need to create
more notifications, it should send multiple requests.
example:
_profile: 'https://api.apiture.com/schemas/notifications/instances/v1.0.0/profile.json'
contextUriTemplate: '/accounts/accounts/{id}'
instances:
- contextId: 0399abed-fd3d-4830-a88b-30f38b8a365c
userIds:
- 82535922-335f-4c95-8000-c663a50aec9c
- 7131b08f-2c47-4c23-a4ad-fb31d895acb3
- 9cdbae90-a120-4a71-8314-d0f6051c86fa
expiresAt: '2020-05-08T14:00:00.00Z'
- contextId: 4c1e7436-14cb-4434-a46e-9d7b4e3f02ea
userIds:
- 1cbdd896-0730-4a7d-af68-1834de0cfe84
- c433df56-b9ef-44ed-bcb8-52bbfb4df5f8
expiresAt: '2020-05-10T14:00:00.00Z'
values:
oldApy: '1.750'
newApy: 1.8.0
x-apiture-composition:
- $ref: '#/components/schemas/abstractRequest'
- properties:
- contextUriTemplate
- instances
properties:
_links:
description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
allOf:
- $ref: '#/components/schemas/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](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.'
type: string
format: uri
contextUriTemplate:
description: >-
An optional URI template for expanding simple `contextId` in each of the `instances` items to URIs. If used, this string must have the
substring `{id}` in it, It can be just a partial URI path or a compete URI. For example, for the template
`https://api.3rdparty.bank/accounts/accounts/{id}` the 'contextId' value `30f38b8a365c` maps to the URI
`https://api.3rdparty.bank/accounts/accounts/30f38b8a365c`.
type: string
example: '/accounts/accounts/{id}'
pattern: '.*{id}.*'
maxLength: 2048
instances:
description: >-
An array containing a page of notification instance items. Due to request body size limits, call this multiple times to create more than
20,000 notification instances.
type: array
maxItems: 20000
items:
$ref: '#/components/schemas/instance'
type: object
x-apiture-flattened: true
instance:
title: Notification Instance
description: >-
Values for creating notification instances for a definition. Each instance must contain either a `contextId` or a `contextUri`. Using
`userIds`, one `instance` item create multiple notification instances.
required:
- userIds
properties:
contextId:
description: 'The `_id` of a resource, such as the ID of an account. The containing `instances` resource must define the `contextUriTemplate`.'
type: string
example: d545e39f-c64f-49c1-9777-2ee1ff75e61f
maxLength: 48
contextUri:
description: The URI of a resource. This may be a partial URI or a full URI.
type: string
format: uri
example: /accounts/accounts/d545e39f-c64f-49c1-9777-2ee1ff75e61f
maxLength: 2048
userIds:
description: A notification is created for each user identified by these `userIds`. Each unique item is the `_id` of a User resource.
type: array
minLength: 1
uniqueItems: true
items:
description: The `_id` of a use resource.
type: string
maxLength: 48
example:
- 82535922-335f-4c95-8000-c663a50aec9c
values:
description: >-
An optional map of name/value variables to insert into the formatted message. For example, the for message tex `We have increased the rate
of your CD from {oldApy}% to {newApy}%.`, the values should define `oldApy` and `newApy`:
`{ "oldApy": "1.750", "newApy": "1.800"}`. If
omitted, the instance uses the `values` of the notification definition.
x-apiture-key: variableName
additionalProperties:
$ref: '#/components/schemas/attributeValue'
expiresAt:
description: >-
The notification's expiration timestamp in [RFC 3339](https://tools.ietf.org/html/rfc3339) UTF format: `YYYY-MM-DDThh:mm:ss.sssZ`. If
omitted, the instance uses the `expiresAt` of the notification definition.
type: string
format: date-time
example:
contextId: 0399abed-fd3d-4830-a88b-30f38b8a365c
contextUri: /accounts/account/17434982-0419-4047-9855-389dac6970f7
userIds:
- 82535922-335f-4c95-8000-c663a50aec9c
- 191c5118-b6d5-4cc7-92bd-3eede737513e
type: object
x-apiture-flattened: true
notification:
title: Notification
description: >-
Representation of a notification resource. The embedded `_embedded.definition` notification definition contains the notification's `type`,
`contextName`, `priority` and other properties (these properties are shared with all notifications defined by that definition.) The
`_embedded.definition` is always included in the [`getNotification`](#op-getNotification) response as well as in the notifications in the
[`getActiveNotifications`](#op-getActiveNotifications) response.
**Note**: This representation does not contain the `message` property; use [`getActiveNotifications`](#op-getActiveNotifications) to obtain
renderable [active notifications](#schema-activeNotification).
example:
_id: 0399abed-fd3d-4830-a88b-30f38b8a365c
_profile: 'https://api.apiture.com/schemas/notifications/notification/v1.0.0/profile.json'
dismissed: true
dismissedAt: '2020-04-02T11:01:31.375Z'
expired: false
expiresAt: '2020-04-T21:00:00.000'
_links:
self:
href: /notifications/notifications/0399abed-fd3d-4830-a88b-30f38b8a365c
'apiture:dismiss':
href: /dismissedNotifications?notification=0399abed-fd3d-4830-a88b-30f38b8a365c
'apiture:expire':
href: /expiredNotifications?notification=0399abed-fd3d-4830-a88b-30f38b8a365c
'apiture:definition':
href: /notifications/definitions/00b68bc7-497c-4ce5-b8bd-47c6a8f33c22
_embedded:
definition:
_id: 0399abed-fd3d-4830-a88b-30f38b8a365c
_profile: 'https://api.apiture.com/schemas/notifications/notificationDefinition/v1.0.0/profile.json'
type: cdMaturingSoon
contextName: account
indicator: true
priority: medium
message:
text: 'This CD account is maturing on {maturityDate}. Now is a good time to review your account maturity settings.'
imageUri: 'https://cdn.assets.3rdpartybank.com/icons/en/notifications/cdMaturingSoon.png'
values:
maturityDate: '2020-04-09'
_links:
self:
href: /notifications/definitions/0399abed-fd3d-4830-a88b-30f38b8a365c
x-apiture-links:
- rel: 'apiture:dismiss'
operationId: dismissNotification
- rel: 'apiture:expire'
operationId: expireNotification
- rel: 'apiture:context'
method: GET
title: Context
description: The target resource or context associate with this notification.
- rel: 'apiture:definition'
description: The definition used to create this notification.
operationId: getDefinition
x-apiture-composition:
- $ref: '#/components/schemas/summaryNotification'
- properties:
- values
- expiresAt
- dismissedAt
- _embedded
properties:
_links:
description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
allOf:
- $ref: '#/components/schemas/links'
_embedded:
description: Embedded objects
readOnly: true
allOf:
- $ref: '#/components/schemas/notificationEmbeddedObjects'
_profile:
description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) 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: '#/components/schemas/error'
contextUri:
description: >-
The URI of a resource that defines the content of this notification, such as an account, a user, or the global resource URI,
`https://api.apiture.com/domains/notifications/global`. The URI need not have the `https://hostname` portion but must either start with
`https://{hostname}/` _or_ be the full resource path starting with a `/`.
type: string
maxLength: 2048
format: uri
example: /accounts/accounts/0a4511d1-1b63-4640-af0c-d4cdd6c88d37
_id:
description: The unique identifier for this notification resource. This is an immutable opaque string.
type: string
maxLength: 48
readOnly: true
dismissed:
description: '`true` if this the user has dismissed this notification.'
type: boolean
readOnly: true
notDismissible:
description: '`true` if this the notification definition is `notDismissible`.'
type: boolean
readOnly: true
expired:
description: '`true` if this notification''s expiration date-time has passed.'
type: boolean
readOnly: true
values:
description: >-
An optional map of name/value variables to insert into the formatted message. For example, the for message tex `We have increased the rate
of your CD from {oldApy}% to {newApy}%.`, the values should define `oldApy` and `newApy`:
`{ "oldApy": "1.750", "newApy": "1.800"}`. If
omitted, the instance uses the `values` of the notification definition.
readOnly: true
x-apiture-key: variableName
additionalProperties:
$ref: '#/components/schemas/attributeValue'
expiresAt:
description: >-
The notification's expiration timestamp1 in [RFC 3339](https://tools.ietf.org/html/rfc3339) UTF format: `YYYY-MM-DDThh:mm:ss.sssZ`. If
omitted, the instance uses the `expiresAt` of the notification definition.
readOnly: true
type: string
format: date-time
dismissedAt:
description: The date/time the user dismissed this notification.
type: string
readOnly: true
format: date-time
type: object
x-apiture-flattened: true
activeNotification:
title: Active Notification
description: Representation of an active notification resource for a client type (web or mobile) and user language(s) preference.
example:
_id: 0399abed-fd3d-4830-a88b-30f38b8a365c
_profile: 'https://api.apiture.com/schemas/notifications/activeNotification/v1.0.0/profile.json'
dismissed: false
dismissedAt: '2020-04-02T11:01:31.375Z'
expired: false
expiresAt: '2020-04-T21:00:00.000'
message:
text: 'This CD account is maturing on {maturityDate}. Now is a good time to review your account maturity settings.'
imageUri: 'https://cdn.assets.3rdpartybank.com/icons/en/notifications/cdMaturingSoon.png'
_links:
self:
href: /notifications/notifications/0399abed-fd3d-4830-a88b-30f38b8a365c
'apiture:dismiss':
href: /dismissedNotifications?notification=0399abed-fd3d-4830-a88b-30f38b8a365c
'apiture:definition':
href: /notifications/definitions/00b68bc7-497c-4ce5-b8bd-47c6a8f33c22
_embedded:
definition:
_id: 0399abed-fd3d-4830-a88b-30f38b8a365c
_profile: 'https://api.apiture.com/schemas/notifications/notificationDefinition/v1.0.0/profile.json'
type: cdMaturingSoon
contextName: account
indicator: true
priority: medium
message:
text: This CD account is maturing on 2020-04-09. Now is a good time to review your account maturity settings.
imageUri: 'https://cdn.assets.3rdpartybank.com/icons/en/notifications/cdMaturingSoon.png'
values:
maturityDate: '2020-04-09'
_links:
self:
href: /notifications/definitions/0399abed-fd3d-4830-a88b-30f38b8a365c
x-apiture-links:
- rel: 'apiture:dismiss'
operationId: dismissNotification
- rel: 'apiture:definition'
description: The definition used to create this notification.
operationId: getDefinition
x-apiture-composition:
- $ref: '#/components/schemas/summaryNotification'
- properties:
- message
- _embedded
properties:
_links:
description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
allOf:
- $ref: '#/components/schemas/links'
_embedded:
description: Embedded objects
allOf:
- $ref: '#/components/schemas/notificationEmbeddedObjects'
_profile:
description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) 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: '#/components/schemas/error'
contextUri:
description: >-
The URI of a resource that defines the content of this notification, such as an account, a user, or the global resource URI,
`https://api.apiture.com/domains/notifications/global`. The URI need not have the `https://hostname` portion but must either start with
`https://{hostname}/` _or_ be the full resource path starting with a `/`.
type: string
maxLength: 2048
format: uri
example: /accounts/accounts/0a4511d1-1b63-4640-af0c-d4cdd6c88d37
_id:
description: The unique identifier for this notification resource. This is an immutable opaque string.
type: string
maxLength: 48
readOnly: true
dismissed:
description: '`true` if this the user has dismissed this notification.'
type: boolean
readOnly: true
notDismissible:
description: '`true` if this the notification definition is `notDismissible`.'
type: boolean
readOnly: true
expired:
description: '`true` if this notification''s expiration date-time has passed.'
type: boolean
readOnly: true
message:
description: >-
The message text for this notification, derived from the notification definition's `message` or `webMessage` or `mobileMessage`, as per
the `clientType` and `languages` query parameter on [`getActiveNotifications`](#op-getActiveNotifications). The
[`getActiveNotifications`](#op-getActiveNotifications) operation also replaces variables in the message text template with the values in
the `values` object.
readOnly: true
allOf:
- $ref: '#/components/schemas/notificationMessage'
type: object
x-apiture-flattened: true
notificationEmbeddedObjects:
title: Notification Embedded Objects
description: Nested objects for a notification instance.
type: object
properties:
definition:
description: The notification definition for this notification.
type: object
allOf:
- $ref: '#/components/schemas/notificationDefinition'
x-apiture-flattened: true
notificationPriority:
title: Notification Priority
description: The priority of a notification.
type: string
maxLength: 8
x-apiture-enum: notificationPriority
enum:
- low
- medium
- high
x-apiture-flattened: true
notificationDefinitionFields:
title: Notification Definition Fields
x-apiture-fragment: true
description: Common fields of the notification definition resource used to build other model schemas.
x-apiture-composition:
- $ref: '#/components/schemas/sharedNotificationDefinitionFields'
- properties:
- contextName
- contextUriTemplate
- contextUri
properties:
type:
description: >-
A programmatic name for the kind of notification this defines, such as `cdMaturingSoon` or `cdInGracePeriod`. Clients may elect to respond
differently or specially to different well-known notification types.
type: string
pattern: '^[a-z][a-zA-Z0-9_$]{1,31}$'
example: announcement
default: announcement
maxLength: 32
message:
description: >-
The default message text template for notification instances. This may be overridden for web or mobile client types with the `webMessage`
or `mobileMessage` properties. A definition must defined either the `message` property or both `webMessage` or `mobileMessage`
properties.
allOf:
- $ref: '#/components/schemas/notificationMessage'
webMessage:
description: >-
The message text template for this notification for web application clients, when using [`GET
/activeNotifications?clientType=web`](#op-activeNotifications. If this is not defined, notifications use `message`.
allOf:
- $ref: '#/components/schemas/notificationMessage'
mobileMessage:
description: >-
The message text template for this notification for mobile application clients, when using [`GET
/activeNotifications?clientType=mobile`](#op-activeNotifications. If this is not defined, notifications use `message`.
allOf:
- $ref: '#/components/schemas/notificationMessage'
values:
description: >-
An optional map of name/value variables to insert into the formatted message. For example, the for message text `We have increased the
rate of your CD from {oldApy}% to {newApy}%.`, the `values` should define `oldApy` and `newApy`:
`{ "oldApy": "1.750", "newApy":
"1.800"}`. These `values` are defaults for instances which do not override `values`.
x-apiture-key: variableName
additionalProperties:
$ref: '#/components/schemas/attributeValue'
priority:
description: The priority of this notification.
allOf:
- $ref: '#/components/schemas/notificationPriority'
default: medium
indicator:
description: >-
If `true`, each notification instantiated from this definition is a visual indicator (a.k.a. badge) rather than a dismissible visual
message, and the [`dismissNotification`](#op-dismissNotification) operation is not allowed. This may not be `true` if `notDismissible` is
true.
type: boolean
default: false
notDismissible:
description: >-
If `true`, each notification instantiated from this definition does not have a UI control to dismiss it, and the
[`dismissNotification`](#op-dismissNotification) operation is not allowed. This may not be `true` if `indicator` is true.
type: boolean
expiresAt:
description: >-
The notification definition's expiration timestamp in [RFC 3339](https://tools.ietf.org/html/rfc3339) UTF format:
`YYYY-MM-DDThh:mm:ss.sssZ`. When the definition expires, all active notifications also expire.
type: string
format: date-time
contextName:
description: >-
A programmatic name of the context for this notification. This could be `global` for a global notification directed at all users, or an
`account` if the notification applies to a banking account, or `user` if the notification applies to a user.
type: string
pattern: '^[a-z][a-zA-Z0-9_$]{1,31}$'
maxLength: 32
contextUriTemplate:
description: >-
An optional URI template for expanding simple identifiers in contexts to full URIs. For example, the value `/accounts/accounts/{id}` will
convert the simple id value `30f38b8a365c` to the URI `/accounts/accounts/30f38b8a365c`. This string must have the substring `{id}` in it.
type: string
maxLength: 2048
contextUri:
description: >-
The URI of a resource that defines the content of this notification, such as the global resource URI,
`https://api.apiture.com/domains/notifications/global`. For non-global notifications, instances supply their own `contextUri` explicitly
or by injecting a `contextId` into the definition's `contextUriTemplate`.
type: string
format: uri
maxLength: 2048
type: object
x-apiture-flattened: true
notificationFields:
title: Notification Fields
x-apiture-fragment: true
description: Common fields of the notification resource used to build other model schemas.
properties:
contextUri:
description: >-
The URI of a resource that defines the content of this notification, such as an account, a user, or the global resource URI,
`https://api.apiture.com/domains/notifications/global`. The URI need not have the `https://hostname` portion but must either start with
`https://{hostname}/` _or_ be the full resource path starting with a `/`.
type: string
maxLength: 2048
format: uri
example: /accounts/accounts/0a4511d1-1b63-4640-af0c-d4cdd6c88d37
type: object
x-apiture-flattened: true
notificationMessage:
title: Notification Message
description: 'The presentation elements of a notification message: the text, image icon URL, and language variants for the text and image.'
example:
text: 'We have increased the rate of your CD from {oldApy}% to {newApy}%.'
imageUri: 'https://cdn.assets.3rdpartybank.com/icons/en/notifications/cdRateIncreased.png'
variants:
es:
text: 'Hemos aumentado la velocidad de su CD de {oldApy}% a {newApy}%.'
imageUri: 'https://cdn.assets.3rdpartybank.com/icons/es/notifications/cdRateIncreased.png'
fr:
text: 'Nous avons augment\u00e9 le taux de votre CD de {oldApy}% \00e0 {newApy}%.'
imageUri: 'https://cdn.assets.3rdpartybank.com/icons/fr/notifications/cdRateIncreased.png'
x-apiture-composition:
- $ref: '#/components/schemas/simpleMessage'
- properties:
- variants
properties:
text:
description: >-
A notification message in [Github Flavored Markdown](https://help.github.com/articles/basic-writing-and-formatting-syntax/). The text may
contain variable references (identifiers in braces such as {oldApy}) which are replaced by corresponding `values` from the notification
instance or definition. In the example, the `values` must define the variables `oldApy` and `newApy`.
type: string
maxLength: 4096
minLength: 1
format: markdown
example: 'We have increased the rate of your CD from {oldApy}% to {newApy}%.'
imageUri:
description: The URL of an icon or visual representation of this notification or notification definition.
type: string
format: uri
maxLength: 2048
variants:
description: >-
The language-specific variants of this message text. The keys in this object are [RFC
7231](https://tools.ietf.org/html/rfc7231#section-3.1.3.1) language codes.
x-apiture-key: languageCode
type: object
additionalProperties:
$ref: '#/components/schemas/simpleMessage'
type: object
x-apiture-flattened: true
simpleMessage:
title: Notification Message
description: The message and optional image (icon) URI for a notification message.
required:
- text
properties:
text:
description: >-
A notification message in [Github Flavored Markdown](https://help.github.com/articles/basic-writing-and-formatting-syntax/). The text may
contain variable references (identifiers in braces such as {oldApy}) which are replaced by corresponding `values` from the notification
instance or definition. In the example, the `values` must define the variables `oldApy` and `newApy`.
type: string
maxLength: 4096
minLength: 1
format: markdown
example: 'We have increased the rate of your CD from {oldApy}% to {newApy}%.'
imageUri:
description: The URL of an icon or visual representation of this notification or notification definition.
type: string
format: uri
maxLength: 2048
example:
text: 'We have increased the rate of your CD from {oldApy}% to {newApy}%.'
imageUri: 'https://cdn.assets.3rdpartybank.com/icons/en/notifications/cdRateIncreased.png'
type: object
x-apiture-flattened: true
createNotification:
title: Create Notification
description: Representation used to create a new notification for a user from a notification definition and a specific notification context.
required:
- definitionId
- userId
- contextUri
example:
_profile: 'https://api.apiture.com/schemas/notifications/createNotification/v1.0.0/profile.json'
definitionId: 41cf829b-879d-4334-9085-7ac18333ce47
userId: 80ebfabf-7a26-48a9-96c2-86f4dca8706f
contextUri: /accounts/account/ba611f3a-ab1b-4ad7-aaf6-56a240123818
x-apiture-composition:
- $ref: '#/components/schemas/abstractRequest'
- $ref: '#/components/schemas/notificationFields'
- properties:
- definitionId
- userId
properties:
_links:
description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
allOf:
- $ref: '#/components/schemas/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](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.'
type: string
format: uri
contextUri:
description: >-
The URI of a resource that defines the content of this notification, such as an account, a user, or the global resource URI,
`https://api.apiture.com/domains/notifications/global`. The URI need not have the `https://hostname` portion but must either start with
`https://{hostname}/` _or_ be the full resource path starting with a `/`.
type: string
maxLength: 2048
format: uri
example: /accounts/accounts/0a4511d1-1b63-4640-af0c-d4cdd6c88d37
definitionId:
description: >-
The `_id` of an active notification definition. The properties of the definition will be used to set some of the properties of this new
notification.
type: string
maxLength: 48
userId:
description: The ID of a digital banking user who owns and can view and dismiss this notification.
type: string
maxLength: 48
type: object
x-apiture-flattened: true
summaryNotification:
title: Notification Summary
description: >-
Summary representation of a notification resource in notifications collections. This representation normally does not contain any `_embedded`
objects. If needed, call the `GET` operation on the item's `self` link to get `_embedded` objects.
example:
_id: 0399abed-fd3d-4830-a88b-30f38b8a365c
_profile: 'https://api.apiture.com/schemas/notifications/summaryNotification/v1.0.0/profile.jsons'
dismissed: false
expired: false
dismissedAt: '2020-04-02T11:01:31.375Z'
expiresAt: '2020-04-18T12:15:21.375Z'
_links:
self:
href: /notifications/notifications/0399abed-fd3d-4830-a88b-30f38b8a365c
x-apiture-composition:
- $ref: '#/components/schemas/abstractResource'
- $ref: '#/components/schemas/notificationFields'
- properties:
- _id
- dismissed
- notDismissible
- expired
properties:
_links:
description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
allOf:
- $ref: '#/components/schemas/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](https://developer.apiture.com/docs/concepts/profiles/) 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: '#/components/schemas/error'
contextUri:
description: >-
The URI of a resource that defines the content of this notification, such as an account, a user, or the global resource URI,
`https://api.apiture.com/domains/notifications/global`. The URI need not have the `https://hostname` portion but must either start with
`https://{hostname}/` _or_ be the full resource path starting with a `/`.
type: string
maxLength: 2048
format: uri
example: /accounts/accounts/0a4511d1-1b63-4640-af0c-d4cdd6c88d37
_id:
description: The unique identifier for this notification resource. This is an immutable opaque string.
type: string
maxLength: 48
readOnly: true
dismissed:
description: '`true` if this the user has dismissed this notification.'
type: boolean
readOnly: true
notDismissible:
description: '`true` if this the notification definition is `notDismissible`.'
type: boolean
readOnly: true
expired:
description: '`true` if this notification''s expiration date-time has passed.'
type: boolean
readOnly: true
type: object
x-apiture-flattened: true
activeNotifications:
title: Active Notifications
description: >-
A list of active notifications for a user, in high to low priority order. These are notifications for a context, a client type (web, mobile),
and one or more language preferences.
type: object
x-apiture-composition:
- $ref: '#/components/schemas/abstractResource'
- properties:
- _embedded
properties:
_links:
description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
allOf:
- $ref: '#/components/schemas/links'
_embedded:
description: Embedded objects.
allOf:
- $ref: '#/components/schemas/embeddedActiveNotifications'
_profile:
description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) 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: '#/components/schemas/error'
x-apiture-flattened: true
embeddedActiveNotifications:
title: Embedded Active Notifications
description: The list of active notifications for a user's context.
type: object
properties:
items:
description: 'An array of active notifications, in high to low priority order.'
type: array
items:
$ref: '#/components/schemas/activeNotification'
x-apiture-flattened: true
notifications:
title: Notification Collection
description: >-
Collection of notifications. The items in the collection are ordered in the `_embedded.items` array; the `name` is `notifications`. The
top-level `_links` object may contain pagination links (`self`, `next`, `prev`, `first`, `last`, `collection`).
example:
_profile: 'https://api.apiture.com/schemas/notifications/notifications/v1.0.0/profile.json'
name: notifications
start: 10
limit: 10
count: 67
_links:
self:
href: /notifications/notifications?start=10&limit=10
first:
href: /notifications/notifications?start=0&limit=10
next:
href: /notifications/notifications?start=20&limit=10
collection:
href: /notifications/notifications
_embedded:
items:
anyOf:
- _id: 0399abed-fd3d-4830-a88b-30f38b8a365c
_profile: 'https://api.apiture.com/schemas/notifications/summaryNotification/v1.0.0/profile.json'
_links:
self:
href: /notifications/notifications/0399abed-fd3d-4830-a88b-30f38b8a365c
- _id: d62c0701-0d74-4836-83f9-ebf3709442ea
_profile: 'https://api.apiture.com/schemas/notifications/summaryNotification/v1.0.0/profile.json'
_links:
self:
href: /notifications/notifications/d62c0701-0d74-4836-83f9-ebf3709442ea
x-apiture-composition:
- $ref: '#/components/schemas/collection'
- properties:
- _embedded
properties:
_links:
description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
allOf:
- $ref: '#/components/schemas/links'
_embedded:
type: object
description: Embedded objects.
properties:
items:
description: An array containing a page of notification items.
type: array
items:
$ref: '#/components/schemas/summaryNotification'
_profile:
description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) 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: '#/components/schemas/error'
count:
description: >-
The number of items in the collection. This value is _optional_ and may be omitted if the count is not computable efficiently. If a filter
is applied to the collection (either implicitly or explicitly), the count, if present, indicates the number of items that satisfy the
filter.
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
type: object
x-apiture-flattened: true
root:
x-apiture-version: 2.0.0
title: API Root (v2.0.0)
description: 'A HAL response, with hypermedia `_links` for the top-level resources and operations in API.'
example:
id: apiName
name: API name
apiVersion: 1.0.0
_profile: 'https://production.api.apiture.com/schemas/common/root/v2.0.0/profile.json'
_links: {}
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/root/v2.0.0/model.json'
x-apiture-namespace: common
x-apiture-composition:
- $ref: '#/components/schemas/abstractResource'
- properties:
- _id
- name
- apiVersion
properties:
_links:
description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
allOf:
- $ref: '#/components/schemas/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](https://developer.apiture.com/docs/concepts/profiles/) 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: '#/components/schemas/error'
_id:
description: This API's unique ID.
readOnly: true
type: string
name:
type: string
description: This API's name.
apiVersion:
type: string
description: This API's version.
type: object
x-apiture-flattened: true
errorResponse:
x-apiture-version: 2.0.0
title: Error Response (v2.0.0)
description: 'Describes an error response, typically returned on 4xx or 5xx errors from API operations. The `_error` object contains the error details.'
example:
_profile: 'https://api.apiture.com/schemas/common/errorResponse/v2.0.0/profile.json'
_error:
_id: 2eae46e1-575c-4d69-8a8f-0a7b0115a4b3
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: 'https://api.apiture.com/errors/positiveNumberRequired'
_embedded:
errors: []
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/errorResponse/v2.0.0/model.json'
x-apiture-namespace: common
x-apiture-composition:
- $ref: '#/components/schemas/abstractResource'
properties:
_links:
description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
allOf:
- $ref: '#/components/schemas/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](https://developer.apiture.com/docs/concepts/profiles/) 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: '#/components/schemas/error'
type: object
x-apiture-flattened: true
abstractRequest:
x-apiture-version: 2.0.0
title: Abstract Request (v2.0.0)
description: >-
An abstract schema used to define other request-only schemas. This is a [HAL](https://tools.ietf.org/html/draft-kelly-json-hal-08) resource
representation, minus the `_error` defined in `abstractResource`.
properties:
_links:
description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
allOf:
- $ref: '#/components/schemas/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](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.'
type: string
format: uri
example:
_profile: '{uri of resource profile.json}'
_links:
self:
href: '{uri of current resource}'
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/abstractRequest/v2.0.0/model.json'
x-apiture-namespace: common
type: object
x-apiture-flattened: true
attributeValue:
x-apiture-version: 2.0.0
title: Attribute Value (v2.0.0)
description: The data associated with this attribute.
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/attributeValue/v2.0.0/model.json'
x-apiture-namespace: common
type: object
properties: {}
x-apiture-flattened: true
abstractResource:
x-apiture-version: 2.0.0
title: Abstract Resource (v2.0.0)
description: >-
An abstract schema used to define other schemas for request and response bodies. This is a
[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: '{uri of resource profile.json}'
_links:
self:
href: '{uri of current resource}'
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/abstractResource/v2.0.0/model.json'
x-apiture-namespace: common
x-apiture-composition:
- $ref: '#/components/schemas/abstractRequest'
- properties:
- _error
properties:
_links:
description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
allOf:
- $ref: '#/components/schemas/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](https://developer.apiture.com/docs/concepts/profiles/) 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: '#/components/schemas/error'
type: object
x-apiture-flattened: true
collection:
x-apiture-version: 2.0.0
title: Collection (v2.0.0)
description: A collection of resources. This is an abstract model schema which is extended to define specific resource collections.
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/collection/v2.0.0/model.json'
x-apiture-namespace: common
x-apiture-composition:
- $ref: '#/components/schemas/abstractResource'
- properties:
- count
- start
- limit
- name
properties:
_links:
description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
allOf:
- $ref: '#/components/schemas/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](https://developer.apiture.com/docs/concepts/profiles/) 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: '#/components/schemas/error'
count:
description: >-
The number of items in the collection. This value is _optional_ and may be omitted if the count is not computable efficiently. If a filter
is applied to the collection (either implicitly or explicitly), the count, if present, indicates the number of items that satisfy the
filter.
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
type: object
x-apiture-flattened: true
links:
title: Links (v1.0.0)
x-apiture-version: 1.0.0
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
x-apiture-key: linkRelationName
additionalProperties:
$ref: '#/components/schemas/link'
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/links/v1.0.0/model.json'
x-apiture-namespace: common
properties: {}
x-apiture-flattened: true
error:
x-apiture-version: 2.0.0
title: Error (v2.0.0)
description: Describes an error in an API request or in a service called via the API.
required:
- message
properties:
message:
type: string
description: A localized message string describing the error condition.
_id:
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.
readOnly: true
type: 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 [RFC 3339](https://tools.ietf.org/html/rfc3339) UTC time stamp indicating when the error occurred.'
example: '2018-02-02T03:37:15.375Z'
attributes:
description: >-
Informative values or constraints which describe the error. For example, for a value out of range error, the attributes may specify the
`minimum` and `maximum` values. This allows clients to present error messages as they see fit (the API does not assume the
client/presentation tier). The set of attributes varies by error `type`.
allOf:
- $ref: '#/components/schemas/attributes'
remediation:
type: string
description: An optional localized string which provides hints for how the user or client can resolve the error.
errors:
description: An optional array of nested error objects. This property is not always present.
type: array
items:
$ref: '#/components/schemas/error'
_links:
$ref: '#/components/schemas/links'
example:
_id: 2eae46e1575c0a7b0115a4b3
message: Descriptive error message...
statusCode: 422
type: errorType1
remediation: Remediation string...
occurredAt: '2018-01-25T05:50:52.375Z'
errors:
- _id: ccdbe2c5c938a230667b3827
message: An optional embedded error
- _id: dbe9088dcfe2460f229338a3
message: Another optional embedded error
_links:
describedby:
href: 'https://developer.apiture.com/errors/errorType1'
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/error/v2.0.0/model.json'
x-apiture-namespace: common
type: object
x-apiture-flattened: true
link:
x-apiture-version: 1.0.0
title: Link (v1.0.0)
description: >-
Describes a hypermedia link within a `_links` object in HAL representations. In Apiture APIs, links are [HAL
links](https://developer.apiture.com/docs/concepts/links), 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.'
example:
href: /contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f
title: Applicant
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/link/v1.0.0/model.json'
x-apiture-namespace: common
type: object
x-apiture-flattened: true
attributes:
x-apiture-version: 2.0.0
title: Attributes (v2.0.0)
description: An optional map of name/value pairs which contains additional dynamic data about the resource.
type: object
x-apiture-key: attributeName
additionalProperties:
$ref: '#/components/schemas/attributeValue'
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/attributes/v2.0.0/model.json'
x-apiture-namespace: common
properties: {}
x-apiture-flattened: true
responses:
'304':
description: Not Modified. The resource has not been modified since it was last fetched.
'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.
content:
application/hal+json:
schema:
$ref: '#/components/schemas/errorResponse'
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
'412':
description: >-
Precondition Failed. The supplied `If-Match` header value does not match the most recent `ETag` response header value. The resource has
changed in the interim.
content:
application/hal+json:
schema:
$ref: '#/components/schemas/errorResponse'
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
'422':
description: >-
Unprocessable Entity. The request body or 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.
content:
application/hal+json:
schema:
$ref: '#/components/schemas/errorResponse'
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
422NotificationDefinition:
description: >-
Unprocessable Entity. The request body or 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.
x-apiture-errors:
- indicatorAndNotDismissibleMutuallyExclusive
- idNotMatchPath
content:
application/hal+json:
schema:
$ref: '#/components/schemas/errorResponse'
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
400ExpireNotificationDefinition:
description: Bad Request. The definition parameter was malformed or does not refer to an existing or accessible definition.
x-apiture-errors:
- definitionRefNotFound
content:
application/hal+json:
schema:
$ref: '#/components/schemas/errorResponse'
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
404NotificationDefinition:
description: >-
Not Found. There is no such definition resource at the specified `{definitionId}`. The `_error` field in the response will contain details
about the request error.
content:
application/hal+json:
schema:
$ref: '#/components/schemas/errorResponse'
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
400DismissNotification:
description: Bad Request. The notification parameter was malformed or does not refer to an existing or accessible notification.
x-apiture-errors:
- notificationRefNotFound
content:
application/hal+json:
schema:
$ref: '#/components/schemas/errorResponse'
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
409DismissNotificationConflict:
description: >-
Conflict. The request to dismiss the notification is not allowed. The `_error` field in the response will contain details about the request
error.
x-apiture-error:
- dismissNotAllowed
content:
application/hal+json:
schema:
$ref: '#/components/schemas/errorResponse'
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
409InstancesConflict:
description: >-
Conflict. The definition has expired, or the `createNotifications` request uses a `contextUriTemplate` that does not match the notification
definition's existing `contextUriTemplate`, or instances contain only a `contextId` and the request or definition has no `contextUriTemplate`,
or a request was made to create notification instance for a global notification definition.
x-apiture-errors:
- definitionExpired
- mismatchedContextUriTemplate
- definitionMissingContextUriTemplate
- cannotCreateInstancesFromGlobalDefinition
content:
application/hal+json:
schema:
$ref: '#/components/schemas/errorResponse'
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
400ExpireNotification:
description: Bad Request. The notification parameter was malformed or does not refer to an existing or accessible notification.
x-apiture-errors:
- notificationRefNotFound
content:
application/hal+json:
schema:
$ref: '#/components/schemas/errorResponse'
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
409ExpireNotificationConflict:
description: >-
Conflict. The request to expire the notification is not allowed. The `_error` field in the response will contain details about the request
error.
content:
application/hal+json:
schema:
$ref: '#/components/schemas/errorResponse'
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
404Notification:
description: >-
Not Found. There is no such notification resource at the specified `{notificationId}`. The `_error` field in the response will contain details
about the request error.
content:
application/hal+json:
schema:
$ref: '#/components/schemas/errorResponse'
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
422CreateNotification:
description: >-
Unprocessable Entity. The request body or 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.
content:
application/hal+json:
schema:
$ref: '#/components/schemas/errorResponse'
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
204Deleted:
description: No Content. The resource was deleted successfully.
parameters:
definitionQueryParam:
name: definition
required: true
in: query
description: >-
A string which uniquely identifies a definition which is to added to the selected definitions resource set. This may be the unique
definitionId or the URI of the definition.
schema:
type: string
definitionIdPathParam:
name: definitionId
description: The unique identifier of this definition. This is an opaque string.
in: path
required: true
schema:
type: string
filterQueryParam:
name: filter
in: query
description: 'Optional filter criteria. See [filtering](https://developer.apiture.com/docs/concepts/filtering).'
schema:
type: string
qQueryParam:
name: q
in: query
description: 'Optional search string. See [searching](https://developer.apiture.com/docs/concepts/searching).'
schema:
type: string
dismissedQueryParam:
name: dismissed
description: Return only notifications whose `dismissed` matches the query parameter value.
in: query
schema:
type: boolean
expiredQueryParam:
name: dismissed
description: Return only objects whose `dismissed` matches the query parameter value.
in: query
schema:
type: boolean
typeQueryParam:
name: type
description: >-
Return only notifications whose `type` matches the one of query parameter values. The array item delimiter is the `|` pipe character.
Examples:
`?type=cdMaturingSoon`
`?type=cdMaturingSoon|cdInGracePeriod`
in: query
style: pipeDelimited
schema:
type: array
items:
type: string
definitionTypeQueryParam:
name: type
description: >-
Return only notification definitions whose `type` matches the one of query parameter values. The array item delimiter is the `|` pipe
character.
Examples:
`?type=cdMaturingSoon`
`?type=cdMaturingSoon|cdInGracePeriod`
in: query
style: pipeDelimited
schema:
type: array
items:
type: string
definitionContextNameQueryParam:
name: contextName
description: >-
Return only notification definitions whose `contextName` matches the one of query parameter values. The array item delimiter is the `|` pipe
character.
Examples:
`?contextName=account`
`?contextName=user|global`
in: query
style: pipeDelimited
schema:
type: array
items:
type: string
contextNameQueryParam:
name: contextName
description: >-
Return only notifications whose `contextName` matches the one of query parameter values. The array item delimiter is the `|` pipe character.
Examples:
`?contextName=account`
`?contextName=user|global`
in: query
style: pipeDelimited
schema:
type: array
items:
type: string
contextUriQueryParam:
name: contextUri
in: query
description: >-
Return only notifications whose `contextUri` matches the query parameter value. If the value begins with `/`, only the path portion of the URi
is matched.
Examples:
`?contextUri=/accounts/accounts/c6082333-be32-4171-b0c5-d161bcdbd6db`
schema:
type: string
notificationQueryParam:
name: notification
required: true
in: query
description: A string which uniquely identifies a notification. This may be the unique `notificationId` or the URI of the notification.
schema:
type: string
contextQueryParam:
name: context
description: >-
A string which uniquely identifies a notification context resource by context name or context URI. The array item delimiter is the `|` pipe
character.
Examples:
`?context=/accounts/accounts/c6082333-be32-4171-b0c5-d161bcdbd6db`
`?context=account`
`?context=global|user`
in: query
required: true
style: pipeDelimited
schema:
type: array
items:
type: string
notificationIdPathParam:
name: notificationId
description: The unique identifier of this notification. This is an opaque string.
in: path
required: true
schema:
type: string
ifMatchHeaderParam:
name: If-Match
description: 'The entity tag that was returned in the `ETag` response. If passed, this must match the current entity tag of the resource.'
in: header
schema:
type: string
ifNoneMatchHeaderParam:
name: If-None-Match
description: >-
The entity tag that was returned in the `ETag` response. If the resource's current entity tag matches, the `GET` will return 304 (Not
Modified) and no response body, else the resource representation will be returned.
in: header
schema:
type: string
requestBodies:
notificationDefinition:
content:
application/hal+json:
schema:
$ref: '#/components/schemas/notificationDefinition'
application/json:
schema:
$ref: '#/components/schemas/notificationDefinition'
required: true
securitySchemes:
apiKey:
type: apiKey
name: API-Key
in: header
description: >-
API Key based authentication. Each client application must pass its private, unique API key, allocated in the developer portal, via the
`API-Key: {api-key}` request header.
accessToken:
type: oauth2
description: >-
OAuth2 client access token authentication. The client authenticates against the server at `authorizationUrl`, passing the client's private
`clientId` (and optional and `clientSecret`) as part of this flow. The client obtains an access token from the server at `tokenUrl`. It then
passes the received access token via the `Authorization: Bearer {access-token}` header in subsequent API calls. The authorization process also
returns a refresh token which the client should use to renew the access token before it expires.
flows:
authorizationCode:
authorizationUrl: /auth/oauth2/authorize
tokenUrl: /auth/oauth2/token
scopes:
data/read: 'Read access to non-account, non-profile data.'
data/write: 'Write (update) access to non-account, non-profile data.'
admin/write: 'Admin write (update) access to non-account, non-profile data.'
admin/read: 'Admin Read access to non-account, non-profile data.'
admin/delete: 'Admin access to non-account, non-profile data.'
admin/full: 'Full admin access to non-account, non-profile data.'