Pattern Sections
Pattern: API Description 
a.k.a. API Documentation, Explicit Service Contract
Context
A service provider has decided to expose one or more API operations in an API endpoint. Developers of clients (i.e., Web and mobile app developers implementing Frontend Integrations or the system integrators writing adapters for Backend Integrations) are not yet able to code service invocations and do not know what to expect in responses. Furthermore, supplemental interface descriptions are missing as well, including informal explanations of the meaning of the API operations (e.g., parameters in message representations, effects on application state in the API implementation) and related qualities (e.g., idempotency, transactionality).
Problem
Which knowledge should be shared between an API provider and its clients? How should this knowledge be documented?
More precisely:
- How can API client and API provider make their agreement on the functional aspects of service invocation (e.g., data transfer representations and invocation prerequisites) explicit?
- How can this functional information be amended with other technical specification elements (e.g., protocol headers, security policies, fault records) and business-level documentation (e.g., call semantics, API owner, billing information, support procedures, versioning)?
Forces
High-level forces to be resolved and balanced when defining shared knowledge in distributed systems include:
- Interoperability (of clients and providers written for, and running on, different middleware platforms)
- Consumability (including understandability, learnability, and simplicity)
- Information hiding (of implementation details)
- Extensibility and evolvability (as facets of general modifiability and maintainability)
Pattern forces are explained in depth in the book.
Solution
Create an API Description that defines request and response message structures, error reporting, and other relevant parts of the technical knowledge to be shared between provider and client. In addition to static and structural information, also cover dynamic or behavioral aspects, including invocation sequences, pre- and postconditions, and invariants. Complement the syntactical interface description with quality management policies as well as semantic specifications and organizational information.
Example
The “Template for Elaborate API Descriptions” in Figure 3 covers both business information as as well as functional-technical API design concerns.
While the template fits on one presentation slide or document page, API Descriptions that follow this template probably will require more space. In practice, such API descriptions are often made available via developer portals, project wikis, or service documentation websites.
Are you missing implementation hints? Our papers publications provide them (for selected patterns).
Consequences
The resolution of pattern forces and other consequences are discussed in our book.
Known Uses
The Microservices Canvas template proposed by C. Richardson creates Elaborate Descriptions when filled out completely. The template includes implementation information, service invocation relationships, and events produced/subscribed to.
Agile Modeling suggests an informal contract model that can be seen as medium verbose API Description.
Many concrete examples of API Descriptions exist. Here we include Terravis, which uses annotated WSDL according to Lübke and Lessen (2016); so does the Dynamic Interface described in Brandner et al. (2004). Developer portals and Do-It-Yourself (DIY) service registries/repositories make these and complementing business/quality policy information available to API users (e.g., frontend and integration developers). A Swiss software vendor specializing on the insurance industry defines its own API documentation format in its internal REST API Design Guidelines.
Technical API description notations exist in many forms for various distributed computing and middleware platforms:
- Swagger, which evolved into the Open API Specification, WADL, and RAML are IDLs specializing on RESTful HTTP. Swagger, for instance, has the notion of a schema object to “define input and output data types”.
- An alternative is the API Blueprint Specification which also has tool support.
- JSON API and APIs.json also suggest contract notations. Note that JSON API only covers response message structure and content.
- WSDL 1.1 is commonly used to describe SOAP-based Web services; WSDL 2.0 is more expressive but has seen less adoption in practice.
- The
.protofile syntax used in Google’s Protocol Buffers can be seen as a known use of the (technical/syntactical) API contract concept. - GraphQL comes with its own schema language.
- The Apache Thrift Interface Definition Language (IDL) serves a similar purpose and can also be seen as an example of a technical API contract format (data and protocol).
- The Apache Avro IDL originating from the Hadoop project is another example.
- AsyncAPI allows the creation of machine-readable definitions of “Message-Driven APIs”.
- Microservice DSL (MDSL) is an emerging platform-independent IDL that integrates the MAP domain model and patterns.
On a broader level, the following notations and assets also qualify as known uses of this pattern:
- Unified Service Description Language (USDL) is a more comprehensive approach that adds metadata and semantic information to the contract, see this W3C report.
- The SOYA framework implements the SOAP Service Description Language (SSDL) specification in C# and on top of Windows Communication Foundation (WCF).
- In the finance industry, SWIFT uses XML (and WSDL/SOAP) as technical interface description language. An example is the Alliance Access messaging interface. SWIFT also standardizes message exchanges and has elaborate SLAs, starting with a master SLA refined by those for individual services.
SOA maturity levels can help with the decision between minimal and elaborate descriptions, supported by the notations and assets listed above.
More Information
Related Patterns
Depending on mission criticality and market dynamics, an API Description be completed with a Service Level Agreement to specify quality goals – and the consequences of not meeting them. Version information and evolution strategies can be included (see for instance Version Identifier and Two in Production patterns).
Service Descriptor in Daigneau (2011) and Interface Description in Voelter, Kircher, and Zdun (2004) cover the technical part of the API Description.
Other Sources
An online API Stylebook collects and references related documentation advice in a dedicated design topic. Recipe 14.1 in the RESTful Web Services Cookbook by Allamaraju (2010) discusses how to document RESTful Web services. The Engagement Perspective of Zimmermann, Tomlinson, and Peuser (2003) collects WSDL and SOAP best practices; much of the given advice also applies to other API contract syntaxes. See for instance an OOPSLA 2008 tutorial. The Australian Digital Transformation Office (DTO) has a best practice rule “document your API” that lists examples of good API documentation.
The notion of Design-by-Contract was established by B. Meyer in Meyer (1997) in the context of object-oriented software engineering; his advice can also be adopted when defining remote API contracts.
The specific role of data in interface contracts is explained in “Data on the Outside vs. Data on the Inside” by P. Helland Helland (2005).
The practice collection Design Practice Repository (DPR) features a stepwise service design activity and an API Description artifact Zimmermann and Stocker (2021).