API Versioning Strategy: A Fill-In Policy for Your Team

Define this in writing, because engineers disagree on the edge cases. A change is breaking if a correct, existing client can stop working without modification. Treat these as breaking:

• Removing or renaming a field, endpoint, or enum value.
• Changing a field's type, format or units, including turning a number into a string.
• Making an optional request field required, or tightening validation.
• Changing the meaning of an existing value or an error code that clients branch on.
• Changing authentication or pagination behavior.

Treat these as safe: adding an optional request field, adding a response field, and adding a new endpoint. That rule only holds if you tell clients to ignore unknown fields, so state it in your docs.

Three placements are common, and each has a tradeoff:

• URL path (`/v2/orders`): obvious, easy to route at a gateway, easy to see in logs. Changing a version changes every URL, which some teams dislike.
• Request header or media type: keeps URLs stable and is more purist. It's harder to test in a browser and easy for clients to forget.
• Date-based version header: the client pins a date and gets the behavior from that day. Good for frequent small changes, but you need infrastructure to maintain each behavior snapshot.

For a small team with a public API, the URL path is the pragmatic default. Version the whole API at once rather than per endpoint, so customers have one number to track.

Fill in this outline and publish it:

1. Announcement: how far ahead you'll notify clients before removal, and through which channels (changelog, email to the account owner, response header).
2. Support window: how long the previous version keeps working after the new one is stable. Pick a period you can afford to run two versions.
3. Signals: add a Deprecation or Sunset header to old-version responses so clients can detect it in code.
4. Usage tracking: log which keys still call the old version so you can contact them directly before shutting it off.
5. Shutdown: a date, a final warning, and an agreed exception process for large customers.

Say your window is twelve months. That number matters less than sticking to it. A policy you break once teaches customers to ignore your announcements.

Keep one core implementation and translate at the edge. The new version's logic is the source of truth, and the old version is a thin adapter that reshapes requests and responses. A gateway such as Kong or Apigee can route by version, but the translation logic usually belongs in your code, where tests can reach it.

Avoid copying the whole codebase for v1. That path leads to two sets of bugs. Contract tests that run against both versions on every build catch the drift early.

Watch for these patterns:

• Shipping a breaking change under the same version because "nobody uses that field". Check logs before deciding, and even then, version it.
• Bumping the major version for every small change, so nobody knows what the number means.
• Deprecating with no replacement documented. Every deprecation needs a migration note that shows old call, new call.
• No changelog. A public, dated list of changes is the cheapest way to build trust.

A useful habit is a standard changelog entry: the date, the version affected, what changed, whether it's breaking, and the exact old and new call. Post it where developers already look, and email account owners for anything breaking. Clients forgive change they were told about early and plainly.

Link your versioning rules to how you structure logs, since version and client ID in every request log line make the usage tracking step possible.