REST and Hateaos

This document describes how the API is structured and how you can expect to interact with it.

Our API is built by the principles and pattern of the RESTful API. This means in short:

• We work with resources that are represented by a URI
• Fetching a URI with a GET call is idempotent.
• Creating a resource is always done by a POST call.
• Resources are partially updated with a PATCH call.
• Resources can be replaced by a PUT call.
• Resources are deleted by a DELETE call.

For a full reading on this, we'd like to refer you to this blogpost by Phil Sturgeon.

We do want to elaborate on the Hateaos part of this implementation.

We add certain links and state representation to our responses to make our APIs easier to work with. In principe, this means that a response is always wrapped in an object.

For a list, you'll always see this structure:

{
    results: [],
    state: {
        pagination: {},
        query: {},
    },
    includes: {
        'inclusionName': []
    }
}

In the results attribute of the response, you'll find the resources that were requested. In the state attribute you'll find the information about the pagination (always present) or the query (present on endpoints that support querying) you sent to the API. In the includes you'll find data that we enriched the API response with. This is documented per API endpoint what is available and what it will look like. Each attribute under this will have a list of the same type of resource.

For a single resource, it will look like this:

{
    result: {},
    links: {},
}

Mind the fact that for a single resource it will the result attribute is singular, whilst it is plural for the list endpoint.

The result attribute will contain the resource you have requested. The links attribute will contain REST URIs to related resources or subresources of the resource you have requested.