Client-Version Negotiation — How API Clients Choose Compatible Versions

In this tutorial, you'll learn about Client Version Negotiation. We cover key concepts, practical examples, and best practices to help you understand and apply this topic effectively.

Client-version negotiation enables API clients to automatically discover and select compatible API versions, reducing manual configuration and improving integration reliability.

from typing import Dict, Optional, List

client = APIClient("https://api.example.com")
client.set_supported_versions(["v1", "v2", "v3"])
server_versions = client.discover_versions()
selected = client.negotiate(server_versions)
print(f"Server supports: {server_versions}")
print(f"Client selected: {selected}")

class APIClient: def discover_versions(self): import requests resp = requests.get(f"{self.base}/api/versions") return resp.json().get("versions", [])

def negotiate(self, server_versions: List[str]) -> Optional[str]:
    for cv in reversed(sorted(self.supported)):
        if cv in server_versions:
            return cv
    return self.supported[-1] if self.supported else None