shahondin1624
b29a268b1d
- Move completed plan files to .plans/done/ - Move 18 open plan files to .plans/open/ - Update .gitignore to exclude .verified_plans temp file - Verified all 18 open plans still describe unimplemented issues
60 lines
1.5 KiB
Markdown
60 lines
1.5 KiB
Markdown
# Issue #209: No API Versioning Strategy
|
|
|
|
## Problem
|
|
|
|
All API endpoints use `/api/v1/` prefix but there's no formal versioning strategy. When breaking changes are needed (e.g., restructuring the member response), there's no clean migration path.
|
|
|
|
Current endpoints:
|
|
```
|
|
/apps/mitgliederverwaltung/api/v1/members
|
|
/apps/mitgliederverwaltung/api/v1/families
|
|
/apps/mitgliederverwaltung/api/v1/fees
|
|
...
|
|
```
|
|
|
|
## Impact
|
|
|
|
- Breaking frontend changes require immediate backend deployment
|
|
- No backward compatibility for mobile apps or third-party integrations
|
|
- Hard to deprecate old formats gracefully
|
|
|
|
## Solution
|
|
|
|
Implement a proper versioning strategy:
|
|
|
|
1. **URL Versioning** (current approach):
|
|
```
|
|
/api/v1/members → Current version
|
|
/api/v2/members → New version with breaking changes
|
|
```
|
|
|
|
2. **Header Versioning** (alternative):
|
|
```
|
|
GET /api/members
|
|
Accept: application/vnd.mitgliederverwaltung.v1+json
|
|
|
|
GET /api/members
|
|
Accept: application/vnd.mitgliederverwaltung.v2+json
|
|
```
|
|
|
|
3. **Deprecation Path**:
|
|
- v1 marked as deprecated in response headers
|
|
- v2 available in parallel
|
|
- v1 removed after 6 months
|
|
|
|
## Tasks
|
|
|
|
- [ ] Document API versioning strategy in docs/
|
|
- [ ] Implement v2 endpoints for critical entities (Member first)
|
|
- [ ] Add deprecation headers to v1 responses
|
|
- [ ] Update frontend to use v2 endpoints
|
|
- [ ] Create migration guide for v1 → v2
|
|
- [ ] Set deprecation timeline (e.g., remove v1 in next major release)
|
|
|
|
## Labels
|
|
|
|
- enhancement
|
|
- backend
|
|
- api
|
|
- priority:low
|
|
- architecture |