API-First Design: Make the Golden Thread Testable

An API description and a protected record history solve different problems. OpenAPI describes how to call an HTTP service, while NIST's log-management guidance addresses the preservation and protection of event records. For field systems, we recommend designing both before treating a successful upload as evidence of a complete history.

API-first design should make those responsibilities explicit before teams build the screens and integrations around them. Start with the work the interface must support, including what a caller can rely on after a response. Do not treat an endpoint catalogue as proof that the record behind it is accurate or complete.

Define the operation, not only the fields

In chapter 5 of Patterns for API Design, Olaf Zimmermann and his co-authors explain contracts through the conditions callers must satisfy, the rules that remain true and the outcome an operation promises. That is a useful starting point for smart logging because it asks what a save actually means.

Consider a hypothetical inspection record awaiting approval. Specify whether a submission creates a draft, replaces a previous version or requests a review. Name who may perform each operation, and decide whether an approved record can be edited or needs a separate correction. These are proposed design decisions, not capabilities supplied by an API format.

Write an example for an accepted submission and one for a refused submission before implementing either. Include the record identifier and the state the caller should display afterwards. We recommend reviewing these examples with the people responsible for the operational record, rather than leaving their meaning to the mobile developer.

Use a machine-readable contract without confusing it with enforcement

OpenAPI 3.1.0 provides a language-independent description of an HTTP API, including operations, request bodies, responses and security requirements. The specification also describes documentation generation, client and server generation, and testing as uses for that description. Those are ways to work from the contract, not evidence that a deployed service follows it.

For the inspection example, describe required fields and permitted values alongside the responses for each operation. Keep explanations of business meaning beside the schema, particularly where an empty value means something different from an unanswered question. Review generated documentation as a caller would, with a concrete record rather than a list of field names.

Then test the implementation against the agreed examples. We would include a request that is structurally valid but attempts an unauthorised state change. Treat its refusal as an acceptance criterion, not as something proved by the presence of a security declaration.

Specify what happens after a lost response

A field workflow needs a retry decision as well as a successful submission path. HTTP's idempotence rules distinguish operations whose repeated requests have the same intended server effect from operations that do not offer that property. They do not require the repeated response to be identical. The standard warns against automatically retrying a non-idempotent request unless the client knows its semantics permit it or knows the first request was not applied.

For our hypothetical submission, choose and document how the caller resolves an unknown outcome after losing contact. One possible application design is a caller-supplied submission identifier that the server recognises on a repeat attempt. If the team chooses that design, specify its retention period and what happens when the identifier is reused with different content. Do not describe that application behaviour as something HTTP supplies automatically.

HTTP's If-Match condition can help prevent accidental overwrites by making an update depend on the current representation's entity tag. We recommend testing that a stale edit is refused, then defining who compares the versions and decides what to retain. A failed precondition is a signal for that workflow, not a rule for resolving the disagreement.

Make failure information usable

RFC 9457 defines a machine-readable problem-details format for HTTP errors. It offers a shared structure instead of requiring every API to invent its own error representation.

Use that structure to describe errors the inspection client must handle, with a documented problem type and an explanation appropriate to the caller. For a validation failure, define which details help the user correct the submission. For a permission failure, decide what the client should say without exposing protected information. These are application choices to review and test, rather than behaviour guaranteed by adopting the format.

Keep the evidence history as a separate responsibility

NIST SP 800-92 recommends defining logging requirements, preserving original logs and protecting their confidentiality, integrity and availability. Its operational guidance also includes synchronising logging hosts to a common time source. That work belongs beside the API contract, rather than being assumed from it.

For the example workflow, decide which accepted changes and refused actions need an event record. Distinguish the time an observation was made from the time the service received it. Specify how a correction refers to the earlier record, who can inspect that history and how long the evidence must remain available. Choose those rules for the actual use case rather than copying a retention period from another system.

Before approving the design, walk one inspection through submission, a lost response, a conflicting edit and a later correction. Require the caller's final state and the retained history to match the agreed examples. That gives the team a concrete acceptance test for data continuity without promising that API-first design guarantees it.

Update, October 2026

The same contract deserves a place in the context given to a coding agent. Our engineering article on grounding packs describes supplying a code-derived view of the system and checking claims against the code. For API work, we recommend including the contract, the implementation locations and the recovery examples before the agent changes an endpoint.

Sources

• OpenAPI Initiative, "OpenAPI Specification v3.1.0", 15 February 2021.
• IETF, "HTTP Semantics", RFC 9110, 6 June 2022.
• IETF, "Problem Details for HTTP APIs", RFC 9457, 31 July 2023.
• NIST, "Guide to Computer Security Log Management", SP 800-92, September 2006. The publisher does not specify a day.
• Olaf Zimmermann and co-authors, "Patterns for API Design", first edition, chapter 5, 5 December 2022. The edition carries a 2023 copyright date.
• Dendro Logic, "What the Agent Does Not Know to Look For", 6 September 2026. Cited only in the dated update.