Menu
The review-first prompt is selected by default. You can switch to a direct command or download a local copy.
Read SKILL.md and any companion files shown by SkillsMP before deciding whether to install.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
npx skills add https://github.com/pluginagentmarketplace/custom-plugin-api-design --skill versioningThe command stays on one line. Scroll horizontally to inspect it before copying.
Prefer a local copy? Download the files currently available to SkillsMP.
REST, GraphQL, and hybrid API architecture patterns for building scalable and maintainable APIs
Production-grade backend patterns for Node.js, Python, Go, and Java/Spring frameworks
Database design, optimization, and caching strategies for SQL, NoSQL, and Redis
Based on SOC occupation classification
Showing SKILL.md
| name | versioning |
| version | 2.0.0 |
| description | API versioning strategies and backward compatibility |
| sasmp_version | 1.3.0 |
| bonded_agent | 01-api-architect |
| bond_type | PRIMARY_BOND |
| atomic_design | {"single_responsibility":"API versioning and deprecation management","boundaries":{"includes":["url_versioning","header_versioning","deprecation","migration"],"excludes":["api_design","implementation"]}} |
| parameter_validation | {"schema":{"type":"object","properties":{"strategy":{"type":"string","enum":["url","header","query"]},"version_format":{"type":"string","pattern":"^v?[0-9]+$"}}}} |
| retry_config | {"enabled":false} |
| logging | {"level":"INFO","fields":["version","strategy","deprecated"]} |
| dependencies | {"skills":["api-architecture"],"agents":["01-api-architect"]} |
Choose and implement API versioning strategies.
| Strategy | Format | Pros | Cons |
|---|---|---|---|
| URL path | /api/v1/users | Clear, cacheable | URL pollution |
| Header | Accept: application/vnd.api.v1+json | Clean URLs | Hidden |
| Query param | /api/users?version=1 | Flexible | Unconventional |
# Version in path
/api/v1/users # Current stable
/api/v2/users # New version
/api/v3-beta/users # Pre-release
# Version-specific routing
app.use('/api/v1', v1Router);
app.use('/api/v2', v2Router);
# Request
Accept: application/vnd.myapi.v1+json
# Response
Content-Type: application/vnd.myapi.v1+json
# Sunset header
Sunset: Sat, 31 Dec 2025 23:59:59 GMT
Deprecation: true
Link: </api/v2/users>; rel="successor-version"
# Response body warning
{
"data": {...},
"warnings": [
{
"type": "deprecation",
"message": ,
}
]
}
# Migration from v1 to v2
## Breaking Changes
### User endpoint
- `GET /api/v1/users/{id}` → `GET /api/v2/users/{id}`
- Response field `fullName` renamed to `name`
### Before (v1)
{
"id": "123",
"fullName": "John Doe"
}
### After (v2)
{
"id": "123",
"name": "John Doe"
}
## Timeline
- v2 available: January 2025
- v1 deprecated: March 2025
- v1 removed: December 2025
describe('API Versioning', () => {
it('should route to v1 handler', async () => {
await request(app)
.get('/api/v1/users')
.expect(200);
});
it('should include deprecation headers for old version', async () => {
const res = await request(app)
.get('/api/v1/users')
.expect(200);
expect(res.headers.deprecation).toBe('true');
expect(res.headers.sunset).toBeDefined();
});
});
| Issue | Cause | Solution |
|---|---|---|
| Clients use wrong version | No redirect | Add version negotiation |
| Breaking change missed | No detection | Use schema diff tools |
| Sunset too short | Client migration time | Minimum 6 month notice |