Advanced Concepts: Pagination, Filtering, Versioning, and Rate LimitingLesson 5.3

API Versioning Strategies

API versioning, URL versioning, header versioning, backward compatibility, versioning strategy, deprecation policy, migration guide

API Versioning Strategies

APIs change over time. New features are added, old ones are improved, and sometimes breaking changes are unavoidable. API versioning allows you to introduce breaking changes without breaking existing clients. Choosing the right strategy at the start of a project prevents painful migrations later.

DiagramAPI Versioning Approaches Compared

IMAGE PROMPT (replace this block with your generated image):

Flat three-column comparison card on white background. Title: API Versioning Strategies. Three equal-width cards side by side. Card 1: URL Path Versioning (most common). Header fill: solid #3A5EFF, white text. Body: code example GET /api/v1/users and GET /api/v2/users. Pros list (green checks): Explicit and visible, Easy to test in browser, Used by Stripe and GitHub. Cons list (red X): Not theoretically pure REST. Card 2: Header Versioning. Header fill: medium blue tint #b3c5ff, dark text. Body: code example — request header API-Version: 2. Pros: Clean URLs. Cons: Harder to test, Less discoverable. Card 3: Accept Header (Content Negotiation). Header fill: light #3A5EFF #e8ecff, dark text. Body: Accept: application/vnd.myapi.v2+json. Pros: Follows HTTP spec. Cons: Complex, Rarely used in practice. Bottom of each card: a Recommended For note — Card 1: Public APIs and most use cases, Card 2: Internal APIs, Card 3: Academic/formal APIs. White outer background, rounded card corners.

URL Path Versioning

The most common and explicit approach: include the version in the URL path.

app.use('/api/v1/users', v1UserRouter);
app.use('/api/v2/users', v2UserRouter);

URL versioning is highly visible, easy to test in a browser, and simple to route in load balancers and API gateways. GitHub API, Stripe API, and Twitter API all use URL versioning.

What Constitutes a Breaking Change

Breaking changes require a new version: removing a field from a response, renaming a field, changing a field's data type, changing a URL path, making a previously optional parameter required, and changing authentication mechanisms. Non-breaking changes do not require a version bump: adding new optional fields, adding new endpoints, and relaxing validation constraints.

Deprecation Policy

When deprecating an old API version: announce the deprecation date publicly, send a Deprecation response header on all requests to the old version, maintain the deprecated version for at least 6-12 months, send email notifications to all registered API users, and provide a migration guide documenting every change between versions.