Last active
June 28, 2020 09:03
-
-
Save amilos/280f24fca2deeec562f97fbf216db70a to your computer and use it in GitHub Desktop.
Core definitions for Asseco REST APIs
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
# 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