An API is a promise to the team on the other side.

In this analysis

The breaking change that passed the test

A team deploys an API update that preserves every endpoint and returns valid JSON. A client still breaks because a field that used to be absent now appears as null, or a response arrives in a different order that the client had quietly depended on. The server’s tests pass because they check its own expectations. The consumer has been relying on a different contract.

This hypothetical incident captures the social dimension of an API: it is an agreement between independently changing systems. Google’s AIP-180 discusses backward compatibility as a concern that extends beyond simply retaining a method name. ⁸ A stable contract must describe behavior that consumers can rely on, while making clear which implementation details remain outside that promise.

A protocol gives behavior a vocabulary

RFC 9110 defines HTTP semantics, including methods, status codes, and properties such as safety and idempotency. RFC 9111 specifies HTTP caching behavior. ¹³ These standards give clients and intermediaries a shared basis for interpreting requests, but application-specific behavior still needs documentation and testing.

For example, a read request should not be designed to trigger an unintended business mutation. A cacheable response must not accidentally expose a user-specific result to another user. Our recommendation is to review the interaction among methods, authorization, cache controls, and representation variance. A system can be syntactically valid HTTP while making poor choices about how the protocol’s semantics map to the application.

A schema is a useful limit on ambiguity

OpenAPI 3.1.1 describes a machine-readable format for HTTP API interfaces. RFC 8259 defines JSON’s data interchange format. ⁴⁵ Neither independently decides the business meaning of a field. “Amount” still needs a currency, unit, rounding policy, and relationship to any tax or refund rules.

We suggest describing boundary cases alongside the schema: absent versus null, empty versus unknown, timestamp precision, pagination, and permitted enumerated values. Generate documentation or clients where useful, but keep contract tests that exercise actual behavior. A specification that drifts away from the running service can become a more efficient way to distribute incorrect assumptions.

Errors are part of the product

RFC 9457 standardizes a format for problem details in HTTP responses. ² Its value is interoperability around structured failure information, rather than a promise that every error can be repaired automatically. A useful application still needs to distinguish invalid input, denied access, temporary unavailability, and conflicts with current state.

Consider a hypothetical document-import API. A client should be able to identify whether the file type is unsupported, the user lacks permission, or processing has not yet completed. Avoid returning a successful status with an opaque failure message buried in an unrelated field. Also avoid leaking sensitive internal details in the name of helpful debugging. The contract should support an appropriate next action without revealing information the caller is not authorized to see.

Retrying requires a definition of sameness

Stripe’s idempotent-request documentation describes using a key to recognize retries of a request and return the corresponding result under its documented behavior. ⁹ It is an implementation example, not a universal rule that every API automatically follows.

For a payment or job-creation endpoint, decide what identifies the same intended operation, how long that identity is retained, and what happens when a repeated key arrives with different parameters. A network timeout can leave the caller uncertain whether the original action completed. The API should help resolve that uncertainty rather than forcing the client to guess between duplication and abandonment. Test the failure after commitment, not only the easy case where the server never received the request.

Authentication does not settle authorization

RFC 9700 documents security best practices for OAuth 2.0. OWASP’s API Security Top 10 highlights risks including object-level authorization failures and unrestricted resource consumption. ⁶⁷ These address related but different layers: establishing and conveying authority, then enforcing what a particular request may access or do.

A valid token does not by itself mean that its holder may read every document identifier accepted by an endpoint. Check access to the requested object and operation at the server. Define resource limits that reflect the cost of the action, especially for endpoints that start expensive AI or data-processing work. Security behavior is part of the contract, even when clients would prefer an unrestricted interface.

Events carry contracts too

AsyncAPI 3.0 describes interfaces for message-driven systems, including channels, operations, and messages. ¹⁰ Moving a workflow from synchronous requests to events does not eliminate compatibility questions. Consumers still depend on payload meaning, delivery expectations, and how changes are communicated.

For a document-processing event, clarify whether “completed” means extraction finished, validation passed, or the result became available to the user. Explain how consumers identify duplicates and how they recover when events arrive late or out of order. These operational semantics may matter more than the field names. An event whose meaning changes silently can corrupt downstream state without causing an obvious request failure.

A timeout does not tell you whether work happened

There are at least three relevant moments in a mutating request: the server receives it, the business change commits, and the client receives confirmation. A connection can fail between the second and third moments. From the client’s perspective, the request failed; from the server’s perspective, the action already happened.

A safe retry mechanism must associate repeated attempts with the same intended operation. Stripe’s documented idempotency behavior is one concrete example. ⁹ Test what happens when the first attempt commits but its response is lost, when a retry uses altered parameters, and when two attempts arrive concurrently. Also document the retention window for deduplication state. Calling an endpoint “idempotent” without defining these conditions leaves the consumer to infer the very behavior it needs during an incident.

Treat evolution as a negotiated process

We recommend maintaining representative consumer tests, a documented deprecation process, and an inventory of important integrations. Review changes from the consumer’s perspective, including changes that seem additive. A new enum value can be harmless to a tolerant client and fatal to one that assumes the old list is exhaustive.

An API’s quality is therefore measured partly by how safely other teams can depend on it. Standards provide shared semantics and security guidance; specifications make the intended interface inspectable; testing reveals discrepancies between intent and behavior. The remaining work is organizational: communicate changes, preserve supported behavior, and provide a migration path. A dependable API lets the team on the other side plan its own work without continually rediscovering your implementation.

The practical takeaway

Review an API change as a change to another team’s workflow, not only to your code.

Sources & methodology

This editorial synthesizes primary research, technical standards, and original engineering documentation. It is not an original experimental study or a systematic literature review. Research findings apply to the conditions studied; product recommendations are our interpretation. Figures explain concepts and do not present experimental measurements.

Sources checked on 31 October 2026. Publication dates and preprint versions may differ; the linked record identifies the referenced work. To suggest a correction, email contact@data-sorcerers.com.

The breaking change that passed the test

A protocol gives behavior a vocabulary

A schema is a useful limit on ambiguity

Errors are part of the product

Retrying requires a definition of sameness

Authentication does not settle authorization

Events carry contracts too

A timeout does not tell you whether work happened

Treat evolution as a negotiated process

Sources & methodology

Continue reading

A smaller architecture can leave more room to grow.

Uptime is not the same as a working user journey.

A fast interface is only useful if people can operate it.

Have a high-value challenge?Let's solve it together.

Have a high-value challenge?
Let's solve it together.