478254400a
- Updated service template structure in `ARCHITECTURE.md` and `README.md` for clarity and usability. - Enhanced bilingual documentation across skills, increasing the number of available skills from 15 to 25. - Added new sections on event-driven architecture, inter-service communication, and performance optimization. - Improved formatting and removed outdated references to streamline the documentation experience.
56 lines
1.3 KiB
Markdown
56 lines
1.3 KiB
Markdown
---
|
|
name: api-versioning-strategy
|
|
description: API versioning strategies for GoodGo microservices including semantic versioning, backward compatibility patterns, API deprecation, version negotiation, and breaking changes handling.
|
|
---
|
|
|
|
# API Versioning Strategy
|
|
|
|
## When to Use This Skill
|
|
|
|
Use this skill when:
|
|
- Versioning APIs
|
|
- Handling breaking changes
|
|
- Implementing API deprecation
|
|
- Maintaining backward compatibility
|
|
- Implementing version negotiation
|
|
|
|
## Key Patterns
|
|
|
|
### URL Path Versioning
|
|
|
|
```typescript
|
|
// Version routes
|
|
router.use('/v1', v1Router);
|
|
router.use('/v2', v2Router);
|
|
```
|
|
|
|
### Header-Based Versioning
|
|
|
|
```typescript
|
|
// Version negotiation
|
|
const acceptHeader = req.headers.accept;
|
|
const version = acceptHeader.match(/application\/vnd\.goodgo\.v(\d+)\+json/)[1];
|
|
```
|
|
|
|
### Deprecation
|
|
|
|
```typescript
|
|
// Deprecation headers
|
|
res.setHeader('Deprecation', 'true');
|
|
res.setHeader('Sunset', '2024-12-31');
|
|
res.setHeader('Warning', 'API version 1 is deprecated');
|
|
```
|
|
|
|
## Best Practices
|
|
|
|
1. Choose versioning strategy and be consistent
|
|
2. Use semantic versioning (MAJOR.MINOR.PATCH)
|
|
3. Always deprecate before removing
|
|
4. Provide migration guides
|
|
5. Maintain backward compatibility when possible
|
|
|
|
## Resources
|
|
|
|
- [API Design](./api-design.md)
|
|
- Skill Source: `.cursor/skills/api-versioning-strategy/SKILL.md`
|