Basic Rules & Conventions

Authentication

The Branded Communication API is built using a separate, in-house authentication service.

The basic pattern is:

  1. Acquire an Authorization token using the API Key and Secret Key
  2. Add the JSON Web Token (JWT) to each Exchange API request as an Authorization header

The token will be valid for 60 minutes. sing the refresh token provided in the initial authentication API request response
The token is valid for 60 minutes, after which a new token must be acquired using a refresh_token which is provided when the initial Authorization token is issued.

It is highly recommended that a client application builds logic on the authentication and re-authentication flows that allow retries in case the first attempt to renew the Authorization token fails. This can easily be achieved by attempting to refresh the Authorization token 10 minutes before it is set to expire, and retry once every minute until it is successfully renewed. The renewal is expected to be successful on the first attempt - the retry logic is only to have sufficient resiliency against exceptions.

API Standards

Noteworthy conventions are:

  • URLs should be hyphenated (e.g. /businesses//business-units)
  • Attribute names are camelCased. (e.g. { "businessId": "..." }

GET
Retrieve a list of objects, or an individual object. When retrieving a list, the result is always paginated.

POST
When submitting a post request with any object, there is no id attribute available yet (that is created when the object is created).

Responses to POST requests (when creating new objects) is the full created object with the newly assigned id attribute value.

PUT
When updating an object the id of the object can be omitted from the request body (the object is identified by the URI). If the ID is part of the request payload, it is ignored, and object id from the URI is honored.

📘

PATCH

In Version 1 PUT behaves similar to PATCH (which we have not implemented). This means, that attributes that are NOT passed in the PUT request payload are left untouched/unchanged.

Response to a PUT request always returns a full copy of updated object in it’s post updated state. (i.e. with new updated values).

DELETE
Single items are deleted using a URI that identifies the object to be deleted. Batch delete is achieved by submitting a POST request to a dedicated DELETE URI with list of objectIds to be deleted.

PATCH
Not used. Use PUT instead.

Basic response object structure

Each request that has a response body is structured in the following ‘blocks’

{
"body":{...},
"error":{...}
}
Body will be an array when the response is a list, and an object if the response is a single item, or multiple lists/arrays.

Error is typically an object with two keys: code that is the http response code, and description which includes a reason that yielded the error/exception.

Error codes

By default we follow the standard http response codes (found e.g. at Mozilla website:link:).

Exceptions and Exchange conventions
404 Bad Request is used for requests using unsupported methods (the standard suggests a 405 in these cases)

409 Conflict is used if a request is rejected due to unique constraint conflicts (e.g. trying to create two phone number objects with the same phone number).

Request Types

Compound requests
Version 1 supports (for convenience) certain compound requests, where a client can post a more extensive object as the POST request payload, and the Exchange system will use the object to create a resource and its sub-resources based on a single request.

In practice this means that a client application can create a business, its addresses and business units - all with one single POST request to the /businesses endpoint.

Compound requests are handled with best effort - this means that the response to the request will often be a 201 Created even if some of the sub-resources are not created because of a validation error. Also, the request will succeed if very basic root level object can be created (i.e. if creating a new business with business units, the request will be successful if business can be created, but business units cannot).

Atomic requests

Compound requests are not supported for updates. This means that in order to update a resource (and its sub-resources) the client application must possibly perform multiple PUT requests (one for each resource).

Each Compound endpoint acts also as an atomic POST endpoint. This means that the client application does not have to provide any sub-resources to create a top-level object.

So in our above example, you can POST to /businesses endpoint, and not include addresses or business units. In this case only the core business record is created.

It is recommended to use the atomic functions rather than the compound requests, primarily to make exception handling easier on the client application side.