# Versionierung der Public API

Jeder Pfad der Public API beginnt mit seiner Version: `https://api.costfluent.com/v1/...`. Version 1 ist die stabile Version, und das [OpenAPI-Dokument](/openapi/public.v1.json), das die [API-Referenz](/api) darstellt, ist ihr Vertrag.

## Was sich in Version 1 ändern kann

Version 1 ändert sich nur durch Ergänzungen:

- Neue Operationen und neue Pfade.
- Neue optionale Anfragefelder und Query-Parameter.
- Neue Felder in einer Antwort, auch in einem Fehler-Body.
- Neue Werte eines Felds, das der Vertrag als `x-extensible-enum` kennzeichnet, etwa eines Provider-Schlüssels.
- Neue Ereignistypen eines [Webhooks](/de/api/webhooks).

Schreibe deine Integration so, dass sie unbekannte Antwortfelder ignoriert und unbekannte Werte eines erweiterbaren Enums akzeptiert, damit eine Ergänzung sie nie bricht.

## Wie eine Entfernung angekündigt wird

Etwas zu entfernen oder zu ändern, das Version 1 bereits zurückgibt, ist eine inkompatible Änderung. Davor antworten die betroffenen Operationen mit einem `Deprecation`-Header und einem `Sunset`-Header, der das Datum nennt, an dem die Änderung wirksam wird, mindestens sechs Monate im Voraus. Eine inkompatible Änderung erscheint als neue Version, `v2`, während Version 1 bis zu ihrem Sunset-Datum weiter antwortet.

## Wie es sich verhält

- Die Version ist Teil des Pfads, nie ein Header oder Query-Parameter.
- Das OpenAPI-Dokument ist in diesem Portal unter `/openapi/public.v1.json` veröffentlicht, und jede Änderung daran erscheint mit dem Release, das sie ausliefert.

## Verwandte Seiten

- [API-Referenz](/api)
- [Datenformate](/de/api/formats)
- [Fehler](/de/api/errors)