Message format

All HTTP API responses in our system MUST adhere to the json api v1.0 standard (http://jsonapi.org/)

This applies throughout the whole architecture regardless of which team writes the API or what language it is written in.

"id" and "type"

The "type" should always be a StudlyCase name of an entity that exists in our /wiki/spaces/BPLAT/pages/38539005, for example: "ExternalVODProductMapping" or "User"

The "id" needs to be the primary key of the entity whose state is being represented in the response.

For most cases we use a primary key that is an auto-incrementing "id" column in a table that models an entity.  

The value of this attribute should be used as the "id" field.

For exceptional cases where we use a composite primary key then the "id" value in the response needs to be a JSON string containing the names of the PK columns and their values, for example like this:

{
  "id": "{'product_id': 123,'external_product_id': 456}"
}

This only becomes relevant when the client is interested in the identity of the entity.  For the most part the client is likely to be uninterested, but we want to allow the client the ability to treat a REST entity as an entity (whose identity is independent of it's value) rather than value objects if they so choose.

Time values

Time values SHOULD be unix epoch integer timestamps

Hydration

Every API MUST avoid retrieving data from the database unless it is directly relevant to the API endpoint

Every API SHOULD prefer to return unhydrated collections and require the client to make further calls to obtain details for entities (this is not a hard rule, but rather a guiding philosophy)

Every API MUST include HATEOAS links to help the client find related entities and where the full details of an entity can be found

Caching

Every API MUST emit a cache-control header suggesting to the client how the response may (nor may not) be cached (https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control)

Every API MUST respond correctly to incoming cache-control headers supplied in the request

Every API SHOULD be able to manage incoming etags in the "If-None-Match" header