
An interface between applications can become a dependency for work far beyond its original project. A small service might expose a field named status, initially containing only the values draft and published. A later release introduces review as a new value. The service still returns a field with the same name and type, but one consumer treats every non-draft record as public. Another refuses any unrecognized status. The revised response may be syntactically valid while both consumers interpret it incorrectly. Versioning begins with recognizing these behavioral agreements, not simply numbering releases.
Find the promises that callers actually rely on
An interface contract includes more than field names and a list of types. It can describe allowed values, units of measure, the meaning of absence, ordering, failure outcomes and any side effects of the operation. A service that returns a price as an integer must make its unit clear. A list operation that returns the ten most recent records needs to state how recency is determined if callers depend on that ordering. A publishing operation must explain whether acknowledgement means the record is already public or that publication was scheduled.
Inspect representative consumers and existing examples before describing the contract. Some behavior may have become an expectation without being deliberately documented. That is a problem to resolve, not automatic evidence that every incidental characteristic must be supported forever. A consumer that reads a private diagnostic field may be relying on something that was never intended as a stable interface. A consumer that distinguishes published records from drafts is likely to rely on the field's meaning. Establish the commitments the interface should make and state the scope of any guarantees clearly.
Assess additive and incompatible changes
Adding a new optional field is often less disruptive than removing an existing one. A consumer that reads only the fields it needs may continue unchanged. But a consumer with a closed validation schema may reject an otherwise valid response containing an unexpected field. Similarly, adding a new status is not always compatible merely because the field remains a string. Determine whether callers are expected to tolerate unrecognized values or whether the response describes a closed set. The answer depends on the contract and the real consumer environment.
Changes in meaning are particularly easy to overlook. Imagine a scheduled publication service whose published status previously meant that the generated public page was available. An internal optimization now uses that status as soon as generation has been requested. Callers may continue to accept the response but display links that do not yet work. Keeping the field name conceals a meaningful behavioral change. A safer design can preserve the existing meaning and add a separate scheduling status, or introduce revised semantics through a deliberately changed contract with a migration path.
Expose a version boundary where one is needed
Related reading: Designing modules around stable boundaries.
How version information appears depends on the interface. A published library may use versioned release artifacts. A network service may expose different endpoint paths or recognize an explicit interface version requested by the consumer. An exchanged document may carry its schema version. Different mechanisms can be suitable, but all should make it possible to determine what contract applies. Do not make callers guess whether an apparently familiar field has changed since an unrelated deployment. A version identifier has value only when its associated behavior is defined.
There is also a cost to supporting several versions. Each must receive appropriate verification, and maintainers need to know which versions can still receive changes. If the old and new behavior differ only at one output boundary, the implementation may share the same underlying rules while converting the result to the requested representation. That can reduce unnecessary duplication. However, forcing every version into one tangled collection of conditional branches can also obscure the semantics. Keep the distinction between the current internal model and the externally supported representations understandable.
Create a migration example before publishing the revision

Return to the application that adds the review status. Write down how the old consumer currently classifies draft and published records. Then describe what should happen after the revision: perhaps draft and review both remain unavailable to a public listing, while published remains eligible. Show a response containing a review record and demonstrate the desired decision. This gives consumers a precise example against which to update their handling. If the old version continues to serve two statuses, define how the service maps the new internal review state into that old representation.
A migration note ought to identify more than the names of added or removed fields. Explain why the behavior changes, which assumptions need attention and what outcome should remain stable. If a record that previously had a numeric price can now omit its price, consumers may need a dedicated absent-data presentation rather than a default zero. If an operation's failure response changes, consumers need to know how to distinguish a condition that can be corrected from a temporary interruption. Use small examples of each relevant difference. A useful note saves callers from reconstructing the change by trial and error.
Test from both sides of the interface
A provider's internal tests can confirm that its new status rule produces the expected records. They cannot establish on their own that existing callers accept those records. A consumer check can provide known responses for each supported contract and verify the decisions that result. Include ordinary data, optional values, recognizable error outcomes and any newly introduced state. If a consumer must support both versions temporarily, exercise both explicitly. A shared set of interface examples can be particularly helpful because it keeps the provider and consumers working from the same descriptions.
For services with several callers, keep a manageable inventory of known consumers and the contract versions they use. This does not need to reveal every internal detail of the consuming application. It helps maintainers identify who needs to evaluate a revised interface and when older behavior is still necessary. Where the interface is public and not every consumer is known, the supported compatibility policy and published migration window become especially important. The provider should not assume that a lack of visible errors proves all consumers have migrated successfully.
Define retirement instead of leaving every version indefinitely
A supported old contract can give consumers time to adapt, but it should have a clear lifecycle. Explain which older versions continue to be maintained, what kinds of changes they receive and when retirement may occur. Different projects will have different practical constraints: a private system with two coordinated consumers can migrate quickly, while an interface used by independently maintained applications may need a longer transition. The important issue is to make the decision explicit rather than leave maintainers guessing whether an old representation is safe to remove.
Before retiring one version, check the evidence available to the provider. Known callers should have completed their updates and undergone relevant verification. Any required communication should have occurred according to the project's policy. If representative consumer checks still fail on the new contract, investigate those problems before removing the fallback. An older version may also contain dependencies that deserve deliberate cleanup once it is no longer necessary. Removing its route alone while leaving confusing unused implementations can make a later interface change more difficult.
Preserve what the version number is meant to communicate
A system may change its internal storage, its logging or its implementation of a calculation without changing an external agreement. These changes need not create new external contract versions merely to advertise engineering activity. Conversely, a small change to the accepted values of one field can be important enough to require a revision. Use the boundary to communicate actual compatibility, not the volume of work. A reliable versioning approach helps consumers plan upgrades, gives maintainers a way to evolve internal behavior and reduces the chance that a successful deployment quietly changes the interpretation of familiar information.
Explore the implementation area: Backend development.


