Schon eine kleine Änderung einer API-Antwort kann Clients beschädigen. Prüfen Sie den Vertrag vor dem Release anhand echter Nutzungsszenarien. DAS VERSPRECHEN DOKUMENTIEREN Halten Sie für wichtige Operationen Methode, Adresse, Parameter, Pflichtfelder, Typen und Fehler fest. OpenAPI bietet ein Format für die Beschreibung von HTTP-APIs. Eine Datei beweist jedoch nicht die Übereinstimmung der Implementierung. Benennen Sie einen Verantwortlichen und verknüpfen Sie die Beschreibung mit dem Releaseablauf. UNAUFFÄLLIGE ÄNDERUNGEN PRÜFEN Ein entferntes Feld fällt schnell auf. Umbenennung, Zahl als Zeichenkette, neuer Enum-Wert oder geändertes Null-Verhalten zeigen sich manchmal erst im Client. Auch ein zusätzliches optionales Feld kann einen strengen Parser stören. Unterscheiden Sie eindeutig inkompatible Änderungen von solchen, die mit bestimmten Verbrauchern geprüft werden müssen. EINEN KLEINEN TESTSATZ AUFBAUEN Verwenden Sie harmlose Beispiele: normales Ergebnis, leere Liste, fehlendes optionales Feld, Validierungsfehler und verweigerter Zugriff. Ergänzen Sie unterstützte Währungen oder Datumsdarstellungen, falls sie zum Vertrag gehören. Testen Sie mit unterstützten Clientversionen und nicht nur dem neuen Server. Zahlungsintegrationen gehören dabei in die Testumgebung des Anbieters ohne echte Belastung. DEN ÜBERGANG PLANEN Vereinbaren Sie bei inkompatiblen Änderungen Versionierung und Übergangszeit. Ein Termin im internen Ticket informiert keine API-Nutzer. Dokumentieren Sie Benachrichtigungen, neue Dokumentation und die Zuständigkeit für alte Aufrufe. Microsoft behandelt Versionierung als Teil der Unterstützung bestehender Verbraucher; das konkrete Verfahren muss zum Produkt passen. Planen Sie eine stabile Dokumentationsadresse und API-Subdomain. Eine klare Domainstruktur erleichtert die Navigation, ersetzt aber keinen kompatiblen Vertrag. Bewahren Sie die Testergebnisse beim Releaseprotokoll auf, damit spätere Änderungen auf überprüfbaren Ergebnissen beruhen. Bild: neue KI-Fotoillustration für diesen Artikel; konzeptionelle Szene, keine dokumentarische Aufnahme. Domain-Katalog: https://domainevery.com/de/domains Primärquellen: https://learn.microsoft.com/en-us/azure/architecture/best-practices/api-design https://spec.openapis.org/oas/latest.html
