Write first draft api spec document

[gra-moore]

Assuming the data model updates are made the specification can be written with no backwards incompatibility.

The spec will state some expectations around use of the model and implementers will need to respect those to be compliant.

Note these requirements only relate to 4 properties.

There is already a draft pull request for the API as it is based on lots of previous work.

[cookeac]

Resolved by #283

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.