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 …

What is API Architecture?

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.

What is API Architecture? – More than you think.

Also published on Medium.

Matthias Biehl

As API strategist, Matthias helps clients discover their opportunities for innovation with APIs & ecosystems and turn them into actionable digital strategies. Based on his experience in leading large-scale API initiatives in both business and technology roles, he shares best practices and provides both strategic and practical guidance. He has stayed a techie at heart and at some point, got a Ph.D. Matthias publishes a blog at api-university.com, is the author of several books on APIs, and regularly speaks at technology conferences.