Documenting Interfaces: OpenAPI Instead of Tribal Knowledge

The OpenAPI Specification defines how an HTTP interface is described in a machine-readable document. With it, a consumer should be able to understand the remote service and interact with it using a minimal amount of implementation logic (OpenAPI Specification). The current version is 3.2.1, dated September 10, 2026 (OpenAPI Specification). It belongs to the 3.2 line, whose first release, 3.2.0, dates from September 19, 2025 (OpenAPI Specification). Patch versions such as 3.2.1 fix errors in the document or clarify wording, but do not change the feature set of the line (OpenAPI Specification).

Technically, an OpenAPI description is a JSON object that can be written either as JSON or as YAML (OpenAPI Specification). Data structures are described by the Schema Object, which by default is a superset of JSON Schema Draft 2020-12 (OpenAPI Specification). For interfaces where the ERP or a payment service sends messages on its own, there is the webhooks field: it describes incoming requests that the API consumer may choose to implement (OpenAPI Specification). A description therefore covers both directions of a data flow, not only the endpoints that the shop calls itself. When push pays off and when polling does is compared in the article on webhooks and polling.

The OpenAPI Initiative names one limitation itself: OpenAPI is not capable of describing every possible HTTP API (OpenAPI Initiative). Teams that write code first and describe it later therefore sometimes run into constructs that can only be represented in a twisted way. The Initiative recommends writing the description first and letting the code follow (OpenAPI Initiative). For a new integration, that is the easier path. For existing interfaces it no longer works; there, the approach shown in the section on describing interfaces after the fact helps.

The specification does not require listing every conceivable status code, because not all of them are known in advance. It does expect the documentation to cover a successful response and any known errors (OpenAPI Specification). For an order interface, these are usually few cases, but consequential ones. What matters is that the description names not only the code, but also the reaction the client should derive from it. Otherwise the middleware retries an order that was booked long ago, or gives up on a case that would have gone through after a minute of waiting.

There is a standard for the format of error responses: RFC 9457 defines “problem details” that let HTTP APIs describe errors in machine-readable form without inventing their own error formats (RFC 9457). A response then carries the media type application/problem+json with members such as type, title, status and detail. In the OpenAPI description, this schema is defined once under components and attached to every error response. With 429, the server can state in the Retry-After header how long the client should wait (RFC 6585). How retries, queues and notifications work together is covered in the article on error handling in interfaces; throttling large imports is the topic of the article on cloud ERP API limits.

A description that runs alongside the code goes stale. The OpenAPI Initiative therefore recommends running validation tools that check the code against the description as part of continuous integration; deviations are then detected promptly and the description can be changed with peace of mind (OpenAPI Initiative). Documentation thus turns into a contract between shop, middleware and ERP: what is written there applies, and whatever deviates from it is a defect, on whichever side.

Contract tests check whether an API still fulfills its documented contract. The article on API versioning describes them as protection against unnoticed breaking changes. Where they can run without loading the real ERP on every commit is shown in the article on test environments for ERP interfaces. For project acceptance, the description has another advantage: it makes the acceptance criterion verifiable. Instead of “the interface works”, the record states that all responses from the test runs match the schema and that every documented error response was triggered at least once.

Switching service providers is the moment that shows whether an interface is documented. In its IT-Grundschutz module on using outsourcing, Germany's Federal Office for Information Security requires under OPS.2.3.A7 that rules be set for planned and unplanned terminations, including how information and data are returned (BSI IT-Grundschutz). For software-related services, the same module recommends escrow agreements under OPS.2.3.A21 that also define how often the source code is deposited and documented (BSI IT-Grundschutz). If you outsource development and operation of an interface, you can adopt these ideas directly: the handover package is not packed on the last day but maintained continuously.

Legally, it pays to look at usage rights. If an employee creates a computer program in the performance of their duties, Section 69b of the German Copyright Act gives the employer the exclusive right to exercise all economic rights, unless otherwise agreed (German Copyright Act). For an external service provider, the provision makes no such assignment. Which rights to code, description, test suite and runbook transfer should therefore be set out in the contract before the first endpoint is built. This is an organizational recommendation and not legal advice.

Fixed deadlines in the coming year argue against postponing the description to “someday”. For supplies from January 1, 2027, the transition rule that still allows invoices to other businesses in Germany on paper or in other electronic formats instead of e-invoices ends for businesses whose total turnover in the previous year exceeded EUR 800,000; smaller businesses can use it until the end of 2027, and EDI procedures have a separate rule (German VAT Act). Anyone reconnecting invoice data from shop and ERP for this is changing interfaces. The article on the 2027 e-invoicing mandate describes the data paths; a description that exists beforehand makes this change verifiable.

The retail calendar also determines the right timing. During the November order peak, work on interfaces is better put on hold; the article on the Black Week order peak recommends a change freeze. The weeks after that are well suited to inventory and description, so that the documentation is in place before the changes of the new year begin. In the budget, it belongs on its own line next to development and testing; how the other items of an integration add up is covered in the article on the cost of an ERP integration.