tomevault-io Versioning APIs
Overview
Implement API versioning strategies -- URL path (/v1/, /v2/), header-based (Accept: application/vnd.api.v2+json), or query parameter (?version=2) -- with backward compatibility layers, deprecation notices, and automated migration paths. Manage concurrent version support, sunset timelines, and breaking change detection across the API surface.
Prerequisites
- Existing API codebase with route definitions and controller implementations
- Version control history for tracking breaking changes across releases
- OpenAPI specs for each supported API version (or ability to generate them)
- API gateway or reverse proxy capable of version-based routing (optional: Kong, AWS API Gateway)
- Consumer notification channel for deprecation announcements (changelog, email, response headers)
Instructions
- Audit existing endpoints using Grep and Read to identify current versioning approach (if any) and catalog all public-facing endpoints with their request/response contracts.
- Select a versioning strategy based on API consumer patterns: URL path versioning for public APIs, header versioning for APIs needing clean URLs, or content negotiation for advanced use cases.
- Create a version router that directs requests to the appropriate version handler set based on the extracted version identifier from URL, header, or query parameter.
- Implement version-specific controller directories (
/v1/controllers/,/v2/controllers/) with shared business logic extracted into version-independent service layers. - Build a compatibility layer that transforms v1 requests into v2 format and v2 responses back to v1 format, enabling older versions to run on the latest business logic.
- Add deprecation headers to sunset versions:
Deprecation: true,Sunset: <date>, andLink: <migration-guide-url>; rel="sunset"per the Sunset HTTP header RFC. - Create a breaking change detector that compares OpenAPI specs between versions and flags removed fields, changed types, new required parameters, and altered response structures.
- Write version compatibility tests that send v1-formatted requests and verify correct responses, ensuring the compatibility layer preserves backward compatibility.
See ${CLAUDE_SKILL_DIR}/references/implementation.md for the full implementation guide.
Output
${CLAUDE_SKILL_DIR}/src/routes/v1/- Version 1 route definitions${CLAUDE_SKILL_DIR}/src/routes/v2/- Version 2 route definitions${CLAUDE_SKILL_DIR}/src/middleware/version-router.js- Version extraction and routing middleware${CLAUDE_SKILL_DIR}/src/compatibility/- Request/response transformation layers between versions${CLAUDE_SKILL_DIR}/src/utils/breaking-change-detector.js- OpenAPI diff tool for breaking changes${CLAUDE_SKILL_DIR}/docs/migration-guide-v1-to-v2.md- Consumer migration documentation
Error Handling
| Error | Cause | Solution |
|---|---|---|
| 400 Unsupported Version | Client requests a version that does not exist | Return available versions list in error body; suggest closest valid version |
| 410 Gone | Client requests a sunset version past its end-of-life date | Return migration guide URL and recommended current version in error body |
| Compatibility layer failure | v1-to-v2 transform encounters a field with no mapping | Log unmapped fields; return partial response with warning header; alert API team |
| Version header ignored | Client sets version header but reverse proxy strips custom headers | Document required proxy configuration; add URL path fallback for header-based versioning |
| Breaking change undetected | Semantic change (same field name, different meaning) not caught by schema diff | Add contract tests with business-logic assertions beyond schema structure |
Refer to ${CLAUDE_SKILL_DIR}/references/errors.md for comprehensive error patterns.
Examples
URL path versioning: Migrate from /api/users to /api/v1/users and /api/v2/users where v2 changes name (string) to firstName/lastName (object), with v1 compatibility layer that joins the fields.
Header-based versioning: Route requests using Accept: application/vnd.myapi.v2+json with a default version fallback for clients omitting the header, and version discovery via OPTIONS responses.
Sunset lifecycle management: Announce v1 deprecation with 6-month sunset timeline, add Sunset headers immediately, log v1 usage metrics to track migration progress, and auto-disable after sunset date.
See ${CLAUDE_SKILL_DIR}/references/examples.md for additional examples.
Resources
- RFC 8594 The Sunset HTTP Header Field
- API Versioning strategies comparison (Stripe, GitHub, Twilio approaches)
- OpenAPI diff tools: oasdiff, openapi-diff
- Semantic Versioning 2.0.0: https://semver.org/
Converted and distributed by TomeVault — claim your Tome and manage your conversions.