API Versioning Strategies

# CHAPTER 23

API Versioning Strategies #

1. Introduction #

2. Learning Objectives #

• Define what constitutes a "Breaking Change" in an API.

• Implement URL-based versioning (e.g., /v1/, /v2/).

• Understand Header-based versioning.

• Explain the concept of Backward Compatibility.

• Implement basic version routing in a PHP application.

3. Beginner-Friendly Explanation #

In APIs, "Model 1" is Version 1 (v1). When we make massive changes, we don't delete v1; we create v2 and run them side-by-side until everyone upgrades.

4. Real-World Examples #

• Twitter API: Look at Twitter's endpoints: https://api.twitter.com/2/tweets. That /2/ means they are on Version 2 of their entire architectural design.

• Stripe API: Stripe uses date-based versioning passed in the headers. You send a header like Stripe-Version: 2023-10-16, and Stripe transforms the response to match how the API worked on that specific date!

5. Detailed Code Examples #

<?php
// Get the requested URL path: /api/v1/users
$uri = parse_url($_SERVER[&#039;REQUEST_URI'], PHP_URL_PATH);
$uri = explode(&#039;/', $uri);

// $uri[1] is 'api', $uri[2] is 'v1', $uri[3] is 'users'
$version = $uri[2] ?? &#039;v1';
$resource = $uri[3] ?? null;

if ($resource === &#039;users') {
    if ($version === &#039;v1') {
        // Old Version logic
        echo json_encode([
            "id" => 5,
            "first_name" => "Jane",
            "last_name" => "Doe"
        ]);
    } elseif ($version === &#039;v2') {
        // New Version logic (combining names)
        echo json_encode([
            "id" => 5,
            "full_name" => "Jane Doe",
            "created_at" => "2023-10-01"
        ]);
    } else {
        http_response_code(404);
        echo json_encode(["error" => "Unsupported API version"]);
    }
}
?>

6. Request/Response Examples #

Client A Request: GET /api/v1/users/5 Response: {"firstname": "Jane", "lastname": "Doe"}

Client B Request: GET /api/v2/users/5 Response: {"full_name": "Jane Doe"}

7. HTTP Examples #

GET /api/users/5 HTTP/1.1
Host: api.example.com
Accept: application/vnd.myapi.v2+json

*Here, the client specifies they want version 2 inside the Accept header instead of the URL.*

8. JSON Examples #

{
  "meta": {
    "warning": "API v1 is deprecated and will be shut down on Dec 31, 2026. Please migrate to v2."
  },
  "data": {
    "first_name": "Jane"
  }
}

9. Best Practices #

• Version from Day 1: Always put /v1/ in your base URL from the very beginning (https://api.yourapp.com/v1/). If you don't, adding /v2/ later creates a messy, inconsistent architecture.

• Maintain Backward Compatibility: Do not increment to v2 for minor changes. Adding a *new* field to a JSON response is backward compatible (old apps just ignore the new field). Removing or renaming a field is a *breaking change* and requires a new version.

• Deprecation Schedules: Never turn off v1 overnight. Give developers 6 to 12 months' notice via email and API headers before turning off an old version.

10. Common Mistakes #

• Creating a v2 for bug fixes: Versions should only change for structural data changes. Bug fixes and performance improvements should be applied directly to v1.

• Duplicating all code: When making v2, don't copy/paste your entire codebase. v1 and v2 should share the same database and core models; only the *Controllers* (the formatting of the JSON) should differ.

11. Mini Exercises #

1. 1. Determine if this is a breaking change: You have an endpoint GET /products. You decide to add a new "stock_count": 50 field to the JSON response.

1. 2. Determine if this is a breaking change: You decide to change the "price" field from a string "$10.00" to an integer 1000 (cents).

12. Coding Challenges #

13. MCQs with Answers #

14. Interview Questions #

• Q: Explain the difference between URL Versioning and Header Versioning. Which do you prefer and why?

• Q: Give three examples of "Breaking Changes" that would require bumping the API version.

• Q: How do you handle the codebase when supporting both v1 and v2 simultaneously without duplicating massive amounts of code?

15. FAQs #

16. Summary #

17. Next Chapter Recommendation #