Skip to content

Instantly share code, notes, and snippets.

@amilos
Last active June 28, 2020 09:03
Show Gist options
  • Save amilos/280f24fca2deeec562f97fbf216db70a to your computer and use it in GitHub Desktop.
Save amilos/280f24fca2deeec562f97fbf216db70a to your computer and use it in GitHub Desktop.
Core definitions for Asseco REST APIs
# OpenAPI version identifier - required for OpenAPI 3.0 domains
openapi: 3.0.0
#######################
# Optional info section
#######################
info:
title: Acme Components
description: Common components for Acme REST APIs
version: 'v1'
components:
responses:
default-error-response:
description: 'Besides specific status codes above, other standard http [status codes](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html) can be returned for each request. To learn more see general guidance on [error handling](common-getstarted.html#error-handling)'
content:
application/json:
schema:
$ref: "https://api.swaggerhub.com/domains/asseco/core/v1#/components/schemas/validation-problem"
validation-error-response:
description: 'Your request was not constructed properly. Response contains the list of validation errors for each invalid element of your request. To learn more see general guidance on [validation](common-getstarted.html#validation).'
content:
application/json:
schema:
$ref: 'https://api.swaggerhub.com/domains/asseco/core/v1#/components/schemas/validation-problem'
parameters:
webhook-id-param:
description: Webhook ID.
in: path
name: webhook-id
required: true
schema:
type: string
page-param:
name: page
in: query
description: 'Page index. For more information see general guidance on [paging](common-getstarted.html#paging)'
schema:
type: integer
default: 1
page-size-param:
name: page-size
in: query
description: 'Number of items on a page. For more information see general guidance on [paging](common-getstarted.html#paging)'
schema:
type: integer
default: 10
sort-order-param:
name: sort-order
in: query
description: 'Sort order (`asc` or `desc`). Default is asc. For more information see general guidance on [sorting](common-getstarted.html#sorting)'
schema:
$ref: 'https://api.swaggerhub.com/domains/asseco/core/v1#/components/schemas/sort-order-enum'
sort-by-param:
name: sort-by
in: query
description: 'Attribute of the collection item to sort by. For more information see general guidance on [sorting](common-getstarted.html#sorting)'
schema:
type: string
schema-id-param:
name: schema-id
in: path
required: true
schema:
type: string
callbacks:
webhooks:
post:
summary: Subscribe for event delivery
description: |
Subscribes a client to receive out-of-band data
> See the payload of Ping operation for specific events in this API
operationId: Webhooks_Subscribe
tags:
- Webhooks
requestBody:
description: Webhook configuration details
content:
application/json:
schema:
$ref: 'https://api.swaggerhub.com/domains/asseco/core/v1#/components/schemas/register-webhook-command'
responses:
'201':
description: Subscription successfully created
content:
application/json:
schema:
$ref: 'https://api.swaggerhub.com/domains/asseco/core/v1#/components/schemas/webhook'
links:
unsubscribe:
operationId: Webhooks_Unsubscribe
description: The `id` value returned in the response can be used as the `webhook-id` parameter in `DELETE /webhooks/{webhook-id}`.
parameters:
webhook-id: '$response.body#/id'
details:
operationId: Webhooks_Get
description: The `id` value returned in the response can be used as the `webhook-id` parameter in `GET /webhooks/{webhook-id}`.
parameters:
webhook-id: '$response.body#/id'
callbacks:
webhook:
'{$request.body#/configuration/callbackUrl}':
post:
description: Event delivery handler you implement to receive events.
parameters:
- name: Content-Type
in: header
required: true
schema:
type: string
enum: ['application/cloudevents+json']
default: 'application/cloudevents+json'
requestBody:
description: 'Event payload according to CloudEvents 1.0 specification'
content:
application/cloudevents+json:
schema:
description: Event base model is reused within each API to ensure compatibility with CloudEvents specification 1.0
type: object
required:
- type
- specversion
- source
- id
- time
- subject
properties:
specversion:
type: string
enum:
- '1.0'
type:
type: string
example: 'asee.lending.loan.closed'
source:
type: string
format: uri-reference
example: 'asee.lending'
id:
type: string
example: 'A234-1234-1234'
time:
type: string
format: date-time
example: '2018-04-05T17:31:00Z'
subject:
type: string
example: 'loans/129199819929181'
traceparent:
type: string
example: '00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01'
tracestate:
type: string
example: 'rojo=00f067aa0ba902b7,congo=t61rcWkgMzE'
data:
type: object
example:
loan-arrangement: '129199819929181'
status-reason: 'completed'
responses:
'200':
description: Data was processed successfully
content:
text/plain:
schema:
type: string
description: Processing acknowledgement identifier if available
example: ACK-18K8JSK1
'202':
description: Data was received successfully but not processed yet
content:
text/plain:
schema:
type: string
description: Receipt acknowledgement identifier if available
example: ACK-18K8JSK1
'204':
description: Data was processed successfully
'410':
description: Delivery target has been retired, no further delivery should be attempted
'415':
description: Delivery cannot be accepted because the notification format has not been understood
'429':
description: Unable to process the request due to high rate of requests
headers:
Retry-After:
description: Retry after specified number of seconds
required: true
schema:
type: integer
example: 30
options:
description: Handler you implement to validate delivery target
parameters:
- name: WebHook-Request-Origin
in: header
description: DNS expression that identifies the sending system. The value is meant to identify all sender instances that act on the behalf of a certain system, and not an individual host. After the validation handshake and if permission has been granted, the sender MUST use the `Origin` request header for each delivery request, with the value matching that of this header.
required: true
schema:
type: string
example: 'eventemitter.example.com'
- name: WebHook-Request-Rate
in: header
description: May be included in the request and asks for permission to send notifications from this sender at the specified rate. The value is the string representation of a positive integer number greater than zero and expresses the request rate in "requests per minute".
schema:
type: integer
example: 120
responses:
'204':
description: Validation performed succesfully. Presence of headers specified here indicates that permission is granted.
headers:
WebHook-Allowed-Origin:
description: Returned when the delivery target agrees to notification delivery by the origin service. Its value MUST either be the origin name supplied in the `WebHook-Request-Origin` header, or a singular asterisk character `*`, indicating that the delivery target supports notifications from all origins.
required: false
schema:
type: string
example: eventemitter.example.com
WebHook-Allowed-Rate:
description: The header grants permission to send notifications at the specified rate. The value is either an asterisk character `*` or the string representation of a positive integer number greater than zero. The asterisk indicates that there is no rate limitation. An integer number expresses the permitted request rate in "requests per minute". For request rates exceeding the granted notification rate, the sender ought to expect request throttling. Throttling is indicated by requests being rejected using HTTP status code 429 Too Many Requests.
required: false
schema:
type: string
example: '*'
'405':
description: Validation method not supported
webhook-by-id:
parameters:
- $ref: 'https://api.swaggerhub.com/domains/asseco/core/v1#/components/parameters/webhook-id-param'
get:
summary: Get webhook details
description: Useful when details info about one particular webhook is required.
operationId: Webhooks_Get
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: 'https://api.swaggerhub.com/domains/asseco/core/v1#/components/schemas/webhook'
default:
$ref: 'https://api.swaggerhub.com/domains/asseco/core/v1#/components/responses/default-error-response'
tags:
- Webhooks
delete:
summary: Unsubscribe from event delivery
description: Deletes a webhook, by ID.
operationId: Webhooks_Unsubscribe
responses:
'204':
description: No Content
default:
$ref: 'https://api.swaggerhub.com/domains/asseco/core/v1#/components/responses/default-error-response'
tags:
- Webhooks
webhook-ping:
post:
summary: Test webhook with specified event
description: Useful when setting up the webhook correctly
operationId: Webhooks_Ping
parameters:
- name: callback-url
in: query
description: 'The text to search for. All searchable fields are searched by default unless search-fields is specified. When searching searchable fields, the search text itself is tokenized, so multiple terms can be separated by white space (e.g. `q=hello world`).'
required: true
schema:
type: string
requestBody:
$ref: '#/components/requestBodies/event-payload'
responses:
'204':
description: No Content
default:
$ref: 'https://api.swaggerhub.com/domains/asseco/core/v1#/components/responses/default-error-response'
tags:
- Webhooks
classifications:
get:
tags:
- Classifications
summary: List all classification schemas used by the API
description: Some fields and parameters have been restricted to a list of allowed lookup values maintained by the bank. This method lists all schemas used in this API.
operationId: Classifications_GetList
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: 'https://api.swaggerhub.com/domains/asseco/core/v1#/components/schemas/classification-list'
default:
description: 'Besides specific status codes above, other standard http [status codes](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html) can be returned for each request. To learn more see general guidance on [error handling](common-getstarted.html#error-handling)'
content: {}
classification-by-id:
get:
tags:
- Classifications
summary: List values allowed by given classification schema.
description: Returns all classification values for chosen classification.
operationId: Classifications_Get
parameters:
- name: schema-id
in: path
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: 'https://api.swaggerhub.com/domains/asseco/core/v1#/components/schemas/classification-item'
default:
description: 'Besides specific status codes above, other standard http [status codes](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html) can be returned for each request. To learn more see general guidance on [error handling](common-getstarted.html#error-handling)'
content: {}
schemas:
webhook:
description: 'Webhook details'
required:
- id
- callback-url
type: object
properties:
id:
description: The ID of the webhook.
type: string
format: uuid
callback-url:
description: The URL that is configured to listen for incoming POST HTTP calls that contain event information. Must be network accessible by the source server.
type: string
format: uri
example: "https://myserver.com/send/callback/here"
filter:
description: Optional array of topic filters for webhook's subscription. If not specified all topics will be subscribed to.
type: array
items:
$ref: 'https://api.swaggerhub.com/domains/asseco/core/v1#/components/schemas/filter-expression'
example:
id: 'a8cac229-71b8-48df-99e5-a9b21e21421a'
callback-url: "https://myserver.com/send/callback/here"
filter: ["party.individual.>","party.*.registered", "party.organization.profile.modified"]
register-webhook-command:
description: 'Webhook registration'
required:
- callback-url
type: object
properties:
callback-url:
description: The URL that is configured to listen for incoming POST HTTP calls that contain event information. Must be network accessible by the source server.
type: string
format: uri
example: "https://myserver.com/send/callback/here"
filter:
description: Optional array of topic filters for webhook's subscription. If not specified all topics will be subscribed to.
type: array
items:
$ref: 'https://api.swaggerhub.com/domains/asseco/core/v1#/components/schemas/filter-expression'
example:
callback-url: "https://myserver.com/send/callback/here"
filter: ["party.individual.>","party.*.registered", "party.organization.profile.modified"]
filter-expression:
type: string
description: |
### Topics
At its simplest, a topic is just a string of characters that form a name the publisher and subscriber can use to find each other.
The `.` character is used to create a topic hierarchy. For example, a Customer MDM application, as a publisher, might define the following list to logically group related topics
```
party.individual.address.added
party.individual.address.removed
party.individual.registered
party.organization.registered
```
### Wildcards
Wildcards can take the place of one or more elements in a dot-separated topic. Subscribers can use these wildcards to listen to multiple topics with a single subscription but publishers will always use a fully specified subject, without the wildcard.
The first wildcard is `*` which will match a single token. For example, if an application wanted to listen for registrations, they could subscribe to `party.*.registered`, which would match `party.individual.registered` and `party.organization.registered`.
The second wildcard is `>` which will match one or more tokens, and can only appear at the end of the topic. For example, `party.individual.>` will match `party.individual.registered`, `party.individual.address.added` and `party.individual.address.removed`, while `party.individual.*` would only match `party.individual.registered` since it can't match more than one token.
The wildcard `*` can appear multiple times for the same topic. Both types can be used as well. For example, `*.*.address.>` will receive `party.individual.address.added` and `party.individual.address.removed`.
example: 'party.*.registered'
event:
description: Event base model is reused within each API to ensure compatibility with CloudEvents specification 1.0
type: object
required:
- type
- specversion
- source
- id
- time
- subject
properties:
specversion:
type: string
enum:
- '1.0'
type:
type: string
example: 'asee.lending.loan.closed'
source:
type: string
format: uri-reference
example: 'asee.lending'
id:
type: string
example: A234-1234-1234
time:
type: string
format: date-time
example: '2018-04-05T17:31:00Z'
subject:
type: string
example: 'loans/129199819929181'
traceparent:
type: string
example: '00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01'
tracestate:
type: string
example: 'rojo=00f067aa0ba902b7,congo=t61rcWkgMzE'
data:
type: object
example:
loan-arrangement: '129199819929181'
status-reason: 'completed'
sort-order-enum:
description: Ascending or descending sort order
type: string
enum:
- asc
- desc
default: asc
x-asee-enum-doc:
- l: asc
d: Ascending order - A to Z
- l: desc
d: Descending order - Z to A
validation-problem:
type: object
properties:
errors:
type: array
description: List of validation errors
items:
type: object
properties:
tag:
type: string
description: Name of input element (field or parameter) that is in invalid. If missing or null it is interpreted that validation error refers to entire request rather than to specific element.
error:
type: string
description: Unique literal that identifies kind of validation error
message:
type: string
description: Message that explains failed validation. To support translation message may embed variable parameters in curly brackets.
description: Details of failed validation
example:
errors:
- tag: phone-number
error: invalid-format
message: Format for this field is invalid
- tag: phone-number
error: max-length
message: Content exceeds maximum alowed length
- tag: account-number
error: check-digit-invalid
message: Check digit is invalid for this field
business-problem:
type: object
properties:
problem:
$ref: '#/components/schemas/problem-literal'
message:
$ref: '#/components/schemas/problem-message'
details:
$ref: '#/components/schemas/problem-details'
description: Explanation of business rule that rejected request
paged-list:
type: object
properties:
total-count:
type: integer
description: Total number of items in collection
page-size:
type: integer
description: Size of the page
page:
type: integer
description: Index of current page
total-pages:
type: integer
description: Total number of pages of set size
sort-order:
$ref: 'https://api.swaggerhub.com/domains/asseco/core/v1#/components/schemas/sort-order-enum'
sort-by:
type: string
description: Attribute of the collection item to sort by
description: List with support for paging
classification-value:
type: object
properties:
literal:
type: string
description: Literal that uniquely identifies classification value
code:
type: string
description: Optional numerical code of classification value
description:
type: string
description: Description of classification value
parent-literal:
type: string
description: Optional literal of parent classification value if schema is hierarchical
description: Classification value
example:
literal: billing
code: '2'
description: Contact may be used to provide party with details of their liabilities to the bank
classification-list:
type: object
properties:
items:
type: array
description: List of classification schemas
items:
$ref: 'https://api.swaggerhub.com/domains/asseco/core/v1#/components/schemas/classification-info'
description: List of classification schemas used by this API
example:
items:
- schema-id: filing-purpose
name: Filing Purpose
description: 'List of possible uses of document in business context. Commonly used filing purposes are document, customer-picture'
- schema-id: folder-purpose
name: Folder Purpose
description: List of possible uses of a folder in business context.
classification-info:
type: object
properties:
schema-id:
type: string
description: Unique literal that identifies the classification schema. Always in `lowercase-dash` convention.
name:
type: string
description: User friendly name of classification
description:
type: string
description: Description of a classification
description: Basic information on classification schema
example:
schema-id: filing-purpose
name: Filing Purpose
description: 'List of possible uses of document in business context. Commonly used filing purposes are document, customer-picture'
classification-item:
type: object
properties:
schema-id:
type: string
description: Unique literal that identifies the classification schema. Always in `lowercase-dash` convention.
name:
type: string
description: User friendly name of classification
description:
type: string
description: Description of a classification
values:
type: array
description: List of allowed classification values
items:
$ref: 'https://api.swaggerhub.com/domains/asseco/core/v1#/components/schemas/classification-value'
description: Classification schema model
example:
schema-id: contact-purpose
name: Contact Purpose
description: List of possible purposes for which a channel or contact point is used
values:
- literal: any
code: '0'
description: Contact may be used for any purpose as contacted party has not indicated any preference.
- literal: marketing
code: '1'
description: Contact may be used to provide details about general products or services provided by the bank or partner organization.
- literal: billing
code: '2'
description: Contact may be used to provide party with details of their liabilities to the bank
- literal: relationship
code: '3'
description: "Contact may be used to maintain and manage bank's relationship with the party"
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment