APIs are languages that allow applications to exchange information. Today, there are many possible technologies that can be used to design and implement APIs. But before settling on one technology, it is also important to decide which API style to use. In this introduction, we have a brief look at the 5 major API styles.
- Tunnel Style: An API is a collection of functions that can be invoked remotely.
- Resource Style: An API is a collection of resources that allow various kinds of interactions.
- Hypermedia Style: An API is a collection of interlinked resources just like resources on the Web.
- Query Style: An API exposes a structured data model that can be queried and updated with a generic query language.
- Event-based Style: An API is a collection of events that are published by providers and can be subscribed to by consumers.
In this introduction, we have a brief look at these 5 styles and look at the differences in the main abstractions they build on. These 5 styles are the foundation of popular approaches and technologies such as REST, OpenAPI, HTTP, gRPC, GraphQL, and Kafka.
Picking an API style (and a technology that is a good fit for that style) is a design choice, and like any design choice, it should be based on design considerations such as API consumers, API producers, and the API scenario. Knowing the styles will help to better understand the decision to be made, and to make good choices when it comes to designing and implementing an API.
The most important lesson to learn about these 5 API styles is that there is no “best style”. It may be useful to have a default choice to fall back to all other things being equal, but it still is a good idea to have these styles in mind as general starting points for designing APIs.
API design should be approached as a process where a given problem can be solved in different ways, none of them being inherently worse or better than the other ones. The design choice of style and technology is a question of context (designing an API product for API consumers) as much as it is a question of the API itself.