Document a set of design principles for the API and Data Model

[jackdos]

In order to assess proposed changes to the API and data model, it would be nice to have a set of clearly articulated principles that we are trying to achieve. Some principles we might want to adopt could be mutually exclusive, so we should also use this as a way to say what we're trying to achieve, e.g.

Each api response object should contain the minimum information that is necessary for a consumer to be able to determine the full context of the object

might be seen as fundamentally conflicting with something like

Consumers should receive the full context of an object with the minimum number of API calls

The conflict comes from whether you make reference to other related objects by including just a reference, (minimising the response but requiring the consumer to make follow up api calls) or whether you include nest the full related object (minimising the number of API calls, but bloating the response).