Andaman7 Developer Portal

Warning! Please note that this document is a first draft and is likely to change shortly.

In this section, you will find all the basic concepts related to the API and the messages format.

The API is currently in version 1 and can be accessed over HTTPS using the following URL : https://sandbox.andaman7.com/public/v1.

It is a REST API and all messages are in JSON format.

REST

With REST, data are resources and they are accessed using the HTTP protocol.

For example, if you want to get a list of users, you make a GET HTTP request on the users collection.

HTTP verbs

Here are the CRUD operations, their corresponding HTTP verb and the action performed on the resources.

CRUD operation	HTTP verb	Description
Create	`POST`	Creates a new resource.
Read	`GET`	Retrieves a single resource or a collection of resources.
Update	`PUT`	Updates an existing resource.
Delete	`DELETE`	Deletes a resource.

API key

All the requests must include an API key. There is one API key per application that is using the API.
If you don’t have one, you have to request it before starting to use the API.

To request an API key, see this section.

Once you have an API key, you make requests to the API by adding an HTTP header : api-key: <YOUR API KEY>.

Authentication

Some API calls need the end user to be authenticated. This can be achieved using Basic HTTP Authentication.

Thus, your request must include an additional HTTP header : Authorization: Basic <CREDENTIALS>.
Where <CREDENTIALS> is the concatenation of the username, the : symbol and the password hashed using the SHA-256 algorithm.
Then, the whole string is encoded in base 64.

In other words : Base64(<username>:SHA256(<password>)).

Responses

HTTP status codes

Code	Reason	Description
200	OK	The request was successfully executed.
201	Created	The resource has been successfully created.
204	No Content	The request was successfully executed but returned no content.

Format

As said earlier, all the messages are in JSON format. By default, they only contain the raw asked data.
But it is possible to specify the _envelope query parameter and set its value to true in order to get additional
information about the request. Example : https://sandbox.andaman7.com/public/v1/users?_envelope=true

The envelope, as we call it, contains 3 sections : the metadata, the raw data and the links.

{
    "meta": {},
    "<data_name>": {},
    "links": {}
}

The metadata are essentially used when a collection of data is returned, basically to give pagination information.

The key used for the data section depends on the data that is being returned.
For example, if the server returns a single user, the key will be user. If a collection of users is returned, then the key is users.

The links section will be explained in the hypermedia part.

Errors

When an error occurs, the response has a specific format which looks like this :

{
    "status": 404,
    "code": 404,
    "message": "The specified resource does not exist.",
    "developerMessage": "The specified resource does not exist.",
    "moreInfo": "http://developers.andaman7.com/guide/errors.html#404",
    "support": "api@andaman7.com"
}

The status is the HTTP status code returned by the server. The code is either the same as the status code or a custom code.
Those codes can be found here. The message is a description of the error that can be understood by end users.
However, the developerMessage is a description that is more oriented to the developers and which contains additional information.

Hypermedia

When the envelope is displayed, most responses include links to other resources that are related to the current one.
They give clues on the relationship between resources and may ease the first contact with the API.

Those links are included in the links section of the envelope and it contains at least one item, which is the link to the current resource (self).

Example

Here is an example of envelope :

{
    "meta": {},
    "device": { ... },
    "links": [
        {
            "rel": "self",
            "href": "https://sandbox.andaman7.com/public/v1/users/me/devices/2c8d77d0-fed7-11e4-b939-0800200c9a66"
        },
        {
            "rel": "devices",
            "href": "https://sandbox.andaman7.com/public/v1/users/me/devices"
        },
        {
            "rel": "owner",
            "href": "https://sandbox.andaman7.com/public/v1/users/me"
        }
    ]
}

Pagination

The pagination is simply used to split a large collection of items into multiple pages. For example, this can be useful
for mobile apps to lazy load some search results.

Pagination can be achieved by specifying 2 query parameters : _page and _perPage, respectively for the number of the
page an the number of items in a page.

Example

Here is the response after hitting GET https://sandbox.andaman7.com/public/v1/users?_page=3&_perPage=8 to get
the third page of the users with 8 users per page.

