Introduction

API gateway documentation can be found in the subpages.

We currently support v3 and v4. The OpenAPI specification is available as of v4.

Versioning

The API gateway has its own versioning, independent of the main application. The major version is indicated in the URL path. A minor gateway version is backward compatible over different versions of the application.

New endpoints and fields are not considered breaking changes and may be added in an existing gateway version. Hence, the Open API specification of a gateway version may differ between different major versions of the application.

OpenAPI Specification

The Harmoney API-gateway OpenAPI specification can be retrieved using the following authenticated endpoint: <base-url>/openapi.json or downloaded here.

The specification can be opened in, for example:

• Postman
• https://editor.swagger.io/

General usage

REST-services

The services are plain REST-based services. All data exchange is handled in JSON using the UTF-8 encoding.

Default URL: https://[host]/external/v4/

note

When identifiers are defined in path/query parameters or the request body, they can only contain alphanumeric characters and a dash (-) character!

Request headers

At server-side, an incoming request may have an entity attached to it depending on the used HTTP method. To determine the type, the following HTTP header parameter must be used on all service requests of the API-gateway:

Content-Type: application/json

Similarly, to determine what type of representation is desired at client side, the following HTTP header parameter is used on the related service requests of the API-gateway:

Accept: application/json

String validation

In the JSON model, when a text field of type string is required, the maximum length that will be accepted is 255 characters, unless specified otherwise.

Authentication

The API-gateway gateway supports both Basic Authentication or a bearer token. On every authenticated service call, one of the two should be supplied.

Basic Authentication

Basic Authentication is an authentication scheme built into the HTTP Protocol. The client sends the HTTP Request with an Authorization header which contains the word Basic following a space and a base64-encoded string representing the username and password.

Example:

Header	Value
Authorization	Basic ZGVtbzpwQDU1dzByZA==

Bearer Token Authentication

Bearer Token Authentication allows clients to authenticate using a JSON Web Token (JWT) obtained from their Identity Provider (IDP). The client sends the HTTP Request with an Authorization header that contains the word Bearer followed by a space and the token string.

To use this method:

1. Retrieve a valid JWT from your configured IDP.
2. Include the token in the Authorization header for each API call.
3. Provide the following additional headers to identify the context for token verification:
   • X-Organization-Identifier: Specifies the organization identifier.
   • X-Whitelabel-Identifier: Specifies the whitelabel identifier.
   • X-Provider-Identifier: Specifies the provider identifier, which links to the IDP configuration.

Example:

Header	Value
Authorization	Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InRlc3Qta2lkIn0.eyJ0…
X-Organization-Identifier	someOrg
X-Whitelabel-Identifier	someWhitelabel
X-Provider-Identifier	someProvider

Concepts

Models

The Harmoney API-gateway OpenAPI specification contains all the associated data-models.

Natural identifiers

Some of the models contain fields that contain an array of items (referring to another sub-model). For such items, we introduced a concept of ‘natural identifier’.

A natural identifier consists of 1 or more fields of the object and defines the uniqueness of the object. If applicable, it can be found in the model descriptions.

The natural identifier is important when updating an entity (e.g. a dossier or party).

Module

When a module is specified for a field it means that data for this field cannot be created/updated/retrieved unless your financial SP has this module activated.

Enum values

Some fields can only contain specific enum values to define their value, although the model defines the type as a free text field. This is the case when the field is configured as a list of values which can be different depending on the environment. The valid keys will be defined and communicated together with Harmoney.

Collections

The ground rules for updating collection fields are as following:

• When the field is not specified or it contains the value null, the collection is not updated.
• When the optional query parameter updateStrategy is omitted or set to OVERWRITE:
  • Entries in the existing collection but not in the new collection are removed from the existing collection. This also happens for an empty collection ([]), resulting in the existing collection to be cleared.
  • Entries in the new collection but not in the existing collection are added;
  • Entries present in both collections are updated.
• When the optional query parameter updateStrategy is set to APPEND:
  • Entries in the existing collection but not in the new collection are ignored;
  • Entries in the new collection but not in the existing collection are added;
  • Entries present in both collections are updated.

For this last case, when comparing the existing field items versus the provided array, an item is considered the same if the ‘natural identifier’ is the same.

Metadata fields

Depending on the configuration, some models (e.g. Dossier, Party, …) might contain additional so-called metadata fields.

Those objects have a single field metadata that behaves like a map/dictionary with keys of type string and values that can be of any type (string, number, …) but are expected to be in accordance with the agreed metadata fields data model.

Within this metadata field, the same strategy is used as other fields:

• If the metadata field itself is set to null or {} (empty map/dictionary), the contents won’t be changed
• When a key is present in the new data, that value will be stored, overwriting any value that was already stored for that key. This is also the case when the key is present with a null value.
• When a key is absent, the value stored with that key in Harmoney will be preserved.

Automations

