Introduction

The EMnify System provides a RESTful API. Communication with the API is done over HTTP(S) requests with JSON request body with application/json content-type and an authentication token as a requirement for every API call.

The API is defined in detail in the following section, but here are some highlights:

• Lookup values are accessed at the same level as the resource they describe. For example, the URL to retrieve the list of possible statuses of an endpoint is /api/v1/endpoint/status.
• Collection responses are NOT wrapped in an envelope. Instead the result metadata is returned in the header of the response.
• Paging, filtering sorting of large datasets are managed via query parameters of GET requests.
• The API provides complex error messages capable of reporting a set of errors.
• The API implicitly provides multi-tenancy management. The server limits the visibility of the data and available operations based on the organisation of the user identified by authentication token.
• When associating an existing object(s) to a collection, it is sufficient to provide only the object(s) IDs.

The following service pattern is provided for all major resources:

N.B. The word endpoint, typically used in RESTful API definitions has a particular meaning in the EMnify application domain. To avoid confusion, the word endpoint will be used in this documentation to identify endpoint entities (resources) of the EMnify System domain while the word entrypoint will be used to identify generic RESTful API endpoints.

Securing the API

The API is secured through usage of JSON Web Tokens (JWT) which are an open standard (RFC 7519) for representing claims securely between two parties.

The server generates JWT tokens for accessing the API (further referenced as ‘authentication token’) for users or applications after they present verifiable credentials. Once the credentials are exchanged for an authentication token on the server, the client has to submit it within the HTTP Authorization header in each subsequent request. The system validates the rights and permissions of the requesting user/application by parsing the token’s content.

The authentication token expires after 240 minutes. Therefore the authentication needs to be performed again to obtain a new authentication token.

If the authentication token is missing, invalid or expired the API returns 401 Unauthorized response status.

If a client tries to access resources that exists, but the client does not have the permissions or the rights to access it, the API returns either 403 Forbidden or 404 Not Found.

These requirements are general and will not be repeated in in the remainder of this API specification.

Connection

All API calls including the authentication must be made over secure socket (SSL).

The server responds to API request in gzip compressed format with the following header

Content-Encoding: gzip
Content-Type: application/json

Rate Limiting

The EMnify System REST API has rate limiting enforced at the following values:

• 2000 requests per IP in a five minute window
• 100 authentication requests per IP in a five minute window

When this threshold is reached, 429 Too Many Requests will be returned by the system as a response to excessive requests until the average request rate is within the specified limit. The response will also include the Retry-After header, which indicates after how many Milliseconds a user can try requesting again.

Apart from the general API rate limiting, there are also limits configured on specific API paths. The following limits are enforced per organisation:

When the limit on any of these paths is exceeded, the system will return 429 Too Many Requests.

API Quota

Every organisation is allowed to make a total of 10,000,000 API requests per month. Once the quota has been used up, the system will return 429 Too Many Requests.

The quota will be reset on the 1st of every month.

URL format

All API URLs are following a generic structure like

/api/APIVERSION/ENTRYPOINT/{object_id}

e.g.

/api/v1/user/123

Also some resources may provide access to further sub-resources

/api/v1/organisation/123/contact

HTTP verbs

Here is the definition of HTTP verbs used in the API with description and typical responses upon request to collection entrypoint and single resource entrypoint.

HTTP Headers

Request Headers

Each HTTP request must have at least the following headers:

• Content-Type: application/json
• Accept: application/json
• Authorization: Bearer YourAuthenticationToken

Response Headers

The API uses header to transfer meta information about the returned result. The usage varies depending on the operation. The details are available within the specification of particular resource description:

HTTP Return codes