Wenn die API aktiv weiterentwickelt wird, ist es wichtig, die Kompatibilität zwischen den Versionen aufrechtzuerhalten und Situationen zu vermeiden, in denen eine einzelne Änderung Dutzende von Client-Integrationen stört. Wir implementieren eine vollständige Versionierung von Verträgen, die es uns ermöglicht, Änderungen zu kontrollieren und APIs reibungslos zu aktualisieren, ohne Risiken für die Benutzer einzugehen.
Dies ist in Microservice-Architekturen, B2B-Integrationen und offenen API-Produkten, bei denen verschiedene Kunden unterschiedliche Versionen von Schnittstellen verwenden, von entscheidender Bedeutung.
Was wir versionieren
| Objekt | Die Beschreibung |
|---|---|
| OpenAPI-Spezifikation | Wir speichern jede Version der Dokumentation und des Vertrags |
| Endpoint'ы | Hinzufügen von Versionen zur URL ('/v1/', '/v2/'), Backward-Kompatibilität beibehalten |
| Verträge (Pact, Dredd) | Festlegung der Bedingungen für die Interaktion zwischen Client und Server |
| Datenmodelle | Überwachung von Änderungen in der Anfrage- und Antwortstruktur |
Wie wir umsetzen
Unterstützung mehrerer API-Versionen parallel
Explizite Angabe der Version in URLs, Überschriften oder Parametern
Autotest jeder Vertragsversion (Pact, Postman, Jest, Dredd)
Versionierung der Spezifikationen in Git oder über CI/CD
Dokumentation und Changelog für Kunden bei jeder Änderung
Vorteile
Garantierte Stabilität der Integrationen
Die Fähigkeit, neue Fiches zu veröffentlichen, ohne das Risiko, Kunden zu „brechen“
Vereinfachung der Migration zwischen Versionen
Klare Änderungshistorie und Vertragssteuerung
Transparenz für externe und interne Entwicklungsteams
Wo es besonders wichtig ist
Microservice-Architektur mit vielen Abhängigkeiten
Plattformen mit öffentlicher oder B2B-API
Finanz- und Zahlungssysteme mit langfristigen Verträgen
Mobile Anwendungen, die auf eine stabile API angewiesen sind
Die Versionierung von Verträgen ist die Grundlage für Berechenbarkeit und Vertrauen in die API. Wir implementieren Prozesse, die es uns ermöglichen, APIs ohne Probleme zu ändern und zu entwickeln, während die Kompatibilität und Transparenz für alle Parteien erhalten bleibt.