Despite the fact that API first approach has been around for many years, interest in it does not decrease and new articles are published.
There's a lot of interest thanks to the popularity of microservices and distributed systems, as well as actively growing as-a-Service solutions and add-ons marketplaces where developers can build and publish their applications and APIs on top platform's APIs.
Technical articles and presentations on API-first mainly focus on the technical implementation and use of certain tools, such as back-end code generation from OpenAPI specification, as well as rising interest to AsyncAPI specification that brings standard to event-driven architectures.
However, I think it is important not to confuse goals and methods of achieving them; remember the basics of API first!
What is API first?
First of all, it is a development process and strategy.
Think about your API as a product for other developers even if it's an internal service. Apply agile development principles to the API design and definition. This allows us to establish a contract for how the API is supposed to behave. This contract is crucial because it improves the interaction of developers and allows you to get a system consisting of a reusable, and extensible building blocks, which brings a great value for business.
An analogy is a test driven development (TDD), since it's also API first approach. Start with an interface, and the test will be the first consumer of your API.
The API contract itself can be specified in various ways which depend on the specifics of project and context.
It could be an OpenAPI specification, request/response JSONs, or interfaces.
For example, at Infobip most of the services define their API through Java interfaces and data models, on the basis of which the OpenAPI specification is generated, if necessary.
If you are designing an API for a web or mobile client of your service, design it as a product for external clients in order to avoid situations when you need to develop separate APIs for every new use cases.
The benefits of an API first approach are similar to agile development processes:
- Fast feedback that allows you to make adjustments earlier while the cost of change is low;
- No constraints inherited from wrong abstractions & data models, you better understand customer needs by collaboratively discussing and adapting APIs
- Decoupling & parallelisation of work, teams can work independently having a common source of truth in the form of an API contract.
What is code first?
With a more traditional code first approach, the main functionality of the application is first developed and then an API for consumers and contributors is inserted on top of it.
This approach works well only for small APIs, mainly internal, when requirements are clear and stable.
Tools & Workshops We Use For 1600 Applications
Let's see briefly how we deal with internal & external APIs at Infobip. Infobip is a global communication platform that consists of over 1600 applications (service types) with hundreds of databases, data pipelines and support systems. More than 80 engineering teams work on. We have about 20 products that expose public APIs. At this scale it is vital for us to have reliable tools that synchronize and standardize service interactions while maintaining flexibility and speed of development.
As I mentioned, most of our internal services are written in Java or Kotlin. They expose their APIs as Java interfaces (we call them "connectors") and register them in home crafted remoting system. This system transparently builds HTTP APIs for inter-service communication. For non-JVM services we use sidecar pattern.
Dependent services can just import "connectors" and use them without worrying about implementation. In this way, the contract is defined and development is completely independent.
For APIs that should be exposed publicly we use a solution based on springdoc-openapi that generates OpenAPI specification from Java/Kotlin classes. Non JVM services can expose OpenAPI specification by themselves on a dedicated endpoint. Thus, regardless of how the specification is created, it is a public contract.
From that specification we generated public documentation and client libraries using OpenAPI Generator based pipeline. Library generation also helps maintain the quality and stability of specifications.
What Works For Us At Infobip
- Focus on API design before development;
- Treat your API as a public product;
- Tools & workflows are secondary.
In most cases, there is no need to dive into the complexity of OpenAPI right away.
OpenAPI has essentially become an industry standard and it is easy to use as a common language between components that guarantees interoperability and simplifies API management.
If you want to know more on this topic give some likes & comments ;)
Top comments (0)