Versionierung
Wie sich die Schnittstelle verändert, ohne deine Integration zu brechen.
Hauptversion im Pfad
Die Hauptversion steht in der Adresse, zum Beispiel https://api.hfoods.de/v1/.... Innerhalb einer
Hauptversion ändern wir nichts, was eine bestehende Integration bricht.
Was sich innerhalb einer Hauptversion ändern darf
Diese Änderungen können jederzeit kommen. Baue deine Integration so, dass sie damit umgehen kann:
- neue Endpunkte
- neue, optionale Felder in Anfragen
- neue Felder in Antworten
- neue Werte in Aufzählungen, die ausdrücklich als erweiterbar beschrieben sind
- neue Ereignistypen bei Webhooks, die du erst abonnieren musst
- geänderte Texte in Fehlermeldungen (die Fehlercodes bleiben gleich)
Was nie ohne neue Hauptversion passiert
- einen Endpunkt oder ein Feld entfernen oder umbenennen
- den Typ oder die Bedeutung eines Feldes ändern
- ein optionales Feld zur Pflicht machen
- einen Fehlercode ändern
- die Authentifizierung ändern
Jede Änderung am Vertrag wird vor der Auslieferung automatisch auf solche Brüche geprüft.
Abkündigung
Ersetzen wir einen Endpunkt, markieren wir ihn in der Referenz als veraltet und nennen das Datum
der Abschaltung. Zwischen Ankündigung und Abschaltung liegen mindestens sechs Monate. Antworten
veralteter Endpunkte tragen die Header Deprecation und Sunset, damit du es auch in deinen Logs
siehst. Eine neue Hauptversion läuft mindestens zwölf Monate parallel zur alten.
Reifegrade
| Reifegrad | Bedeutung |
|---|---|
| Entwurf | Nur zur Abstimmung. Alles kann sich ändern, nichts ist in Betrieb. |
| Vorschau | Nutzbar im Testbetrieb. Brüche sind noch möglich und stehen im Changelog. |
| Stabil | Freigegeben. Es gelten alle Zusagen auf dieser Seite. |
| Abgekündigt | Läuft bis zum genannten Datum weiter, bekommt aber nichts Neues mehr. |