api-versioning

Create separate APIRouter instances with prefixes like /api/v1 and /api/v2, then define version-specific handlers on each router. Alternatively, read an api_version header and route requests to the appropriate handler logic.

URI versioning puts the version in the path (e.g., /api/v2/users), making versions explicit and easy to route. Header versioning keeps URLs stable and selects behavior via an api_version request header, but is less visible to consumers.

Mark the endpoint deprecated and return X-API-Deprecated and X-API-Sunset headers with a removal date, plus a Link header pointing to the successor version. Give consumers a documented migration path before removal.

Bump the major version when introducing incompatible changes such as altered response formats or newly required authentication. Backwards-compatible additions increment the minor version, and bug fixes increment the patch version.

Skip versioning for simple API design or internal function changes where a single evolving contract suffices. Versioning adds routing and maintenance overhead that is only justified when external consumers depend on stable contracts.