Skip to main content
REST API Design Tutorial
CHAPTER 13 Beginner

API Versioning Strategies

Updated: May 14, 2026
30 min read

# CHAPTER 13

API Versioning Strategies

1. Introduction

Once an API is published to the internet and consumed by external clients (mobile apps, partner companies, automated scripts), it becomes a binding contract. If you change the name of a JSON key from firstName to firstname without warning, every single application relying on your API will instantly crash. Because modifying live APIs is inherently dangerous, architects use API Versioning. In this chapter, we will explore how to manage the lifecycle of an API, introduce breaking vs. non-breaking changes, and examine the three primary strategies for routing traffic to different versions of your code.

2. Learning Objectives

By the end of this chapter, you will be able to:
  • Define the API Contract and understand the consequences of breaking it.
  • Distinguish between Breaking Changes and Non-Breaking Changes.
  • Implement URL Routing Versioning (The industry standard).
  • Understand Header Versioning and Query Parameter Versioning.
  • Architect an API deprecation lifecycle.

3. Beginner-Friendly Explanation

Imagine a TV Remote Control.
  • Version 1: The remote has a "Volume Up" button on the left, and a "Channel Up" button on the right. You memorize this layout.
  • Non-Breaking Change: The manufacturer adds a new "Netflix" button at the bottom. Your memorized buttons still work perfectly. You don't care about the new button.
  • Breaking Change: The manufacturer secretly swaps the location of the Volume and Channel buttons. You try to turn up the volume, and you accidentally change the channel. The system is broken.

If you must swap the buttons (a breaking change), you cannot magically alter the remotes already sitting in people's houses. You must release a brand new remote (Version 2) and let people upgrade when they are ready.

4. The API Contract

When you publish an API, you promise the Client: "If you send me X, I will return Y in this exact structure."

Non-Breaking Changes (Safe):

  • Adding a brand new endpoint.
  • Adding a new field to an existing JSON response (Clients simply ignore fields they don't recognize).

Breaking Changes (Dangerous):

  • Deleting an endpoint.
  • Changing a JSON key (e.g., id to userId).
  • Changing the data type of a field (e.g., an age Integer becomes a dateof_birth String).
  • Adding a new *required* field to a POST request (Old clients won't send it, and their requests will fail).

If you must make a Breaking Change, you MUST create a new Version of the API.

5. Strategy 1: URL Versioning (Industry Standard)

The simplest, most transparent, and most popular way to version an API is to include the version number directly in the URL path.
  • GET https://api.stripe.com/v1/customers
  • GET https://api.stripe.com/v2/customers

Implementation (Express.js): You map completely different Router files to different root paths.

javascript
123456 
const routerV1 = require('./routes/v1/users');
const routerV2 = require('./routes/v2/users');

// Old apps use v1. New apps use v2. Both run simultaneously!
app.use('/api/v1/users', routerV1);
app.use('/api/v2/users', routerV2);

6. Strategy 2: Header Versioning (Content Negotiation)

Some purists argue that the URL should only represent the resource, and versioning the URL violates strict REST principles. Instead, they use HTTP Headers to request a specific version.
  • GET https://api.example.com/customers
  • Header: Accept: application/vnd.example.v2+json

*Pros:* Keeps URLs clean. *Cons:* Extremely difficult for beginners to test in browsers. Harder to route backend traffic cleanly compared to URL routing.

7. Strategy 3: Query Parameter Versioning

The client requests the version in the URL string.
  • GET https://api.example.com/customers?version=2

*Pros:* Very easy to implement. *Cons:* Looks messy. Can interfere with pagination and filtering logic.

8. Backend Workflow: Managing the Codebase

How do you maintain a v1 and v2 codebase without duplicating 10,000 lines of code? You do not duplicate the database models or core business logic. You only duplicate the Controllers (the files that shape the JSON response). Both v1/UserController and v2/UserController query the exact same database. But v1 formats the output as { id: 1 } to satisfy old clients, while v2 formats it as { userId: 1 } for new clients.

9. The API Deprecation Lifecycle

You cannot support v1 forever. It costs money and server resources.
  1. 1. Announce: Publish a timeline (e.g., "v1 will be deprecated in 12 months").
  1. 2. Warn: Add HTTP Headers to v1 responses: Warning: 299 - This API version is deprecated.
  1. 3. Brownouts: Intentionally turn off v1 for 1 hour a day to force lazy clients to notice the errors and upgrade.
  1. 4. Sunset: Turn off v1 permanently. Requests to v1 now return 410 Gone.

10. Best Practices

  • Use Major Versions Only: Do not use /v1.1/ or /v1.2/ in your URLs. Minor updates should always be Non-Breaking changes, meaning they can be quietly rolled into the existing /v1/ endpoint. Only increment to /v2/ when making massive, structural, Breaking Changes.

11. Common Mistakes

  • Versioning Too Late: If you launch your API as /api/users and a year later realize you need a v2, you are stuck. You have to create /api/v2/users, leaving your original endpoint structurally inconsistent. ALWAYS include /v1/ in your base URL on day one, even if you never think you'll need a v2.

12. Exercises

  1. 1. Define a "Breaking Change" in REST API design. Give two specific examples of modifications that would crash a client application.

13. Coding Challenges

  • Challenge: You are the Lead Architect. The Marketing team wants to change the JSON key usermobile to phonenumber in the /api/v1/profile endpoint because it looks cleaner. The Mobile App team is furious because their iOS app expects usermobile. Propose a solution that satisfies both teams without breaking the iOS app and without creating a v2 endpoint just for one field. *(Hint: Can an API return both keys?)*

14. MCQs with Answers

Question 1

Which of the following API modifications is considered a "Non-Breaking Change" that can be safely deployed to an existing v1 endpoint without crashing legacy client applications?

Question 2

What is the industry-standard, most widely adopted strategy for versioning REST APIs due to its simplicity, ease of routing, and high visibility for developers?

15. Interview Questions

  • Q: Explain the concept of the "API Contract". How does a backend engineering team manage the codebase to support both a v1 and a v2 API simultaneously querying the exact same database table?
  • Q: Detail the steps of an API Deprecation Lifecycle. How do you gracefully force third-party developers to migrate from v1 to v2 without suddenly breaking their applications unannounced?

16. FAQs

Q: How does Stripe handle versioning? Their API doesn't use v1/v2 in the URL! A: Stripe uses Date-Based Header Versioning (e.g., Stripe-Version: 2023-10-16). It is an incredibly complex, highly advanced architecture where middleware intercepts the request, runs the data through a series of "migration functions," and mutates the JSON backward through time until it matches the exact format the client requested. It is brilliant, but far too complex for standard applications. Stick to URL versioning.

17. Summary

In Chapter 13, we recognized APIs as binding contracts between systems. We defined the severe consequences of deploying Breaking Changes to live endpoints. We explored three versioning strategies, establishing URL Versioning (/api/v1/) as the pragmatic industry standard. We learned how to structure our backend routing to support multiple parallel API versions concurrently, and outlined the professional deprecation lifecycle required to gracefully sunset obsolete endpoints.

18. Next Chapter Recommendation

Your API endpoints are perfect, but how do external developers know what URLs to hit? Proceed to Chapter 14: REST API Documentation with Swagger/OpenAPI.

Finish this Chapter

Save your progress on your learning path and prepare for coding interview challenges.

Previous Chapter Pagination, Filtering, and Sorting
Next Chapter REST API Documentation with Swagger/OpenAPI

Discussion

Join the discussion

Log in or create a free account to participate.

Sort: ·

Explore More

📖 Related Tutorials 6

❓ Related Quizzes 6

🎥 Related Videos 1