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 challenge is finding an API architecture and defining the methodology.
API architecture is way more than the correct application of REST principles. So what is API architecture? API Architecture spans the bigger picture of APIs and can be seen from several perspectives:
API architecture may refer to the architecture of the complete solution consisting 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.
API architecture may refer to the technical architecture of the API 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 managing APIs.
API architecture may refer to 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.
API architecture may refer to the design decisions for a particular API proxy. To document the design decisions, API description languages are used. We explain the use of API description languages on many examples.