It is possible to configure some automations for a front-office or back-office that will be run after a dossier is created or updated through the gateway. These automations will need to be configured in the Harmoney system itself.

To disable any automations from being executed after a dossier create/update, provide a query parameter automationIdentifier with value none in the PUT Dossier request. Disabling automations may prove useful, for example, when updating the dossier status to prevent automations from changing the dossier status again after the API request.

Callback URL

The API-gateway uses a callback-mechanism to trigger asynchronous “out-of-band” requests, also known as webhooks, to the consuming service in response to certain events. A callback will go through a different connection then the initial request-response flow.

The external-system, consuming the Harmoney API-gateway services, must expose a REST-service following the standard web-service implementation practices. This REST-service callback endpoint must be externally exposed and made accessible to the Harmoney-system. This enables a direct communication channel between the two systems, used for certain events depending on the configuration.

The callback REST-service:

• Externally accessible by the Harmoney-system
• Implement the HTTP POST-method and must accept a body JSON-payload following the Callback-model.
• Using the secure version of HTTP supporting at least TLS 1.3
• Supported authentication:
  • Accessible without authentication
  • Basic authentication
  • Bearer token
• Return a 200-response upon receipt

Best practice security-measures on the callback-URI:

• Each PUT-Dossier interaction should include a unique callback-URI, see more detail in the “Query Parameters” section of the PUT-dossier service below.
• This unique callback-URI should include an additional security-token, to protect and distinguish every interaction.
• Process the callback-trigger in an asynchronous way, limiting the overall transaction-span by excluding interactions with multiple internal-systems.

The provided payload on this POST-callback service can be found in the models defined in by OpenAPI specification.

Practical example: When calling the service to create a dossier a callback URL can be provided, which will be called after the dossier is processed. The status object returned on this callback contains a href element which must be used to retrieve detailed information about this processed dossier.

Callback error handling

When a non 2xx response is received from the consuming service, a retry mechanism with exponential back-off is triggered. The callback is retried 4 times. The first retry is after 30 seconds. The second retry is 60 seconds later, the third after another 120 seconds etc. If the callback did not succeed after the retries, the job ends in a dead-letter queue which is monitored by the Harmoney team.

Error handling

The Harmoney API-gateway uses HTTP status codes to give a first hint on what's going on:

• 2xx: Everything was OK, and the data has been accepted or processed.
• 4xx: There is an error on client-side which means the request could not be processed. If the data can be corrected, subsequent calls might complete successfully. Common error codes:
  • 403: Unable to process this request due to authorization issues. E.g. invalid user role, missing modules,...
  • 404: The provided data could not be found or parsed. E.g. json syntax errors, invalid enum values, wrong id's,...
  • 409: The provided data is not valid or could not be validated. E.g. a required field is not provided, a string contains too many characters, an identifier cannot be resolved,...
  • 429: The configured rate limit was hit; this and future requests will be blocked. The remaining time is returned in the response error message. See RATE_LIMIT error code.
• 5xx: There is an error on server-side. The client is not responsible and it might be possible to try again without making changes to the call. If the problem persists, contact Harmoney support.

Error return data structure

When an error occurs (4xx or 5xx), the Harmoney API-gateway will return error information in a structured format:

{
  "_errorCode": "ERROR_CODE",
  "_error": "A human readable error message"
}

The _errorCode is targeted at a developer audience and might be too technical for an end user to understand.
The _error field contains a human readable error message. This message could be interpreted to find out why the call returned an error. If this message doesn’t provide enough information, please contact Harmoney support.

Error Codes

Below is a list of possible error codes known in the API-gateway.

• FORBIDDEN: The logged in user is not allowed to access the requested resources.
• INTERNAL_SERVER_ERROR: The server could not process the request because of a problem on server-side. The client could retry the call without any changes and it might get processed. If the problem persist, contact Harmoney support.
• BAD_REQUEST: The request could not be processed due to a bad request. This might be caused by incorrect data, invalid data formatting or some other reason where the request cannot be processed at this time (e.g. preconditions of the object the request is made on).
• METHOD_NOT_ALLOWED: The method was not allowed for this resource. This occurs when e.g. a POST is executed on an endpoint where only GET is allowed.
• UNAUTHORIZED: The user executing the call is not authorized to make this call.
• NOT_FOUND: The requested resource or action could not be found on the system.
• RATE_LIMIT: The client has hit the rate limits. There should be more time between subsequent calls. A penalty timeout might be enforced that might increase when the limit is hit again.
• UNSUPPORTED_MEDIA: The media type could not be processed by the server. The Harmoney API-gateway uses application/json.
• SERVICE_UNAVAILABLE: The API-gateway service is currently (partially) unavailable, and might become available again.
• INVALID_INPUT: The sent data could not be accepted as it is invalid or incorrect depending on the context in which the call was made.
• INVALID_CREDENTIALS: The credentials given are invalid (either the password is wrong, or the user could not be found).