Table of contents
What is API-First
API-First Design simply means APIs are treated as basic building blocks and developers visualize the final product in terms of these building blocks. Instead of worrying about various possible clients (i.e. Frontend App, mobile apps, IoT devices, other APIs/Services) and how the APIs will be consumed developers focus on visualizing API contracts and capabilities. Reusability and Consistency are the backbone qualities for good APIs. Specifications like OpenAPI come into the picture for providing an API description language to establish a contract for how the API is supposed to behave. Using this approach API design becomes more important and often requires collaborating with stakeholders on API interface and what an API can/can’t do. Based on feedback once API contact(aka specification) is final, it can be shared with consumer application developers to kickstart their development. They can mock the API through specifications and start their development in parallel before any API code is written.
Why use API-First
Data is a new currency which is been traded by a variety of devices and platforms. APIs are the most popular mode of Data transfer which means it’s important these APIs are built quickly and versatile. An API-first strategy allows organizations to build such APIs in a deterministic way and with minimum issues. Treating APIs as “first-class citizens.” avoids a lot of back and forth discussion post-development which might result in other approaches, resulting in delays and costs.
Benefits for API-First
- Multiple Teams can work in parallel API-First involves establishing a contract. While API developers working on implementing the contract downstream teams can mock these services and work on developing dependent features. As everyone honors, an agreed-upon contract there is no way we will end up in a discussion like “ Ooh I was expecting Tokoyo but you are sending me to Paris” which can derail project progress.
Reduces the cost of developing apps API-first design also allows most problems to be solved before any code is even written which helps prevent problems when it is time to integrate APIs with applications. It’s great for doing a proof of concept or developing an MVP as we can see APIs behavior upfront and based on that recalibrate the idea.
Increases the speed to market Building an API is simple nowadays (though that might not be so true for building good APIs ). For API development, a framework like SpringBoot has removed a lot of boilerplate code/configuration and made developers’ life easy. If we combine it with API-First and use specification provider like Open API it will reduce time to market a great deal. There are tools for creating a specification/mocking and testing services also plugins that can generate code based on specifications like Open API Generator.
- Ensures good developer experiences Consumers of APIs are most often developers, and developer experience (DX) can make or break the success of an API. API-First ensures that developers have positive experiences using your APIs. Well-designed, well-documented, consistent APIs provide positive developer experiences because it’s easier to reuse code and onboard developers, and it reduces the learning curve.
Resources
- open api
- maven openapi-generator