In this article, I would like to talk about the spec-first approach to REST API development.
While traditional code-first REST API development goes like this:
- Writing code
- REST-enabling it
- Documenting it (as a REST API)
Spec-first follows the same steps but reverse. We start with a spec, also doubling as documentation, generate a boilerplate REST app from that and finally write some business logic.
This is advantageous because:
- You always have relevant and useful documentation for external or frontend developers who want to use your REST API
- Specification created in OAS (Swagger) can be imported into a variety of tools allowing editing, client generation, API Management, Unit Testing and automation or simplification of many other tasks
- Improved API architecture. In code-first approach, API is developed method by method so a developer can easily lose track of the overall API architecture, however with the spec-first developer is forced to interact with an API from the position if API consumer which usually helps with designing cleaner API architecture
- Faster development - as all boilerplate code is automatically generated you won't have to write it, all that's left is developing business logic.
- Faster feedback loops - consumers can get a view of the API immediately and they can easier offer suggestions simply by modifying the spec
Let's develop our API in a spec-first approach!