# 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](https://passport.kabin.sh/docs/de/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](https://passport.kabin.sh/docs/de/api-reference) 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`](https://passport.kabin.sh/docs/de/api-reference/registry/get-registry-info)).

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-`code` nach 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](https://passport.kabin.sh/docs/de/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`](https://passport.kabin.sh/docs/openapi.json), [`/docs/openapi.yaml`](https://passport.kabin.sh/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:

```bash title="cURL"
curl -sS "$BATTERYPASS_URL/api/v1/openapi.json" | jq -r '.info.version'
```

> [!TIP]
> 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.