Why should one, design an API first before starting coding?
Well first, lets ask, would you write code a UI without first having a design and mock ups first?
The answer is, You could, but once you show it to stakeholders they will most likely want changes in the code. It’s more costly to change compared to having design created on a diagramming tool first.
Early, in my career as a developer I would work with product, understand the requirements, and then code the API, based on my interpretation of the requirements were, and I would declare their response and request objects contract schema.
And I would add reference to swagger to my .NET app, which would auto generate the swagger/openAPI spec if you navigated to the service running.
As a developer I thought great, I needed only to code and not I did not need to keep a separate file up to date.
However, in order for my QA team to start developing automated tests for contract testing and functional testing. Let alone the actual consumer of the API, I first had to deploy the service so I had to 1st make sure I had my CI pipeline and some place to host the application.
This lead to me as a developer being a blocker for the QA to write their tests and also for the consumers to start integrating.
Also this was normally the first time I would be able to submit it for review by the actual consumer. Which would often cause re-development effort as changes would need to be made, causing more lead time.
A developer maybe thinking “so what” less work for me. However teammates and also stakeholders might think otherwise.
So first I advocated that before functional code was written the developers should create a skeleton, API and deploy it, and have mock information in it, which to QA, and any other team could use to create a tests and start consuming the mocked API.
(Please note: that this was also before we started to use API Gateway to proxy our APIs, and when each deployable service would have its own API, instead of a more customer expreance designed API)
This, way of working, let me and others who adopted this way of working to allow others to work on their tasks sooner and also reduced the feedback cycle time.
However once I moved into a leadership role and became more interested in story lead tim, reducing waste in the development process. I started to see the waste of the back and forth across all teams and developers. I saw that it needed to be improved.
By this point we started to see the benefits and was able to compare the time waste of stories between developers who delivered the upfront mocked API vs the devs who didn’t.
We clearly saw that the more upfront design we did, the less time waste in waiting time and also it reduced the magnitude of effort a dev would spend changing making the needed changes compared to devs who didn’t produce the mock first.
However we still saw that later in our development lifecycle, technical product owners and in certain cases the consumers would request changes to things like naming of the route, how the request and responses were structured and even naming of objects.
So we decided to give design-first a go and share that spec with technical and non-technical people , this allowed us to design the APIs as a team instead of one or two developers working together and coding and then getting feedback.
By design-first, we cut the time spent in our development process going back and forth because we were able to review the API as a collective and make changes quickly to the spec.
For sometime we had pushback from developers that it would involve extra work, however we were able to show from our story tracking system that it was reducing the amount of dev time per ticket and also reducing the lead time of stories.
Now, to be honest, we didn’t adhere to design first, all the time, at least not until we started developing lambda functions and more micro micro services which independently didn’t make sense to have their own API deployed indecently, instead they served the endpoints of APIs that were proxied by an API Gateway. The different endpoints were served by different micro services and functions that were actually developed by different dev teams.
We, I, quickly found out that once you start using API Gateways and move more into cell-based architecture with serverless functions, code-first design not only becomes a bottleneck but also a becomes problematic. Especially when you start performing centralised logic like authentication and authorisation at the API Gateway because then your actual API schema which consumers consume, at least from my experience, different from the actual code which serves the operation and I found its cheaper to design first than to code first.