Summaries of artifacts, templates, practices, and techniques for agile architecting (DPR-mm) and service design (SDPR-nn).

DPR Git Pages HomeArtifacts Index

Artifact/Template: API Description

also known as: Service Contract

An API Description answers the following questions: “Which knowledge should be shared between an API provider and its clients? How should this knowledge be documented?”

Motivation (Addressed Information Need)

Quoting the context section of the API Description pattern on the MAP website, let us assume that “a service provider has decided to expose one or more API operations in an API endpoint; the number, name, and synopsis of these API calls have not been specified yet. Therefore, 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 calls (e.g., parameters in message representations, effects on application state in the API implementation) and related qualities (e.g., idempotency, transactionality).”

Desired qualities are understandability, interoperability, and extensibility (preserving backward compatibility as much as possible).

Usage (Produced and Consumed When)

Explicit, both human- and machine readable API specifications (or service contracts) are typically created during design elaboration and transition activities. In the Stepwise Service Design activity in DPR, they are created in Step 6 (and then evolved in Step 7).

Mike Amundsen’s seven-step Web API design method features “Create a Semantic Profile” in Step 5. Service description and profile formats are created in this step, hence it produces an API Description in DPR and MAP terms.

Template Structure and Notation(s)

The API Description on the MAP website advises to define “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.”

API Description Template (Source: MAP Website)

James Higginbotham compiled the minimum documentation required for an API in a blog post.


A minimal technical API Description is (notation: MDSL):

API description HelloWorldAPI

data type SampleDTO {ID, D} 

endpoint type HelloWorldEndpoint
  operation sayHello 
    expecting payload D<string>  
    delivering payload SampleDTO

API provider HelloWorldAPIProvider
  offers HelloWorldEndpoint

API client HelloWorldAPIClient
  consumes HelloWorldEndpoint

The Microservice Canvas template proposed by Chris Richardson creates elaborate API Descriptions when filled out completely. The template includes implementation information, service invocation relationships, and events produced/subscribed to.

See the end-to-end service design demo “Domain-Driven Service Design with Context Mapper and MDSL” for technical, platform-specific contracts generated from the platform-independent MDSL.


Hints and Pitfalls to Avoid

The API Description pattern text in “Interface Evolution Patterns — Balancing Compatibility and Extensibility across Service Life Cycles” (@LuebkeZimmermannEtAl:2019) recommends:

Origins and Signs of Use

Interface Description/Definition Languages (IDLs) have been around for a long time; the CORBA IDL is a prominent predecessor of OpenAPI (and WSDL). OpenAPI currently seems to dominate the Web API contract language realm.

Usage of OpenAPI specifications or other platform- and technology-specific IDLs is easy to detect (but less common than one would expect, given the importance of interoperability and understandability of API implementations and their clients). The same holds for MDSL; informal descriptions are harder to spot as they may vary a lot.

The Known Uses section of the API Description pattern lists many notations and tools.

More Information

Data Provenance

title: "Design Practice Repository (DPR): API Description"
author: Olaf Zimmermann (ZIO), woth contributions from other MAP authors
date: "03, 31, 2021"
copyright: Olaf Zimmermann, 2020-2021 (unless noted otherwise). All rights reserved.
license: Creative Commons Attribution 4.0 International License