{
    "meta": {
        "page": 3,
        "perPage": 8,
        "totalPages": 19,
        "count": 8,
        "totalItems": 146,
        "hasMore": true
    },
    "users": [
        ...
    ],
    "links": [
        {
            "rel": "first",
            "href": "https://sandbox.andaman7.com/public/v1/users?_page=1&_perPage=8"
        },
        {
            "rel": "prev",
            "href": "https://sandbox.andaman7.com/public/v1/users?_page=2&_perPage=8"
        },
        {
            "rel": "next",
            "href": "https://sandbox.andaman7.com/public/v1/users?_page=4&_perPage=8"
        },
        {
            "rel": "last",
            "href": "https://sandbox.andaman7.com/public/v1/users?_page=19&_perPage=8"
        }
    ]
}

You can notice that there are some additional information in the meta section and there are also links to navigate
through the pages in the links section.

Filtering

If you want only some fields to appear in the response or some you don’t, you can add the _fields query parameter.
The value is the coma-separated list of the fields you want to appear in the response. Nested fields must be separated from their parent by a ..
On the other side, if you want a field not to appear in the response, you have to prefix its name by a !.

Example

Try to hit this URL : https://sandbox.andaman7.com/public/v1/users?_fields=type,administrative.firstName,administrative.lastName

You should get something like this :

[
  {
    "type": "PATIENT",
    "administrative": {
      "firstName": "John",
      "lastName": "Doe"
    }
  },
  {
    "type": "DOCTOR",
    "administrative": {
      "firstName": "Gregory",
      "lastName": "House"
    }
  },
  ...
]

Search

Each resource can be searched according to their fields. To do so, queries must include a query parameter per search field.

For string type fields, the given pattern is contained in the field. The search is case insensitive.
For other type fields like numbers or dates, we provide comparison operators :

Supported operators

Operator	Description	Parameter(s) type(s)
`eq(<param>)`	Equal to <param>	String, number or date
`lt(<param>)`	Less than <param>	Number or date
`le(<param>)`	Less than or equal to <param>	Number or date
`gt(<param>)`	Greater than <param>	Number or date
`ge(<param>)`	Greater than or equal to <param>	Number or date
`between(<param1>, <param2>)`	Between <param1> and <param2>	Number or date

The dates must be in ISO format (ex: 2015-08-27) and you can use the keyword now to refer to the current date.

Example

For example, to search the english translation entries containing “test” we call the following URL : https://sandbox.andaman7.com/public/v1/translations?creationDate=between(2015-07-01, 2015-07-15)&translationEntries.EN=date.

Here is the returned JSON :

[
    {
        "id": "E3DE38C8-1E64-420F-9864-62F70E1F0E19",
        "self": "http://localhost:8080/public/v1/translations/webapp.validation.date?_languages=*",
        "creationDate": "2015-07-02T21:26:49.650+0000",
        "modificationDate": "2015-07-02T21:26:49.650+0000",
        "key": "webapp.validation.date",
        "translationEntries": {
            "EN": "Validation date",
            "FR": "Date de validation",
            "NL": "Validatiedatum"
        }
    },
    {
        "id": "AA75D62C-7FDD-454E-8EA2-0FFCA25EBDC4",
        "self": "http://localhost:8080/public/v1/translations/webapp.monitoring.date?_languages=*",
        "creationDate": "2015-07-02T21:16:35.790+0000",
        "modificationDate": "2015-07-02T21:16:35.790+0000",
        "key": "webapp.monitoring.date",
        "translationEntries": {
            "EN": "Date",
            "FR": "Date",
            "NL": "Datum"
        }
    }
]

Rate limit

By default, each user of the API can send a maximum of 10 requests in a 20 seconds window.
If you exceed this limit, you will get a HTTP 429 “Too many requests” response code.

Each response contains the following HTTP headers :

X-Rate-Limit-Limit: the limit of requests that can be sent in a single time window
X-Rate-Limit-Remaining: the number of requests left for the 20 seconds window
X-Rate-Limit-Reset: the remaining seconds before the rate limit resets

Postman

If you plan to use Postman to test the API calls, please click on the following button :

Overview

REST

HTTP verbs

API key

Authentication

Responses

HTTP status codes

Format

Errors

Hypermedia

Example

Pagination

Example

Filtering

Example

Search

Supported operators

Example

Rate limit

Postman