API versioning without multiplying endpoints

Versioning is often introduced as a URL convention before anyone has defined what counts as a breaking change. The result can be several endpoints that differ only slightly, each needing fixes and documentation. Start with a compatibility policy instead.

Prefer additive evolution

Adding an optional response field is usually compatible if clients ignore fields they do not recognize. Adding a new endpoint can also be safe. More risky changes include renaming a field, changing its meaning or units, tightening accepted input, changing nullability, and changing ordering or pagination behavior that clients rely on.

Even an additive change can break a client with a strict decoder. Publish the expected behavior in the contract and test the clients that matter. For public APIs, use a schema format such as OpenAPI and validate generated examples in CI.

Separate wire compatibility from domain change

A stable external representation does not require the internal database model to remain frozen. Map between the public contract and internal types at the service boundary. This gives the application room to reorganize without exposing implementation details in every API response.

When a version is warranted

Use a new major version when clients cannot safely interpret the old and new behavior through an additive extension or a migration window. Document the differences, provide a transition period, and keep the old version only as long as it is supported and monitored.

Make retirement observable

• Record which client versions call each deprecated behavior.
• Publish the deprecation date and replacement path.
• Use consumer contract tests for high-value integrations.
• Remove the old behavior only after usage has moved or an agreed support window ends.

Versioning is not a substitute for communication. A small, explicit compatibility promise—and instrumentation to see whether clients still depend on a behavior—keeps both the API and the engineering workload manageable.