Versionierung
API v1 ist seit dem Start eingefroren. Code, der dafür geschrieben wurde, funktioniert weiter: Die API erhält neue Endpunkte und Felder und verliert nichts.
Was sich in v1 ändern darf
- Neue Endpunkte sowie neue optionale Felder und Optionen in Anfragen, standardmäßig ausgeschaltet.
- Neue Felder in Antworten und in Webhook-Ereignissen. Ignorieren Sie Felder, die Sie nicht kennen.
- Neue Fehlercodes, nur für neue Funktionen; eine bestehende Anfrage erhält nie einen neuen Code aus einem alten Grund.
- Neue Typen von Webhook-Ereignissen, die nur an Endpunkte gesendet werden, die sie anfordern.
- Fehlermeldungen, die für Menschen gedacht sind: Verzweigen Sie anhand des Codes, nie anhand der Meldung.
- Höhere Limits, mehr Formate, schnellere Antworten.
Was sich in v1 nie ändert
- Pfad und Methode eines Endpunkts oder die Bedeutung seiner Felder und Antworten.
- Name oder Typ eines Felds, ein Standardwert oder Status und Bedeutung eines Fehlercodes.
- Was als eine Markierung zählt, wie es die Preisseite angibt, ohne Ankündigung gegenüber bestehenden Kunden.
- Das Signaturschema der Webhooks (Kennmarq-Signature) und die Formate des Transparenzprotokolls.
Eine inkompatible Änderung
Sie käme als v2, unter eigenen Pfaden, mindestens 12 Monate im Voraus im Änderungsprotokoll und per E-Mail an die Inhaber jeder Organisation angekündigt. v1 antwortet mindestens diese 12 Monate lang weiter. Die einzige Ausnahme ist die Behebung eines Sicherheitsproblems: Ist eine Anfrage so, wie sie ist, unsicher, ändern wir sie sofort und vermerken das im Änderungsprotokoll.
OpenAPI
Ein OpenAPI-3.1-Dokument beschreibt v1, abrufbar unter https://api.kennmarq.com/v1/openapi.json, für Client-Generatoren und API-Tools. Es führt jeden Endpunkt, jedes Feld und jeden Fehlercode auf, die auch diese Referenz nennt.