Guidelines

For all API calls

  • Any request may return X-CLIENT-STATE and if so that state should be stored and sent with any further requests.

  • The Emarsys SDK always sends the (X-CLIENT-ID), contact token ( X-CONTACT-TOKEN ) and state cookie ( X-CLIENT-STATE )

  • If the backend API returns a 400, the SDK should consider the app code or request structure is wrong and notify the app developer

  • If the backend API returns a 401, the SDK should consider that the contact token has to be renewed. The Emarsys SDK automatically goes to a POST /apps/:appCode/client/contact_token endpoint on the ME Backend and receives a new contact token and stores it on the device

    See POST `/apps/:appCode/client/contact_token` endpoint of Client Contact Matcher Service

Versioning

For now probably it is easier to keep the version in the path.

HTTP Methods

  • GET for fetching/reading data.

  • POST for appending new data

  • PUT for Replace/Create data (as a whole object). If the id is know we can utilise to create the resource

  • DELETE for deleting data.

HTTP Status

Data Errors/Client Errors

  • 400 - Bad Request - requested information is incomplete or malformed.

  • 402 - Request Failed - The parameters were valid but the request failed.

  • 404 - Not Found - the endpoint requested does not exist.

Authorisation Errors

  • 401 - Unauthorized

  • 429 - Too Many Requests

Success Codes

  • 200 - OK

  • 201 - Created

  • 202 - Accepted

  • 204 - No Content - no content is returned

Others

  • 500 - Internal Server Error

Rate Limit

Rate limiting is a problem we do not have yet, and do not want to solve at this stage, but we will eventually approach it with the following headers and process:

  • x-rate-limit-limit: number of requests allowed for a specific period

  • x-rate-limit-remaining: the number of requests left for the current period

  • x-rate-limit-reset: The number of seconds left in the current period

Until then, the API reserves the right to return 429 without giving any such indications.

Glossary

Client_id

Currently called hardware_id, it is a unique identifier that has a 1-0 or 1-1 relationship to push tokens and identifies an application instance that the app user is using to interact with the customer’s backend and the emarsys tracking backend.

X-CONTACT-TOKEN

contact token is a short-lived JWT token which client has to provide to authenticate itself when accessing all Mobile Engage services.

It contains:

  • contact-reference

  • expiration date & time

Token is generated when the client is linked to contact (see /apps/:appCode/client/contact endpoint).

We want this token to be short-lived (automatically expire) to cover the following scenarios:

  1. App user has installed two apps from the same customer and logged into both of them. Apps use different contact field IDs and the contact resolution has not been finished yet.

    When the client tries to link to the identified contact, we issue two different contact-reference s for these apps.

    When the contact resolution is done, we know that this is actually the same contact. Therefore, both apps should have gotten the same contact-reference.

    When the contact token expires, client asks for a new one and now we correctly return the same contact-reference to both apps.

  2. App user logs in the app and client initiates linking to the contact. Client receives an contact-reference which should eventually be linked to a contact in Suite.

    However, contact has not yet been created in Suite. We retry linking for 2 days after which it is considered a failure.

    When contact token expires, client asks for a new one and we will initiate linking process again.

    At this time, contact exists in the database and linking is successfull.

  3. Gives us flexibility to add other reasons to expire access in the future.

X-CLIENT-STATE

Server generated blob that decides which additional state the client should send with every request.

X-CLIENT-ID

A string identifier of the client, will typically be an app instance id or hardware id given back by the platform SDK.

X-REQUEST-ORDER

A value from monotonically increasing sequence representing the order of the request. The reason for letting the client set this is that a header like 'X-Request-Start' set by Heroku does not guarantee accuracy within a second.

SDK can use unix time (milliseconds since 1970) and must ensure that it always sends the number higher than any previous number it has sent before.