Question
- What do we want to achieve?
- What are possible solutions
- What are the differences of the possible solutions
- What are the proposed solutions
What do we want to achieve
- We want to define our endpoints, payloads and responses
- Tell if it needs auth
- Talk about specific headers
- Generate tests from it
- Data modelling
- Payload
- Params
- Info about the flow
Specification languages
There are a handful worth talking about
Postman’s blogpost is quite certain that OpenAPI is the way to go for the following reasons
- Open source ecosystem
- Tooling agnostic
- ‘won’ the API describing war
OpenAPI has quite a lot of tooling available.
However, RAML is also said to be ‘modelling’ an API whilst OpenAPI is ‘describing’ an API. A distinction of what we would like to do. Since we could describe our API with auto generated specs, it might not be the best fitting solution for us.
That said, I found little information about RAML in general.
Even though Grant really liked API Blueprint, the project is abandoned and didn’t have any meaningful updates in over a year.
TypeSpec seems a worthy contender, especially as it lets you write ‘code’ for OpenAPI Specifications.
OpenAPI Specs
Either json or yaml.
RAML
yaml