Skip to content
Tutorials Center
My learning

Topics

Lesson 32 of 39 ยท Pagination, Caching and Versioning

API Versioning and Evolution

Change an API without breaking clients: breaking versus safe changes, URL, header and date versioning, the Deprecation and Sunset headers, and a migration plan.

Once other people's code depends on your API, you no longer control when your changes land. A mobile app that cannot be updated for months, a partner's nightly job, an open-source client: all of them break if you rename a field. API versioning is the discipline of changing an API while keeping existing clients working, and of retiring old behavior in an orderly way.

The best versioning strategy is to avoid needing a new version for as long as possible. This lesson starts with which changes are safe, then compares versioning styles, and ends with the deprecation process that gives clients time to move.

Breaking or not?

Safe Add a field. Add an endpoint.
Careful Add a required input.
Breaking Rename, remove or retype a field.

Clients must ignore fields they do not know.

1 / 2

Breaking and non-breaking changes

A change is breaking if a correct, existing client stops working.

Change Breaking?
Add a new endpoint No
Add an optional request field or query parameter No
Add a field to a response No, if clients ignore unknown fields
Add a new value to an enum the client switches on Possibly yes
Remove or rename a response field Yes
Change a field's type ("id": 7 to "id": "7") Yes
Make an optional request field required Yes
Tighten validation (shorter max length) Yes
Change status codes or the error format Yes
Change default sorting or page size Often yes
Change the meaning of a field Yes (the worst kind: it fails silently)

The rule for clients is the robustness principle: ignore what you do not understand. The rule for servers is: only add, never remove or change, within a version.

Node.js Detect breaking changes automatically

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Tools such as OpenAPI diff checkers and contract tests (Contract Testing and Mocking) run this kind of comparison in CI so a breaking change cannot ship by accident.

Versioning styles

URL path

HTTP
GET /v1/articles/7
GET /v2/articles/7

The most popular style: obvious, easy to route, easy to test in a browser, easy to cache. The downside is that the version appears in every URL, and purists argue the resource itself did not change. Version the whole API (/v1), not individual resources.

Header or media type

HTTP
GET /articles/7
Accept: application/vnd.example.v2+json

or a custom header such as X-API-Version: 2. URLs stay stable and cache-friendly (add Vary: Accept), but the version is hidden from logs, links and casual testing, and clients can forget to send it.

Date-based versions

Some providers pin each client to the API date it first used and let it opt in to newer ones: API-Version: 2026-05-01. Changes are small and frequent, and each client upgrades on its own schedule. It needs good tooling on the server side to keep many behaviors alive.

Query parameter

GET /articles/7?version=2 works but easily falls out of caching rules and makes optional behavior look mandatory. Usually not recommended.

Style Visibility Caching Effort
URL path High Simple Low
Header or media type Low Needs Vary Medium
Date Medium Needs Vary High

Pick one style, document it, and use it everywhere.

Node.js Serve two versions side by side

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Notice the single internal model and two presenters. Keep the version-specific code at the edge (routing and serialization), and share the business logic, or you will maintain two copies of your application.

Deprecation and sunset

Retiring a version is a process, not an event:

  1. Announce the deprecation in the docs, changelog and email to key owners, and state the removal date.
  2. Signal in responses: the Deprecation header (RFC 9745) says the endpoint is deprecated, Sunset (RFC 8594) gives the date it will stop working, and Link: <...>; rel="successor-version" points to the replacement.
  3. Measure usage per version and per API key, so you know who still calls the old one and can contact them.
  4. Give enough time, for public APIs often 6 to 12 months or more.
  5. Brown out shortly before shutdown (brief planned failures) so forgotten clients wake up.
  6. Remove with 410 Gone and a message that points to the migration guide.

Evolve without a new version

Most changes can be made inside one version:

  • Add fields and endpoints instead of changing them.
  • Keep the old field while adding the new one (name plus firstName/lastName), mark the old one deprecated, remove it in the next major version.
  • Accept both old and new input formats during a transition.
  • Use feature flags or opt-in parameters for new behavior.
  • Treat error codes and response formats as part of the contract.

Use semantic ideas: a major version changes only for breaking changes, and everything else ships continuously. A changelog with dates keeps clients informed.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which change is NOT breaking for existing clients?

    Existing clients that ignore unknown fields keep working. The other changes alter what they send or parse.
  2. 2. What is an advantage of URL path versioning?

    /v1 and /v2 are explicit, easy to debug and work naturally with caches.
  3. 3. Which header announces the date a version stops working?

    Sunset (RFC 8594) gives the retirement date. Deprecation marks the endpoint as deprecated.
  4. 4. Where should version-specific code live?

    Separate representations from business logic so you maintain one core and thin version layers.
  5. 5. Which response is suitable after a version has been removed?

    410 says the resource is permanently gone, and the body can explain where to go next.

Summary

  • Adding is safe; removing, renaming, retyping or tightening is breaking. Clients should ignore unknown fields.
  • Prefer evolving within a version; version the whole API only for real breaking changes.
  • URL path versions are the simplest; header and date versions keep URLs clean but need Vary and more tooling.
  • Keep one business core with thin per-version presenters.
  • Deprecate with documentation, Deprecation and Sunset headers, usage metrics and enough time, then answer 410 Gone.

Next: Documenting APIs with OpenAPI