Published: 20 August 2023
Known Uses
In the Dutch Public Sector, API documentation must be provided in the form of an OpenAPI definition document which conforms to the OpenAPI Specification (from v3 onwards). The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to RESTful APIs, which allows both humans and computers to discover and understand the capabilities of the service without access to source code or through network traffic inspection. An API is as good as the accompanying documentation. The documentation has to be easily findable, searchable, and publicly accessible. Most developers will first read the documentation before they start implementing. Hiding the technical documentation in PDF documents and/or behind a login creates a barrier for both developers and search engines.
To make the OAS document easy to find and to facilitate self-discovering clients, there should be one standard location where the OAS document is available for downloadr. Clients (such as Swagger UI or ReDoc) must be able to retrieve the document without having to authenticate. Furthermore, the CORS (Cross-Origin Resource Sharing) policy for this URI must allow external domains to read the documentation from a browser environment.
In the Dutch Energy Sector we think that documentation should never be a voluminous document. When extensive documentation seems necessary, the functionality is probably too complex…
Examples: In the API registry of the DSO developers portal (DSO: Environment and Planning Act of the Netherlands which is expected to come into force on January 1, 2024) we can see the following:
- API OAS specification
- Link to conceptual information model (semantics of the payload)
- Link to request an API Key
- Functional documentation of the API
- Link to a dedicated forum to raise questions or provide feedback
Another example is https://developer.overheid.nl/apis/vng-brc. Again there is a link to the API OAS specification and a link to a dedicated GitHub repository. The latter provides business contexts and a standard way of raising issues. Also, (anonymous) test data can be obtained here, as well as a getting started guide.
Discussion Input
As illustrated by the above examples, it should be noted that the OAS files primarily focus on documenting API endpoints and their structure. Possible combinations of inputs and outputs, use cases, and other business-related aspects not directly related to the structure of the API endpoints are only minimally supported and should be added outside the OAS. Besides centralizing the API documentation on the developer portal, API store, or API catalog, the OpenAPI Specification provides functionality to include links to external docs in the Description part of the specification: https://spec.openapis.org/oas/v3.1.0#external-documentation-object.
Knowing the target audience helps in documenting the API. We distinguish at least two target audiences: the technical developer who works mainly with API description formalized by the OpenAPI Specification 3.0 (OAS 3) description standard. On the other hand, business analysts or other stakeholders are also interested in the business context and business-related aspects and solutions the APIs provide. In many cases (especially in generic designed public APIs), the syntactic interface description (the technical contract) must be supplemented with semantic specifications such as organizational information, business ownership, commercial aspects, non-functional requirements, support procedures, sequence diagrams, etc. This supplemental business-related piece of information and the OASs jointly form the API documentation (as we see it).
The API documentation can also document business drivers and supported business capabilities (if needed in domain terms). Amongst many advantages, it offers added value for technical developers to get acquainted with the business context, language, and requirements. It helps to answer the question: what high-value capability does the API offer the business, and what problem does it solve? These concerns are well-stated in the book: “The amount of documentation depends on the client provider relationship. Since APIs evolve, the documentation needs to be updated – which bears risk and costs”. Figure 9.4 (page 403) provides a great balanced template for an elaborate API description (another takeaway! 😊). However, it is not that easy to decide between minimal and elaborate API descriptions in our experience.
Regardless of whether you decide to keep an API private or release it to the general public, documentation is incredibly important and often neglected. Documenting software is never a popular task, but it is paramount in the API design-first approach moving toward an effective API design before writing a line of production code.
Recommended Reading
- Zalando: https://opensource.zalando.com/restful-api-guidelines/#102
- Zalando on API Descriptions: https://opensource.zalando.com/restful-api-guidelines/#meta-information
- Best Practices For Creating Useful API Documentation: https://nordicapis.com/best-practices-for-creating-useful-api-documentation/
- Hyrum’s law and API Design and the role of documentation: https://nordicapis.com/what-does-hyrums-law-mean-for-api-design/
- 5 Examples of Excellent API Documentation: https://nordicapis.com/5-examples-of-excellent-api-documentation/
- The 8 Best API Documentation Examples for 2023: https://blog.dreamfactory.com/8-api-documentation-examples/
- Certain behaviors cannot be expressed in an OAS (OpenAPI Specification) because they involve business logic: https://vng-realisatie.github.io/gemma-zaken/standaard/contactmomenten/ (in Dutch)
- Dutch governmental: https://geonovum.github.io/KP-APIs/API-strategie-algemeen/Architectuur/#specificatie-documentatie (in Dutch)
- Principles of Web API Design (Higginbotham 2021): mentions three other personas (besides developers) that can benefit from the documentation on a developer portal (page 251).
Read the complete pattern on api-patterns.org