Basic Concepts in API Design and Refactoring

API Domain Model

We share the API domain vocabulary and concepts with Microservice API Patterns (MAP).

Section 3 of “Interface Evolution Patterns — Balancing Compatibility and Extensibility across Service Life Cycles” explains:

At the most abstract level, there are two kinds of communication participants (or participants for short) that communicate via an API: the API provider and the API client. An API provider exposes any number of APIs; an API client uses any number of APIs. One participant can also play both roles (for instance, in an API Gateway […] in which the communication participant offers services as the provider of the gateway and is client to the services shielded by the gateway). In the client role, a communication participant uses API endpoints to access the API. An API endpoint is a provider-side end of a communication channel that specifies the location of the API service resources so that APIs can be accessed by API clients. Each endpoint thus needs to have a unique address such as a Uniform Resource Locator (URL), as commonly used on the World-Wide Web, as well as in HTTP-based SOAP or RESTful HTTP. Each API endpoint belongs to one API; one API can have different endpoints.

Our refactorings focus on the API implementation on the provider side, targeting endpoints, but also the operations they expose. These are identified by an additional operation identifier, which depend on the underlying technology: HTTP comes with a predefined set of methods (also called verbs), such as GET or POST. In SOAP, the operation is identified by the top-level XML tag in the message body. To invoke an operation, clients send a request message to the endpoint, which may respond with a corresponding response message. API operations are often mapped to code level methods, functions or procedures, with request- and response messages mapped to parameters and return values respectively.

Messages have representations consisting on multiple elements. Finally, all operations are part of the technical API contract. This contract usually details all possible conversations and messages down to the technical parameter representations and addresses. Thus, the contract describes the API endpoint. API contracts are necessary for realizing any interoperable and testable technical communication; that is, in order to be able to communicate, API clients must comply with the API provider’s contract for those parts of the API that are used. This can be done explicitly at design time (supported by static contracts) or at runtime (requiring dynamic contracts).

The following figure visualizes the elements of the API domain model and their relations:

UML Sketch of MAP Concepts

Terminology Index

This glossary forms the vocabulary of the ubiquitous language established by this domain model.

API. The top-level concept that connects (and separates) API clients and API providers.

API Description. Defines the API capabilities either briefly or elaborately.

API Endpoint. Bundles a set of related operations under a single address.

Message. The payload that travels from API client to provider and back.

Operation. A unit of work that can be called to exchange data or trigger processing.

Request. What an API client sends to the API provider when calling an operation. Can but does not have to have payload content.

Response. What the provider returns to a client when done with operation invocation. Can be empty (or merely contain a status code).

Microservices. Microservices implement the SOA style in a constrained, modern way. Services expose APIs.