Historically, API design has been mainly implementation-driven (also called code-first). Nothing faster than quickly prototyping a few endpoints toget

An introduction to spec-driven API development

submited by

Style Pass

2021-07-29 13:00:14

Historically, API design has been mainly implementation-driven (also called code-first). Nothing faster than quickly prototyping a few endpoints together before even thinking about putting together an API specification. Mo specs mo problems. Or is it?

You might recognise the side-effects of a typical product "drift". For example; You want to develop a new REST API for a service or a product, so you start with the beginning (designing the REST API) or with the end (development of the REST API). Along the way, ideas change or have to be adapted because of the iterative nature that is linked to development, but now your specification or documentation is outdated, and you have to rework your tests to keep up with the changes continuously.

Maintaining your specification, code, tests, and documentation as separate parts means that every change must stay in sync in all these layers of your product. This causes double or even triple the work effort and starts to feel like a waste of time. In addition, there is the risk that parts are missed entirely - causing frustration with anyone trying to use your newly developed API.