API Versioning: Managing Change Without Breaking Clients

WHY IT EXISTS APIs must evolve to fix bugs, patch security holes, or add features. Some of these are "breaking changes" that alter data structures or endpoint behavior, which can crash client applications. API versioning solves this by allowing the API to support multiple, incompatible versions at once, preserving trust and stability for existing consumers.

THE MENTAL MODEL Think of API versions like different editions of a textbook. A professor can teach a course using the 2nd edition, and students with that book are fine. When the 3rd edition comes out with new chapters, new students can buy it and the professor can update the syllabus. But students with the 2nd edition aren't suddenly blocked. The publisher supports both for a time. API versioning lets clients specify which "edition" of the API they were built for.

HOW IT WORKS Versioning is a contract. The client requests a specific version, and the server routes the request to the corresponding code. There are four common strategies: first, URI Path versioning (api.com/v1/users), which is explicit and easy to route; second, Query Parameter versioning (api.com/users?version=1), which is simple but can clutter URLs; third, Custom Header versioning (Accept-Version: v1), which keeps URIs clean but is less visible; and fourth, Accept Header versioning (Accept: application/vnd.myapi.v1+json), the most RESTful but also most complex approach.

WHEN TO USE IT Use versioning for any API with consumers you don't control, such as public APIs, third-party integrations, or mobile clients that users may not update immediately. If you anticipate that your API's data structures, authentication, or core endpoints will change over time, you need versioning from day one.

WHEN NOT TO USE IT For purely internal APIs where the client and server are deployed together atomically, explicit versioning can be overkill. If you can guarantee all consumers update simultaneously with the API, you can skip it. Also, non-breaking changes, like adding a new optional field to a response, do not require a new version.

ONE CANONICAL EXAMPLE Imagine an API where you need to split a fullName field into firstName and lastName. This is a breaking change. Using URI versioning in Express.js, you would maintain two routers. The old router, mounted at /v1, handles requests to /v1/users and returns { "id": 1, "fullName": "Jane Doe" }. The new router, mounted at /v2, handles /v2/users and returns { "id": 1, "firstName": "Jane", "lastName": "Doe" }. This allows old clients to continue using v1 while new clients can adopt v2.