What most API design books focus on is the use of HTTP methods, URL design, HTTP status codes, HTTP headers and the structure of the resources in the HTTP body. However, this is actually the smallest challenge when building APIs. The real technical challenge in many API initiatives is finding an API architecture and defining the methodology. This leads us to an interesting question …
So what is API architecture? It is way more than the correct application of REST principles. It spans the bigger picture of APIs and can be seen from several perspectives.
The Architecture of the Overall Solution
The overall solution consists not only of the API itself but also of an API client such as a mobile app and several other components. API solution architecture explains the components and their relations within the software solution.
The Technical Architecture of the Platform
When building, running, and exposing not only one but several APIs, it becomes clear that certain building blocks of the API, runtime functionality, and management functionality for the API need to be used over and over again. An API platform provides an infrastructure for developing, running, and marketing APIs. Often the API platform is further split up into
- An API development platform
- An API runtime platform, or API gateway
- An API engagement platform, API portal, or developer portal
Altogether these platforms are sometimes also called API management platforms.
The Architecture of the API Portfolio
The API portfolio contains all APIs of the enterprise and needs to be managed like its product. API portfolio architecture analyzes the functionality of the API and organizes, manages and reuses the APIs.
The Architecture of the API Proxy
The design decisions for a particular API proxy are essential. We often refer to the design decisions regarding a particular API proxy as API design. To document the API design decisions, API description languages are used.
If the client calls the API, it is best practice to use REST, GraphQL or gRPC for the API design. You should check out the comparison of architectural styles for APIs.
If a server should notify the client, webhooks are a typical architectural pattern.
Wrapping up
So there you have it. The four meanings. Do you want to know more about it? Check out the API Architecture Book.
Also published on Medium.
