In recent years more and more companies are taking the route of API first development. Are all of them getting success or tangible benefits from this? I don’t know the answer for all, but I have seen many companies not getting benefits out of this process. In this article we will not only discuss common mistakes or misunderstandings, but we will also discuss some of the solutions which can make your API first development journey successful.
Common Pitfalls:
API First Development is not just another development approach, rather it is a change in MINDSET. It’s a mindset where API is considered as product for end user. There should be buy in from leadership or management of the organization to implement this across the organization. It difficult to implement this on a portion of product API’s instead of all API.
As the API specification design and review takes substantial time and effort, often its misunderstood that it will impact the overall project or product timeline. In reality development effort is very less, as the boilerplate code gets auto generated from specification. Afterwards developers only need to add business and persistence logic to the boilerplate code in the controller or service implementation.
Early stakeholder or consumer feedback is one of the keys for the success. But often teams miss to perform this step immediately after the specification design, rather it done at the end of development. As a result, any feedback or comment on design leads to waste of development effort done on wrong design piece.
It’s quite common that developers start with design first approach but eventually focus gets shifted to implementation. Very soon implementation starts drifting from design or specification. Without use of automated checks to compare API implementation against design leads to failure of the entire process.
Now that we have discussed some common mistakes, lets now look into some best practices which can bring the success in API first development.
Success Factors:
Correct and detailed specification like OAS is definitely one of the keys for success. Every organization has their own common way of API implementations. Like API Gateway, security model or API authentication and authorization, allowed error codes and many other standards like naming, versioning allowed methods (PATCH is allowed not PUT). Any new design should be checked against these standards in an automated way. This can be easily taken care by Spectral which is an open-source tool from Stoplight.
Another key factor is to get early stakeholder feedback on new design or design change. If there is already existing consumer for the API, for any change it must be checked whether existing consumers gets impacted due to this. This can be easily implemented with contract test using pact to prevent any breaking design change by provider API. This guarantees smooth integration for any change in API design.
Sometimes stakeholders or consumer need a mock API service (Till actual service gets developed) as per OAS to provide early feedback as well as parallel development. This can easily be achieved with any mocking tools like Prism.
Did the API implementation go as per the design? This can definitely get answered once API gets consumed by user in Production, but that’s too late. This can definitely get validated with tools like Schemathesis or Dredd.
Entire deployment and release process needs to be automated with CI and CD pipelines along with gating for QA checks. In this way design deployment can be done in iterations also.
These are just some of the key factors, there can be many other factors which can fail one’s journey in API First Development. If you have experienced any of those challenges, feel free to comment.
Takeaway 💡
In this article we didn’t talk about API application monitoring or observability, which is a must have for any API management.
