Was ist API-Versionierung
API-Versionsverwaltung
API-Versionierung
API-Versionierung ist die Praxis der Verwaltung von API-Änderungen bei gleichzeitiger Aufrechterhaltung der Abwärtskompatibilität für bestehende Clients.
Versionierungsstrategien
| Strategie | Beispiel | Beschreibung | |-----------|----------|--------------| | URL-Pfad | /api/v1/users | Version im URL-Pfad | | Query-Parameter | /api/users?version=1 | Version im Parameter | | Header | X-API-Version: 1 | Version im Header | | Content-Type | Accept: application/vnd.api.v1+json | Media-Type-Version |
Semantische Versionierung
- Major (v1→v2) — Breaking Changes
- Minor (v1.1→v1.2) — neue Funktionen, abwärtskompatibel
- Patch (v1.1.0→v1.1.1) — Fehlerbehebungen
Best Practices
- Alle Änderungen dokumentieren (Changelog)
- Mindestens 2 Versionen unterstützen
- Deprecation im Voraus ankündigen
- Sunset-Header verwenden
- Migrationstools bereitstellen
Wann eine neue Version benötigt wird
- Entfernen von Feldern oder Endpunkten
- Ändern des Antwortformats
- Ändern der Parametersemantik
- Ändern der Authentifizierung