Versionierung der Public API
Was in Version 1 der Costfluent Public API stabil bleibt und wie eine Änderung angekündigt wird, bevor sie deine Integration erreicht.
Jeder Pfad der Public API beginnt mit seiner Version: https://api.costfluent.com/v1/.... Version 1 ist die stabile Version, und das OpenAPI-Dokument, das die API-Referenz 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-enumkennzeichnet, etwa eines Provider-Schlüssels. - Neue Ereignistypen eines 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.jsonveröffentlicht, und jede Änderung daran erscheint mit dem Release, das sie ausliefert.