Start with goals: keep existing clients working, make it easy to discover and select variants, and allow safe rollouts.
URL-based versioning:
- Use stable, human-readable routes for major API changes: /v1/predict, /v2/predict. Good for caching, routing, and analytics. Reserve for breaking contract changes (input/output schema, semantics).
- Example: POST /v2/models/gpt-2.1/predict
Header-based versioning:
- Use for non-breaking changes or to let clients opt into features without changing URLs: Accept-Version: v1; Model-Variant: gpt-2.1. Cleaner endpoints, easier A/B and gradual migration.
- Default to the latest safe version if header missing; document default behavior.
Model-registry integration:
- Maintain a registry that maps model IDs, semantic versions, variant tags (stable, canary), and contract schema (OpenAPI/JSON Schema). Integrate registry with routing so /models/{id} resolves to the current variant or a pinned version.
- Store input/output schemas and example payloads in the registry for automated validation and SDK generation.
Client deprecation windows:
- Announce breaking changes with clear timelines (e.g., 90 days), provide migration guides, and support both versions concurrently during the window.
- Log usage per-version, proactively contact high-volume clients. Automatically redirect deprecated minor changes only when safe after notice.
Communication and SDK coordination:
- Publish change logs, API docs, and schema diffs. Provide migration examples and code snippets.
- Release SDK updates timed with server changes; keep SDKs backward-compatible and allow clients to pin API version easily (constructor option or header).
- Offer feature flags and a sandbox endpoint for testing. Use email, dashboards, and in-console warnings for deprecation notices.
Operational practices:
- CI checks that validate new model contracts against schema and run integration tests.
- Canary deployments for new variants and metric monitoring (latency, error-rate, semantic drift).
- Prefer semantic versioning for contracts (MAJOR breaks, MINOR backwards-compatible extensions, PATCH fixes).
These combined strategies balance stability and agility, letting you serve multiple model variants while minimizing client disruption.
