Help us improve
Share bugs, ideas, or general feedback.
From grimoire
Designs an API versioning policy (URL path, date-based, or header versioning) to evolve APIs without breaking existing consumers. Includes breaking vs. non-breaking change rules and version lifecycle policies.
npx claudepluginhub jeffreytse/grimoire --plugin grimoireHow this skill is triggered — by the user, by Claude, or both
Slash command
/grimoire:design-api-versioning-strategyThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Establish a versioning policy that allows APIs to evolve and add capabilities without breaking existing consumers.
Guides API versioning strategies including URL path, header, query parameter, and content negotiation. Helps manage breaking changes, deprecations, and multiple versions.
Produces a complete API versioning strategy with scheme selection, breaking-change classification, deprecation timeline, migration guide, and client communication templates for REST, GraphQL, or gRPC.
Guides API versioning strategies: URL path vs headers, Stripe-style date-based, deprecation with sunset headers, backward compatibility, and non-breaking evolution.
Share bugs, ideas, or general feedback.
Establish a versioning policy that allows APIs to evolve and add capabilities without breaking existing consumers.
Adopted by: Stripe (date-based versioning, industry gold standard), GitHub (version in URL path), Google APIs (version in URI), Twilio (URL versioning with LTS commitments) Impact: Stripe's versioning strategy is cited as enabling 10+ years of API evolution without forced migrations; unversioned APIs that break consumers cause integration incidents that cost enterprise customers 40+ engineering hours per incident Why best: APIs are contracts; breaking changes without versioning destroy trust and require coordinated cross-team upgrades; versioning decouples provider evolution from consumer upgrade timelines
Sources: Microsoft "REST API Guidelines" (2016, github.com/microsoft/api-guidelines); Stripe API versioning documentation; Fielding REST dissertation (2000)
Choose a versioning scheme — URL path versioning (/v1/orders): most common, explicit, easy to route, easy to document. Date-based (2024-01-01): Stripe's model, enables precise semantics per version, ideal for continuous evolution. Header versioning (Accept: application/vnd.api+json; version=1): keeps URL clean, harder to test in browser. Choose URL path for new APIs unless you model after Stripe's release-date approach.
Define breaking vs. non-breaking changes — Non-breaking (never require a version bump): adding new optional fields to responses, adding new optional query parameters, adding new endpoints. Breaking (require a version bump): removing or renaming fields, changing field types, changing required parameters, altering authentication requirements. Enforce this distinction in API review.
Establish a versioning policy — Document: how long each version is supported (minimum 12 months after deprecation notice), how consumers are notified of deprecations (email, HTTP headers, changelog), and what "end-of-life" means (returns 410 Gone or is disabled). Publish this policy before releasing v1. Stripe's policy: versions are supported indefinitely unless the version has negligible usage.
Implement version routing — Route requests by version at the API gateway or load balancer layer, not in application code. This allows independent deployment of version implementations. If using URL path versioning, the path prefix (/v1/, /v2/) is the routing key. Version routing at the gateway enables zero-downtime version migrations.
Use semantic versioning for major, minor, patch — Major (v1 → v2): breaking changes. Minor (v1.1): additive, non-breaking changes. Patch: bug fixes. For REST APIs, expose only the major version in the URL; minor/patch changes are transparent to consumers. Document minor changes in the API changelog.
Apply the tolerant reader pattern to consumers — API consumers must ignore unknown fields (don't fail on extra fields in the response). Consumers that are strict about response schemas will break on non-breaking additive changes. Enforce this in integration tests: add extra fields to mock responses and verify consumers handle them.
Deprecate before removing — Before removing any endpoint or field: add a Deprecation header to responses (Deprecation: true; rel="deprecation"; type="text/html"), log a warning in the API docs, email all registered consumers, and set a minimum 12-month sunset timeline. Never remove without a deprecation period.
Maintain a machine-readable changelog — Use OpenAPI (Swagger) or GraphQL schema to document every version. Generate diffs between versions automatically (oasdiff for OpenAPI, graphql-inspector). Consumers can programmatically detect changes. This is the foundation for automated compatibility testing.
Test version compatibility in CI — Run contract tests (Pact or schema validation) between your API versions and consumer versions. The CI pipeline must catch breaking changes before they reach production. Use API linting tools (Spectral, Optic) to enforce non-breaking change policy on every PR.
Sunset retired versions gracefully — 6 months before EOL: increase deprecation warnings, reach out to high-usage consumers. 1 month before EOL: return HTTP 301 redirects to the current version with documentation. On EOL date: return HTTP 410 Gone with a migration guide URL. Never return 404 for sunsetted versions; 410 signals intentional retirement.
/v2/orders/create) while leaving others unversioned; version the API, not individual endpoints.?version=1) — query params are for filtering data, not API versions; hard to cache, easy to omit; URL path or header versioning is preferred.