API Honesty Contracts: Why Your API Should Say "I Don't Know"
An API that always returns a value, even when it has nothing to say, forces consumers to build guesses on top of guesses. API honesty contracts change that.
Most API contracts guarantee a response shape. GTL API contracts go further: they guarantee that the response accurately represents the state of the system's knowledge at the time of the call. The shape guarantees structure. The honesty contract guarantees meaning.
What an Honesty Contract Covers
A GTL honesty contract specifies: what state values are valid for this endpoint, what each state means in the context of this specific data, what reasons are valid for partial and empty states, and how the timestamp should be interpreted. The contract is part of the API documentation — not as a description of the happy path, but as a specification of all valid data states the consumer may receive.
The Consumer's Obligation Under the Contract
An API honesty contract is bilateral. The producer commits to returning accurate states. The consumer commits to handling all three states explicitly — not just the complete state. A consumer that treats partial as complete, or empty as an error, is violating the contract. GTL-aware client libraries enforce this by making state a required field that must be checked before accessing the data field.
◆GTL client pattern: `const { state, data, reason } = await getTemporalAuthority(auditId); if (state === "empty") { showBaselineMessage(reason); return; } if (state === "partial") { renderWithCaveat(data, reason); return; } render(data);`
Why This Builds More Durable Integrations
Integrations built against API honesty contracts are more durable than those built against shape-only contracts. When a sub-computation fails and the response transitions from complete to partial, the consumer handles it correctly, because the contract always included that possibility. There are no surprise null reference errors, no silent score degradations, no wrong cached values. The consumer was built to handle what the producer can honestly deliver.
GTL Systems — Part 6 of 10