Mitgliederverwaltung/.plans/open/issue-209-api-versioning-strategy.md

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