Implement API Versioning - The Migrator | Build Distributed Systems

Implementation

API versioning lets you evolve your API without breaking existing clients. You support multiple versions simultaneously, warn clients on deprecated ones with Deprecation and Sunset headers, and eventually stop serving a version after its sunset date with HTTP 410.

Implement a node that routes and manages API versions:

// Route to the correct version handler
{ "type": "get_users", "msg_id": 1, "version": "v2" }
-> { "type": "users_response", "in_reply_to": 1,
    "version": "v2",
    "users": [{"id":1,"email":"user@example.com","full_name":"John Doe"}] }

// Deprecated version: add warning headers
{ "type": "get_users", "msg_id": 2, "version": "v1", "deprecated": true }
-> { "type": "users_response", "in_reply_to": 2,
    "version": "v1",
    "headers": {"Deprecation":"true","Sunset":"2024-12-31"} }

// Version negotiation via Accept header
{ "type": "get_users", "msg_id": 3 }
headers: { "Accept": "application/vnd.myapi.v2+json" }
-> { "type": "users_response", "in_reply_to": 3,
    "version": "v2", "content_type": "application/vnd.myapi.v2+json" }

// Sunset version returns 410 Gone
{ "type": "get_users", "msg_id": 4, "version": "v1", "sunset": true }
-> { "type": "error", "in_reply_to": 4, "status": 410,
    "error": "API version v1.0 has been sunset",
    "current_version": "v2.0" }

Sample Test Cases

Route to correct API versionTimeout: 5000ms

Input

{
  "src": "client",
  "dest": "api",
  "body": {
    "type": "get_users",
    "msg_id": 1,
    "version": "v2"
  }
}

Expected Output

{"type": "users_response", "in_reply_to": 1, "version": "v2", "users": [{"id": 1, "email": "user@example.com", "full_name": "John Doe"}]}

Deprecation headersTimeout: 5000ms

Input

{
  "src": "client",
  "dest": "api",
  "body": {
    "type": "get_users",
    "msg_id": 1,
    "version": "v1",
    "deprecated": true
  }
}

Expected Output

{"type": "users_response", "in_reply_to": 1, "version": "v1", "headers": {"Deprecation": "true", "Sunset": "2024-12-31"}}

Hints

Hint 1▾

Route requests by version field or Accept header to the correct handler

Hint 2▾

Deprecation header: Deprecation: true plus Sunset: <date> on v1 responses

Hint 3▾

Content negotiation: parse version from Accept: application/vnd.myapi.v2+json

Hint 4▾

Sunset (410 Gone): once the sunset date passes, reject requests with HTTP 410

Hint 5▾

Never remove a version without a sunset date announced in advance

Implementation

Sample Test Cases

Hints

Resources

Theoretical Hub

Key Concepts