Asynchronous API – byNeuron

In some cases you don't need directly a response, and also some requests require heavy processing (eg creating a contract based on a very elaborate product configuration). In such cases you don't want to wait a long time and keep a thread open.

This is why we have asynchronous requests on API endpoints and a Request API to retrieve the status and exchange the correlation ID for an entity ID. You can recognize the asynchronous endpoints with a prefix of /async/ in the URI.

Execution flow

Send request to an asynchronous endpoint

Retrieve the status of the request

If status is completed, exchange the correlation ID for an entity ID

In the paragraphs below, more information and examples can be found for these steps. It is also possible to subscribe on MQTT to get notifications for these requests. This is described in a separate paragraph.

Asynchronous requests

The request body of asynchronous requests is identical as the 'normal' requests on the synchronous endpoints. The response of asynchronous requests is different, no actual response of the created or updated entity is returned, but a correlation ID is returned. This is a unique identifier to track the request in byNeuron. It is also possible to provide your own correlation id, in that case a header x-correlation-id need to be added to the request.

Example

Request

Headers:

key	value
x-correlation-id	ef2cefa8-066a-4235-9c80-90a390f0b624

Method: POST

URL: /async/v1/{tenant}/parties

{
    "name": "John Doe"
}

Response

{
    "identification": {
        "correlationId": "ef2cefa8-066a-4235-9c80-90a390f0b624"
    }
}

Retrieve the status of a request

Once the request is send to the asynchronous endpoint, the status can be requested using the correlation ID.

Example

Request

Method: GET

URL: /v1/{tenant}/request/correlation/ef2cefa8-066a-4235-9c80-90a390f0b624/status

Response

"completed"

Exchange the correlation ID for a request

In case the request status is completed, the correlation ID can be exchanged for the entity ID. Especially for creating entities asynchronously, you would like to know which entity is created.

Example

Request

Method: GET

URL: /v1/{tenant}/request/correlation/ef2cefa8-066a-4235-9c80-90a390f0b624/exchange

Response

{
  "identification": {
    "id": "27a62d1a-8638-43bb-b2c7-165b2d99ef92"
  },
  "api": "parties",
  "status": "completed"
}

MQTT notifications

We recommend to subscribe to MQTT to get notifications on the request, without having to request the endpoints to retrieve the status or exchange the correlation ID. In this paragraph is explained how to subscribe on MQTT topics to get notified on the asynchronous requests.

MQTT connection

First a MQTT connection need to be set up. We recommend the MQTT X client, to easily test and verify the connection settings.

You need to provide the following information to set up the connection

Property	Description
Name	Name of the connection, you can define this yourself
Client ID	Client ID of the connection, need to be unique to prevent duplicate connections
Protocol	`mqtts://` (mqtt) or `wss://` (websockets)
Port	`8883` for mqtts, `8884` for websockets
URI	This is the base url of your byNeuron environment, eg `abc.xyz.byneuron.com`
Username	As MQTT does not support OAuth authentication, a username and password need to be provided
Password	The password is the Bearer token received from the API, take into account that this token can expire and you need to set up the connection again.

More advanced settings can be set up, but the defaults are just fine for testing the connection.

Topic subscription

Once a connection is successfully established, a new subscription can be created for a specific topic. For subscribing on notifications for a specific correlation ID of a request, the topic is build up as follows.

api/v1/{tenant}/request/correlation/{correlationId}/exchange

After subscribing, notifications are received as they occur real time. Notifications are not sent retroactively, so it is important to subscribe on the topic before you sent the request to the asynchronous endpoint. That's why you also need to sent your own correlation ID as a header, to be able to subscribe upfront.

Notifications have the same body as the response of the Rest endpoints.

Example

Topic: api/v1/{tenant}/request/correlation/ef2cefa8-066a-4235-9c80-90a390f0b624/exchange

Notifications

First notification

{"status":"running"}

Second notification

{"status":"completed","api":"parties","identification":{"id":"27a62d1a-8638-43bb-b2c7-165b2d99ef92"}}