In the realm of software development, Application Programming Interfaces (APIs) serve as the digital glue that connects various software components, enabling them to communicate and share data seamlessly. API-first development emphasizes the importance of designing and defining APIs as a fundamental step in the software development process. Whether you’re building a web application, a mobile app, or a complex system, adopting an API-first approach is a fundamental strategy. Is this same as API design-first approach? Where to choose API code-first approach? Let’s go through these approaches and decide which one fits for your need.
API-First Development
API First is a development methodology that prioritizes the creation and design of APIs as a fundamental step in the software development process. The primary goal is to establish a clear and well-defined interface along with specification that different parts of an application, or even external systems, can use to communicate and exchange data. Specifications are written in API description language like OpenAPI, which is understandable by both machine and human. In recent years more and more companies are taking the route of API first development.
As the specification or contract of API comes first before creation of production grade code or components, this approach offers several advantages.
- Clear data flow makes the collaboration very easy between teams.
- All dependencies are discovered, contract established. All API’s can be developed in parallel.
- Unnecessary data needs can be challenged.
- Clear vision on security model.
- Easy consumption based on contract before real API gets developed.
Before going into more details on how to implement API first development effectively with different tools and standards, let’s go through design-first and develop-first approach.
Design-first approach
The term API Design-first often used as synonym for API first, but they are not totally same. In the Design-First approach, you start by creating the API’s design or specification before writing any code. Biggest question is where will you capture the interface design? Following are some of the key feature that design documentation should have:
- Detailed enough with inputs, descriptions and examples
- Human understandable
- Machine readable to generate code
This design often takes the form of a detailed API documentation or a machine-readable API specification, such as OpenAPI (formerly known as Swagger) or RAML.
Code or Prototype first approach
In the Code-First approach, development starts with writing the boilerplate code with validations, restrictions that will serve as the API. The API specification or documentation can be created after this. Business logics or API controller service implementation are written afterwards.
How to approach API-First development
Now that we’ve explored both approaches, the question remains: which one is the best?
Let’s first explore whether Prototype first can fits for API-first development. Prototype-first is useful under following scenarios:
- Rapid Prototyping: When you need to quickly experiment with different API ideas and want to iterate on the design as you go.
- Flexibility Matters: In situations where the project requirements are still evolving, and you need the freedom to make implementation decisions on the fly.
- Less no of API’s: For very few no of API of small projects rigid API specification processes might be overly burdensome.
Based on the use-cases mentioned above, it’s clear that Prototype-first doesn’t fit for API-first development except for the scenario of development of only few new API’s for the existing application system. Additionally, this approach has following disadvantages:
- Difficulty in generating detailed enough specification with inputs, descriptions and examples form prototype or boilerplate code.
- Validations or data types used in code doesn’t always gets represented in specification. Application starts drifting from design.
- Focus gets shifted to implementation instead of API.
- High re-work in cases of adjustment needed based on feedback (from stakeholder/consumer) on design. Entire effort of prototyping may get wasted.
Due to all these limitations in code-first approach, the term API Design-first often used as synonym for API first development.
Let’s explore now the design first approach with OpenAPI. How does it fit in implementation of organization wide API-first development and the available tools or libraries.
Fig 1 shows the high-level process for API-first development along with design-first approach. Following are details on those stages.
- Interface design created using OpenAPI specification. You can use Swagger-editor or any other tool as per your need from list of OpenAPI-GUI-Editor.
- Stakeholder’s review and feedback taken at very early stage, even before writing single line of code. OpenAPI-generator can produce basic documentation. If you are looking for something better, try ReDoc or any other tool from this list.
- OpenAPI-generator can definitely be considered as a good option for boilerplate code generation. Alternately you can try API Platform or any other from this list.
- Add business and persistence logic to the boilerplate code in the controller or service implementation.
- Test and integrate the change, deploy and release continuously through pipeline.
For this entire implementation there are many other tools w.r.t OpenAPI which can also be explored based on need like mocking, API gateway integration.
Are you or your organization already started API-first development, but unable to realize the tangible benefits out of this? To know more on what could have been missed, read the next article.
