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

[vinaysrao1]

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

Thanks Tom.

Here are my thoughts

1. Auth: The tools are self-hosted and internal to corp env. They have to accept specific auth mechanism of the org that implements. Even action and access levels should be reflected in RBACs that orgs are likely to set up at their security level.
2. Error schema: I think this is useful. We are probably early in our journey. I do think it is imp to follow through.
3. Idempotency: This is probably immediately useful and worth checking. I am inclined to add this.
4. Naming conventions: Good to have, probably worth picking up with error schema. Is there is a good reference for this?
5. Status code expectations: Probably worth taking up after idempotency.

Love to hear what others think?