API Versioning Strategies

1. The Inevitability of Change

Imagine your application has a User model, and your API currently returns user data like this:

{
  "first_name": "Alex",
  "last_name": "Williams"
}

A mobile app is built to consume this API, displaying first_name and last_name in separate fields. Now, a new requirement comes from the product team: they want to replace first_name and last_name with a single full_name field for all new development.

If you simply change the API to return this:

{
  "full_name": "Alex Williams"
}

You've just broken the existing mobile app. It's still looking for first_name and last_name, which are no longer there. This is known as a breaking change. API versioning is the solution to this problem. It allows you to release new, improved versions of your API while maintaining older versions for existing clients, giving them time to upgrade.

2. Explicit Versioning and SemVer

The core idea behind versioning is to explicitly maintain multiple, callable versions of your API. This allows you to evolve your API in a structured way. But what do version numbers like v1, v2, or v3.1.1 actually mean?

For this, many developers follow a specification called Semantic Versioning (SemVer). It provides a formal system for assigning meaning to version numbers.

To summarize SemVer (MAJOR.MINOR.PATCH):

• MAJOR version (e.g., v1 -> v2): You increment this when you make incompatible, breaking changes. This is a signal to all clients that they will need to modify their code to use the new version.
• MINOR version (e.g., v1.0 -> v1.1): You increment this when you add new functionality in a backward-compatible way. For example, adding a new optional field to a response. Existing clients won't break.
• PATCH version (e.g., v1.1.0 -> v1.1.1): You increment this for backward-compatible bug fixes.

Most public APIs only expose the MAJOR version (e.g., /v1, /v2), as minor and patch changes are backward-compatible and clients can typically be upgraded to them automatically.

3. Common Versioning Strategies

Now that we know why we version and what the numbers mean, let's explore how a client can request a specific version of an API. There are three primary strategies.

The following article from the Medium publication "CodeX" gives a great high-level overview of these strategies, including their advantages and disadvantages.

Let's break these down further, with a focus on how they relate to Django REST Framework. The official DRF documentation is the best source for this. We will be referencing its "Versioning" page.

A. URL Path Versioning

This is arguably the most common and straightforward strategy. The version number is embedded directly in the URL.

• Example: https://api.example.com/v1/users/

This is the approach used by major API providers like Stripe and Slack.

• Pros:
  • Highly visible and clear: It's immediately obvious which version of the API is being called.
  • Easy to test: You can simply type different URLs into a browser or API client to test different versions.
  • Bookmarkable: URLs for specific versions can be saved and shared easily.
• Cons:
  • "Pollutes" the URI: Some argue this violates the REST principle that a URI should identify a unique resource, not a version of it. The resource is /users/, and /v1/users/ is just one representation.
  • Can lead to more complex routing logic: As you see in the DRF examples, it requires specific URL patterns.

This is the strategy we will implement in our next lesson due to its clarity and popularity.

B. Header Versioning

In this approach, the client requests a version via an HTTP header, keeping the URL itself "clean" and version-agnostic.

• Example 1 (Custom Header): GET /users/ with a header X-API-Version: 1
• Example 2 (Accept Header): GET /users/ with the header Accept: application/json; version=1.0

• Pros:
  • Clean URLs: The URI (/users/) remains constant and purely represents the resource.
  • RESTful: Aligns well with the principles of content negotiation, where the client "negotiates" for the representation it wants.
• Cons:
  • Less visible: The version is "hidden" in the headers, making it harder to see at a glance or test in a browser's address bar.
  • More complex for clients: Requires clients to know how to construct requests with custom headers.

C. Query Parameter Versioning

This strategy is a middle ground, keeping the URL path clean but making the version visible in the query string.

• Example: https://api.example.com/users?version=1

• Pros:
  • Simple to implement and use.
  • Keeps the URL path clean.
• Cons:
  • Potential caching issues: Some proxy caches might not handle query parameters well or might treat /users?version=1 and /users?version=2 as requests for completely different resources, leading to cache bloat.
  • Can be cluttered: If the endpoint already uses many query parameters for filtering and sorting, adding another for versioning can make the URL messy.

Conclusion

Today, we explored the critical concept of API versioning—a fundamental practice for building sustainable, professional-grade backend services. Understanding how to manage change without disrupting existing users is a hallmark of a skilled backend engineer.

Key Takeaways:

• Why Version? To introduce new features and breaking changes without breaking existing client applications, ensuring backward compatibility.
• What do versions mean? Semantic Versioning (MAJOR.MINOR.PATCH) provides a standard for communicating the nature of changes. Major versions indicate breaking changes.
• How do we version? There are three common strategies, each with trade-offs:
  • URL Path Versioning (/v1/resource): Most visible and easy to use, but "pollutes" the URL.
  • Header Versioning (Accept: ...; version=1): Keeps URLs clean and is considered more "RESTful," but is less intuitive for clients.
  • Query Parameter Versioning (/resource?version=1): A simple compromise, but can have caching implications.

Preview of the Next Lesson:
We've covered the theory and described the common strategies. In the next lesson, we will put this knowledge into practice. We will implement URL-based versioning for a DRF API, as it is one of the most common and explicit methods for managing API evolution. You'll see how DRF's built-in tools make this a surprisingly manageable task.