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"

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