Introducing api.md

[vinaysrao1]

Introducing API standards for ROOST software. It would be useful to get a conversation going on (1) OpenAPI as standard (2) Being standard ready immediately - Coop and Osprey aren't (3) Are we design first or code first re. API specification (4) should we have API standards only for external facing API or for internal APIs as well

[tgthorley]

How opinionated do you want to be in this documentation we could be much more specific about a bunch of topics, but it seems like the aim here is to be very general. Areas that it might be worth considering adding a little more guidance so that we don't have too much of a divergent approach across systems:

• Authentication method(s) documented (and error responses)
• Standard error schema (problem+json or equivalent)
• Idempotency guidance for POST/PUT/PATCH
• Naming conventions (paths, resources, fields)
• Status code expectations