Stabilität und Versionierung
Worauf sich Integrationen verlassen können, wie sich die API ändert und wo Sie den Vertrag laden.
Zwei Versionsnummern
| Version | Wo | Ändert sich, wenn |
|---|---|---|
| Pfadversion | /api/v1 in jeder URL | sich veröffentlichte Operationen inkompatibel ändern. |
| Vertragsversion | info.version im Vertrag, derzeit 0.10.0 | sich der Vertrag in irgendeiner Weise ändert. |
Das Changelog führt jede Vertragsversion mit ihren Änderungen auf.
Worauf Sie sich verlassen können
Der veröffentlichte Vertrag (ADR-020) enthält genau die Operationen, die Integrationen nutzen dürfen: die
Operationen, die einen API-Schlüssel akzeptieren, und die öffentlichen Abrufe von Pässen (Tag public). Alles
darin ist die API, die diese Dokumentation beschreibt und die API-Referenz auflistet.
Das BatteryPass-Portal nutzt weitere, interne Operationen: Anmeldung, Mitglieder, Verwaltung von API-Schlüsseln, Prüfung, Veröffentlichung, Importe. Sie stehen nicht im veröffentlichten Vertrag, brauchen eine Portalsitzung und können sich mit jedem Release ohne Ankündigung ändern. Bauen Sie nicht darauf auf.
Kompatible Änderungen
Diese Änderungen können mit jedem Release ohne neue Pfadversion kommen:
- neue Operationen;
- neue optionale Query-Parameter und neue optionale Eigenschaften in Request-Bodys;
- neue Eigenschaften in Antworten;
- neue Enum-Werte, zum Beispiel ein neuer Passstatus oder Typ von Lebenszyklusereignis;
- neue Problem-Codes und Codes für Feldfehler;
- eine neue Version des Feldregisters mit neuen Feldern, Bezeichnungen oder Anforderungen (lesbar mit
getRegistryInfo).
Schreiben Sie Ihren Client so, dass ihn das nicht bricht:
- ignorieren Sie unbekannte Eigenschaften in Antworten;
- behandeln Sie unbekannte Enum-Werte mit einem sinnvollen Standard, statt abzubrechen;
- behandeln Sie einen unbekannten Problem-
codenach seinem HTTP-Status; - validieren Sie Antworten nicht streng gegen eine ältere Kopie des Vertrags.
Inkompatible Änderungen
Inkompatibel ist es, eine Operation, einen Parameter oder eine Eigenschaft zu entfernen oder umzubenennen, einen Typ oder eine Bedeutung zu ändern oder optionale Eingaben verpflichtend zu machen. Solche Änderungen an veröffentlichten Operationen kommen nur mit einer neuen Pfadversion und werden im Changelog angekündigt.
Vertrag herunterladen
Der Vertrag ist ein OpenAPI-3.0-Dokument, als JSON und YAML, ohne Authentifizierung abrufbar:
| Adresse | Inhalt |
|---|---|
$BATTERYPASS_URL/api/v1/openapi.json, $BATTERYPASS_URL/api/v1/openapi.yaml | Der Vertrag der BatteryPass-Instanz, die Ihre Organisation nutzt |
/docs/openapi.json, /docs/openapi.yaml | Der Vertrag, den diese Dokumentation beschreibt |
Für Ihre Integration maßgeblich ist der Vertrag Ihrer Instanz: Er passt zu der Version, die Ihre Anfragen beantwortet, und kann älter oder neuer sein als der auf dieser Website. Prüfen Sie seine Version, bevor Sie einen Client erzeugen:
curl -sS "$BATTERYPASS_URL/api/v1/openapi.json" | jq -r '.info.version'Erzeugen Sie typisierte Clients aus dem Vertrag und merken Sie sich die info.version, aus der Sie erzeugt
haben. Ein Vergleich mit der Version der Instanz in Ihrem Monitoring zeigt, wann ein Blick ins Changelog
fällig ist.