​Requests & Responses

The API follows familiar RESTful conventions for requests, responses and errors.

• Fetching resources is done using GET requests.
  • Query parameters can be used to filter, sort and paginate the results.
• Creating resources using POST requests.
• PUT, PATCH and DELETE requests aren't currently used.

​Responses

• All responses are returned in application/json format.
• Errors are mostly communicated using HTTP status codes with a JSON body.
• Successful responses will be 200, 201 or 204 (if there resource to return).

​Collections

• Endpoints that return a collection of resources will return a JSON object with a <resources> field that contains an array of resource objects.
  • For devices, the resource is devices, for sites, the resource is sites, etc.
• The response will include a total field that contains the total number of resources in the collection (not the number of resources returned in the response).
  • The total field is represented the total number of resources that match filters, not the total number of resources in the database.

For example, fetching devices will return the following structure:

{
  "devices": [
    {
      "id": "1",
      ...
    },
    {
      "id": "2",
      ...
    }
  ],
  "total": 3
}

​Errors

Common error status codes are:

Once mutation endpoints are added, we will return a JSON body with an error message.

{
  "error": "Bad request",
  "message": "Site name must be unique"
}

Endpoints can return multiple messages in the message field.

{
  "error": "Bad request",
  "message": ["Site name must be unique", "Site name must be at least 3 characters long"]
}