An Intellyx Blog Post for WireMock by Eric Newcomer
“API-first” is the mantra for the right way to develop an API.
Many people interpret this as starting with the OpenAPI specification, but an OpenAPI specification is complex and can require a lot of editing and rework when an API design is still changing – which is very often the case.
It’s much better to create a prototype first, especially when reviewing the API with a business analyst or with the API consumer. It’s better to involve all stakeholders, in other words, as soon as possible and complete the “API first” design collaboratively.
The prototyping approach is comparable to the practice of mocking up a GUI on storyboards or wireframes and showing it to the user before starting to code the app.
The point is, you want to get feedback on the design before doing a lot of work that might have to be redone later if it doesn’t meet requirements.
A typical requirement is to support a great customer experience, which users expect from mobile and web applications.
The right kind of API delivers the right data to the app at the right time, and sends the data from the app to the database, as users expect. It’s not just the GUI, it’s also the API.
Therefore an essential part of the API-first approach is confirming that the API supports the expected user experience, before starting development work.
Basically this means working with the user (or the user’s proxy) on an API prototype to finalize the API prototype before designing the OpenAPI spec and generating the API.
In other words, prototyping or “API mocking” is a better approach to the API first design process, rather than starting with writing the OpenAPI spec.
Modern tooling should prototype APIs via API mocking. Once the design is finalized, the tooling should generate the OpenAPI spec from the mock.
