tags : API Design, Custom Protocols
FAQ
Swagger vs OpenAPI
New name of Swagger is OpenAPI
Do you need open API?
- It’s a documentation thing, you can roll without it, but if the API is getting too big, something like open API can help. It’ll help you generate automated docs, mocks etc etc.
- You can just document it with things like org-mode verb, just using postman collections etc.
- “OpenAPI tries too hard to cover every base and has become the SOAP of this generation.” - some internet person
Relation of spec and programming languages
The spec(openapi.yaml) file is standalone, it’s independent of programming language. This is true if using spec for only spec and documentation. But for codegen, there are too many tools in different languages w different levels of support and implementation.
API Design first or code first?
This is not OpenAPI specific, it can be about any specification in general.
Why API Design first?
- Sometimes its costly for code first APIs, we need people to be on the same page about it.
- In that case, we can do a API design first approach and we can use it as ref when writing code.
Why Code first?
- Historically it’s code first and then we document our API with something like OpenAPISpec.
- Issue w writing specs before code is that u are not aware of what the api looks like finally (incremental)
Components
Data part
- This is where you define the schema of the things that can be accessible via the API
- This uses JSONSchema, Protocol Buffers can be an alternative for this data part.
Network part
serverandpathsof the API
Structure part
Open API is about describing the API, if you want to structure the API responses, you can use JSON API.
- JSON API
- API spec for building apis in json
- Gives more structure to the “response” itself
- OpenAPI can be used with JSON API. They compliment each other if needed.
- See OpenAPI 3.0 spec that conforms to JSON:API - JSON API
OpenAPI related tools
Writing the spec
- You can handwrite it, but it tedious
- Postman and Insomnia has some support also
- Stoplight Studio is good if you buy it
- Use codegen
Documentation
- ReDoc (doc gens:speccy(old))
- slate (doc gens: widdershins)
Codegen
- You need to find a generator that works for you, here are some options
Client = SDK,Sever = Server stub
Spec to Code (Boilerplate generation)
- Multi-lang: kiota(client), openapi-generator(client&server)
- Go: deepmap/oapi-codegen(client&server), ogen(client&server), go-swagger(client&server but v2)
- TS: openapi-typescript-codegen, openapi-typescript, openapi-codegen, swagger-typescript-api
- protocol buffers: gnostic
Code to Spec (Spec generation, more realistic for small use-cases)
Mock server
Alternatives?
Async
- OpenAPI not fit for documenting event driven APIs, It’s mostly meant for REST
- https://github.com/asyncapi/spec
Fern
- For REST, but tries to be better than OpenAPI
- https://github.com/fern-api/fern
GraphQL
Goa
Protocol Buffers
- See Protocol Buffers