Skip to main content

Standardize API Documentation

Context​

Microservices are being adopted. There are multiple microservices with their own APIs and documentation. There is no standardized way how to document a microservice.

Problem​

  • Every microservice uses different API documentation mechanisms
    • Navigating different kinds of API documentation makes accessing knowledge about the system more complex
    • Tools to make API discovery easier cannot be used

Solution​

Standardize the API documentation format.

In practice, natural languages and open standards as RAML and YAML are used frequently. The OpenAPI initiative (or known as Swagger) offers a well-adopted standard for documenting RESTful APIs. The benefit of those open standards is the combination of human-readability (by format, but also by UI applications) and machine-readability, which enables to multi-use the documentation, e.g. for offering search and discovery mechanisms for APIs, or to generate client code.

If consumer-driven contract tests are adopted they might be a good addition to the existing documentation as they describe how the API is used from the perspective from the clients.

This technique is a specialization of establishing standards.

Maturity​

Proposed, to be evaluated.

Sources of Evidence​

L5:

  • Quality attribute "open interface" cited once in analyzed papers
    • Microservices should provide open descriptions of their APIs, GUIs, and messages format
  • modeling languages in literature: RAML, YAML (Swagger), CAME
    • RAML and YAML are open standards describing REST-like messages
    • CAMLE conceptual graphical design for SOA - integrates wit CAOPLE (agent-oriented systems modelling language)
      • Combination already used for modeling microservice architecture of CIDE (proposed IDE for microservices)
  • Code snippets to describe data model: JavaScript, JSON, Node.js, Ruby

L24:

  • Context: requirements for benchmark application
  • view with communication channels required

L26:

  • Self-describing or standardized pattern for documentation
  • Examples for API standards: RAML and Swagger (evolved to Open API)
  • Can be used to discover / make APIs the searchable

L31:

  • Only contracts and the microservice name to be known to call another microservice
  • They used Swagger to document API
  • => easy learning curve

L45:

  • Context: recovery of architecture, DSL meta-model for microservice-based systems
  • use communication logs to recover interface (provider and consumer side)
  • Connect the interfaces via a "link" in the model
  • Results in a box-and-lines visual model

L46:

  • context: enterprise
    • API registry / repository (pendant to SOA service registry/repository)
    • make interfaces exposed to consumers visible
    • standardized format
    • access controlled
    • search and retrieval capabilities => design time lookup of API specs
    • central location for governance of API portfolio
  • Should contain more than only API
    • Status
    • Ownership
  • Discoverability of interfaces
    • look up and find interfaces without knowledge of underlying technology implementation or location

L49:

  • Context of microservice validation
  • Microservices offer documentation
    • open and standardized interface that describes all available communication methods (
    • API or GUI
  • Microservices standard contracts
    • messaging direction, message origin, and destination
    • => to track all messages transmitted between microservices => build a messaging graph

L52:

  • enterprise context, EA mini descriptions
  • M1 contains meta-data of microservice
    • purpose
    • API endpoints
    • usage costs
    • communication channels

L53:

  • in context of IoT systems
  • need to document syntactic and semantic level of APIs
  • important to search microservices and compose them
    • propose ontology for service description and discovery

LN44:

  • Context: Security issues by layers
  • Service/application layer
    • clear and well-documented APIs as "basic software engineering practice" to mitigate security risks

Interview A:

  • REST: Swagger as tool
  • Contracts from CDCT

Interview B:

  • Should be standardized
  • OpenAPI as alternative for API documentation

Interview C:

  • Many suggestions from research how to document APIs
  • but best we see is OpenAPI (same state as before 30 years)
    • only syntax
    • no semantics,
    • no quality attributes (as how fast, how reliable)
    • no information which transaction criteria
  • does the current state not suffice?
    • ideas from research since 30 years (e.g. 200 extensions fpr WSDL)
    • but practitioners ignored it, and systems are still running
    • it works, but might be suboptimal - that might be okay for us
      • would offer benefits, e.g. recognize mistakes earlier
      • front-loaded investment, hard to communicate that to people
    • maybe it is more natural to go with "Lets make a good-enough plan and get started. We will learn on the way anyway and readjust here and there";
      • fits more into the nature of the human, very popular in business administration
    • "try and error" => chaos engineering formalizes the try and error

Interview D:

  • Context: microservice documentation
  • What do document? how much to document?
  • Where to tools help me?
  • People think that just letting run Swagger => everything is documented
    • => Nonsense
    • Consequently, most documentation is lousy
  • Context: API documentation
  • ideal:
    • REST: instead of Swagger serve documentation via content type HTML instead of JSON
    • that is real REST maturity level I-don't-know-what => self-documenting
  • need for minimal consensus what is documented, how, and where it is to find
    • => discoverability of APIs
      • believes that this is not sufficient
      • => need for active communication mechanism