Use when planning API versioning strategy, handling breaking changes, or managing API deprecation. Covers URL, header, and query parameter versioning approaches.
Provides strategies for API versioning, managing breaking changes, and graceful deprecation. Use when planning versioning schemes, handling migrations, or designing version-aware APIs.
/plugin marketplace add melodic-software/claude-code-plugins/plugin install systems-design@melodic-softwareThis skill is limited to using the following tools:
Strategies for versioning APIs, managing breaking changes, and deprecating old versions gracefully.
APIs are contracts with clients.
Breaking changes break clients.
Without versioning:
- Change field name → All clients break
- Remove endpoint → All clients break
- Change behavior → Unexpected client behavior
With versioning:
- Old clients use old version
- New clients use new version
- Gradual migration possible
https://api.example.com/v1/users
https://api.example.com/v2/users
Pros:
- Clear and explicit
- Easy to understand
- Easy to route
- Easy to cache
Cons:
- Version embedded in client code
- Multiple URLs for same resource
- Not truly RESTful (URL should identify resource)
GET /users
Accept: application/vnd.example.v1+json
or custom header:
GET /users
API-Version: 1
Pros:
- Clean URLs
- More RESTful
- Version separate from resource
Cons:
- Hidden from URL
- Harder to test in browser
- Requires header support
GET /users?version=1
GET /users?api-version=2023-01-01
Pros:
- Easy to add
- Optional (can default)
- Easy to test
Cons:
- Can be forgotten
- Pollutes query string
- Caching complexity
Accept: application/vnd.example+json; version=1
Pros:
- Standard HTTP mechanism
- Flexible
Cons:
- Complex to implement
- Hard to discover
| Strategy | Visibility | Implementation | Caching | Recommendation |
|---|---|---|---|---|
| URL Path | High | Easy | Easy | Best for public APIs |
| Header | Low | Medium | Medium | Good for internal APIs |
| Query Param | Medium | Easy | Complex | Good for simple cases |
| Content Neg | Low | Complex | Medium | Rarely used |
v1, v2, v3
Pros: Simple, clear major changes
Cons: Coarse-grained
Best for: Public APIs with infrequent breaking changes
v1.2.3 (major.minor.patch)
Major: Breaking changes
Minor: New features (backward compatible)
Patch: Bug fixes
Pros: Fine-grained, predictable
Cons: More complex
Best for: Libraries, SDKs
2023-01-15, 2023-06-01
Pros: Clear when version was current
Cons: Doesn't indicate change magnitude
Best for: Frequently changing APIs (Stripe, GitHub)
Example (Stripe):
Stripe-Version: 2023-10-16
Always breaking:
- Removing endpoint
- Removing field
- Changing field type
- Changing field meaning
- Renaming field
- Adding required field
- Changing authentication
- Changing error format
Safe changes:
- Adding new endpoint
- Adding optional field
- Adding new enum value
- Adding optional parameter
- Relaxing validation
- Adding new error codes
Option 1: Separate codebases
/v1/* → v1 service
/v2/* → v2 service
Pros: Full isolation
Cons: Duplication, maintenance burden
Option 2: Shared codebase with branching
if (version == 1) {
return formatV1(data);
} else {
return formatV2(data);
}
Pros: Single codebase
Cons: Code complexity grows
Option 3: Transformation layer
Internal model → Version-specific transformer → Response
Pros: Clean separation
Cons: Requires transformation code
API Gateway pattern:
Client → Gateway → Route by version → Service
Gateway responsibilities:
- Parse version from URL/header
- Route to appropriate backend
- Transform if needed
- Handle defaults
1. Current: Active development
2. Maintained: Bug fixes only
3. Deprecated: No changes, sunset announced
4. Sunset: Removed
Timeline example:
v1: Current (12 months)
v1: Maintained when v2 launches (6 months)
v1: Deprecated (6 months)
v1: Sunset
Headers:
Deprecation: true
Sunset: Sat, 1 Jul 2024 00:00:00 GMT
Link: <https://api.example.com/v2/docs>; rel="successor-version"
Response body:
{
"data": {...},
"_deprecation": {
"message": "This API version is deprecated",
"sunset": "2024-07-01",
"successor": "https://api.example.com/v2"
}
}
Provide:
1. Migration guide documenting all changes
2. Mapping of old → new endpoints
3. Code examples for common operations
4. SDK updates with compatibility layer
5. Sandbox environment for testing
Options:
1. Require explicit version (recommended for public APIs)
2. Default to latest (dangerous for stability)
3. Default to oldest supported (conservative)
Recommendation: Require version, fail without it
Include version info in responses:
{
"data": {...},
"_meta": {
"api_version": "v2",
"deprecated": false
}
}
When version unknown:
1. Return error with supported versions
2. Redirect to documentation
3. Return latest version with warning
HTTP 400 Bad Request
{
"error": "Unknown API version",
"supported_versions": ["v1", "v2"],
"documentation": "https://docs.example.com/api"
}
Test matrix:
- All supported versions
- Breaking change boundaries
- Deprecation warnings
- Sunset behavior
Automated tests:
- Contract tests per version
- Backward compatibility tests
- Migration path tests
Date-based: 2023-10-16
Header: Stripe-Version
Default: Account's API version
Rollback: Can pin to older version
Upgrades: Preview in dashboard
Date-based: 2022-11-28
Header: X-GitHub-Api-Version
Default: Latest
Preview features: Accept header
URL path: /v1/, /v2/
Discovery document for each version
Long deprecation cycles (years)
Date-based: 2010-04-01
URL path includes date
Very long support windows
1. Too many versions
→ Consolidate, set deprecation schedule
2. Breaking changes in minor versions
→ Follow semantic versioning strictly
3. No deprecation warnings
→ Always communicate before breaking
4. Instant sunset
→ Give clients time to migrate (6-12 months minimum)
5. Version per endpoint
→ Keep all endpoints in sync per version
api-design-fundamentals - API design patternsidempotency-patterns - Safe API operationsquality-attributes-taxonomy - Maintainability attributesCreating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields, or particle systems. Create original algorithmic art rather than copying existing artists' work to avoid copyright violations.
Applies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.
Create beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists' work to avoid copyright violations.