GunSpec
Versionierung

Versionierung

Was die Version im Pfad verspricht, was wir ändern, ohne sie anzufassen, wie ein Breaking Change ausgeliefert wird, und der eine enge Fall, in dem die aktuelle Version stattdessen an Ort und Stelle korrigiert wird. Präfix, Version und die Zahlen der Richtlinie werden aus der Konfiguration der API gelesen.

  • /v1Pfadpräfix
  • 1.1.0Spec-Version
  • 133Operationen darunter
  • 0Veraltete Operationen

So funktionieren Versionen

Jeder Endpunkt liegt unter /v1. Dieses Präfix ist der Vertrag: solange es antwortet, funktioniert eine Anfrage, die funktioniert hat, weiterhin. info.version im OpenAPI-Dokument (1.1.0) sagt, welche Ausgabe dieses Vertrags live ist, und seine Hauptnummer ist das Präfix.

Zwei Stellen, an denen eine Version erscheint
bash
# The prefix is the contractcurl -H "X-API-Key: your_api_key" https://api.gunspec.io/v1/firearms/glock-17-gen5 # The document says which release of that contract is livecurl https://api.gunspec.io/openapi.json | jq .info.version# "1.1.0"
1Major: das Präfix
Bewegt sich nur bei einem Breaking Change, und dann bewegt sich der Pfad mit: /v1 wird /v2. Nichts unter dem alten Präfix ändert an diesem Tag seine Form.
1Minor: additiv
Bewegt sich, wenn etwas hinzukommt: ein Endpunkt, ein Feld, ein Parameter, ein Enum-Wert, ein Ereignis. Ein Client, der Unbekanntes ignoriert, merkt keinen Unterschied.
0Patch: Korrekturen
Bewegt sich für eine Korrektur, die keine Form ändert: eine falsche Beschreibung, eine abweichende Zahl, eine Validierung, die lockerer war als dokumentiert.

2 Pfade liegen außerhalb des Präfixes, weil sie den Dienst beschreiben und nicht die Daten, und sind absichtlich stabil: /health, /ready. Das Feld version auf einem Katalogeintrag hat damit nichts zu tun: es ist ein Fingerabdruck der Daten dieses Eintrags für Caching und Spiegelung, beschrieben unter Datenrevisionen und in der Feldreferenz, und ändert sich, wenn sich der Eintrag ändert, nicht wenn sich die API ändert.

Was sich ohne neue Version ändert

Additive Änderungen landen unter /v1, sobald sie fertig sind, mit einer Minor-Erhöhung von info.version und einem Changelog-Eintrag. Ein Client, der nach den Regeln unten geschrieben ist, bemerkt sie nie.

  • Neue Endpunkte und neue optionale Query-Parameter auf bestehenden. Ein unbekannter Parameter wird ignoriert, nie abgelehnt.
  • Neue Felder in einer Antwort. Sie kommen neben denen an, die Sie lesen; nichts, was Sie lesen, verschiebt sich oder ändert den Typ.
  • Neue Werte in einem geschlossenen Vokabular. Ein Eintrag kann einen Status, einen Verschlusstyp oder einen Ereignisnamen tragen, den es beim Schreiben Ihres Codes nicht gab.
  • Neue error.reason-Werte unter einem bestehenden error.code. Der Code ist die Familie, auf die Ihr Code verzweigt; der Grund ist die konkrete Situation, und die Liste wächst.
  • Mehr Daten. Einträge bekommen Felder, die null waren, Zähler steigen, Listen werden länger. Eine Zahl, die von null zu einem Wert wird, ist keine Formänderung.

Vokabulare, die wachsen

  • firearm.statusheute 6

    Der Produktionsstatus eines Eintrags. Behandeln Sie die Werte, die Sie kennen, und den Rest als unbekannt, nie als Fehler.

    • in_production
    • discontinued
    • out_of_production
    • alle 6
  • firearm.actionTypeheute 46

    Der Mechanismus einer Waffe. Das längste der vier Vokabulare und das am häufigsten erschöpfend abgefragte.

    • short_recoil
    • bolt_action
    • blowback
    • alle 46
  • X-Webhook-Eventheute 18

    Worum es bei einer Zustellung geht. Wer einen Wildcard abonniert, erhält neue Ereignisnamen, sobald sie ausgeliefert werden.

    • firearm.created
    • firearm.updated
    • firearm.deleted
    • alle 18
  • error.reasonheute 39

    Warum eine Anfrage abgelehnt wurde, eine Ebene unter dem Status. Erst auf den Code verzweigen, dann auf die Gründe, auf die Sie reagieren können.

    • INVALID_PARAMETER
    • INVALID_JSON
    • INVALID_REQUEST
    • alle 39

Was als Breaking gilt

Ein Breaking Change lässt eine Anfrage, die funktioniert hat, scheitern oder liefert etwas, das ein korrekter Client falsch liest. Er wird unter einem neuen Präfix ausgeliefert; /v1 antwortet weiter wie zuvor.

  • Entfernen oder Umbenennen eines Feldes, Endpunkts, Parameters oder Vokabularwerts.
  • Ändern des Typs oder der Einheit eines Feldes oder der Bedeutung eines bestehenden Werts.
  • Verschärfen der Validierung, sodass eine bisher akzeptierte Anfrage abgelehnt wird.
  • Ändern des Statuscodes, Fehlercodes oder Tarifs, mit dem eine Anfrage beantwortet wird.
  • Ändern der Hülle, der Authentifizierungs-Header oder des Paginierungsvertrags.

Der Standardweg

  1. 1Die Änderung wird vor der Auslieferung als breaking-Eintrag im Changelog abgelegt, mit dem, was sich bewegt und warum.
  2. 2Der neue Vertrag geht unter /v2 live. Die Major-Version der Spec bewegt sich mit, und die SDKs erhalten ein Release dafür.
  3. 3/v1 antwortet ab diesem Tag mindestens 12 Monate unverändert weiter. Die Operationen, die es verlieren wird, sind in der Spec als deprecated markiert, was Referenz und SDKs anzeigen.
  4. 4Wenn das alte Präfix abgeschaltet wird, wird das Datum mindestens 12 Monate vorher im Changelog angekündigt, und jeder Schlüssel, der es im Nutzungsfenster aufgerufen hat, wird direkt kontaktiert.

Die Ausnahme: v1 an Ort und Stelle korrigieren

Ein neues Präfix ist die richtige Antwort auf eine Meinungsänderung. Für einen Defekt ist es die falsche: /v1 12 Monate lang falsch zu lassen, damit niemandes Code sich ändert, dient den wenigen Aufrufern, die auf die falsche Antwort angewiesen sind, und schadet allen anderen. Wo die Nutzungslogs zeigen, dass die betroffene Oberfläche fast keine Konsumenten hat, darf die Korrektur stattdessen im aktuellen Präfix landen. Die Bedingungen sind eng, und alle müssen gelten.

Wann es erlaubt ist

  • Das aktuelle Verhalten ist gegenüber der eigenen Dokumentation falsch, nicht nur unbequem: eine Zahl in der falschen Einheit, ein Status, der lügt, eine Validierung, die durchlässt, was die Spec verbietet.
  • Die Nutzungslogs der letzten 90 Tage zeigen, dass der betroffene Endpunkt, das Feld oder der Wert von fast niemandem konsumiert wird, und jeder Schlüssel, der es aufgerufen hat, direkt kontaktiert werden kann.
  • Das korrigierte Verhalten ist das, was ein Leser der Dokumentation ohnehin erwartet, sodass ein nach der Doku geschriebener Client danach besser funktioniert, nicht schlechter.
  • Es ist eine Korrektur, keine Funktion: nichts Neues kommt hinzu, und die Änderung ist die kleinste, die das Verhalten wahr macht.

Wann nicht

  • Jeder Endpunkt, den die SDKs, die Website oder ein veröffentlichtes Integrationspaket in einem dokumentierten Ablauf aufrufen.
  • Jede Änderung von Name, Typ oder Einheit eines Feldes auf einem Eintrag: ein Spiegel mit der alten Form kann einen korrigierten Wert nicht von einem geänderten unterscheiden.
  • Jede Änderung an Authentifizierung, Hülle, Fehlervertrag oder Paginierung.
  • Alles, worüber ein Konsument überrascht statt erleichtert wäre.

So wird es ausgeliefert

  1. 1Ein breaking-Eintrag landet mindestens 30 Tage vor Inkrafttreten im Changelog und im Feed und nennt Endpunkt, altes Verhalten, neues Verhalten und Datum.
  2. 2Jeder Schlüssel, der die betroffene Oberfläche in den letzten 90 Tagen aufgerufen hat, erhält dieselbe Mitteilung per E-Mail, sodass niemand davon durch eine fehlschlagende Anfrage erfährt.
  3. 3Die Änderung landet am angekündigten Datum mit einem Patch an info.version und einem passenden SDK-Release; der Changelog-Eintrag wird aktualisiert, dass sie ausgeliefert ist.
  4. 4Wo ein Aufrufer nicht rechtzeitig umstellen kann, wird das alte Verhalten für ihn hinter einer Ausnahme pro Schlüssel beibehalten, bis er kann. Eine angekündigte Korrektur bricht nie einen Kunden, der um mehr Zeit gebeten hat.

Bisher veröffentlichte Breaking-Einträge (1)

Veraltete Operationen

Eine auslaufende Operation ist im OpenAPI-Dokument als deprecated markiert, was generierte Clients und die Referenz anzeigen. Sie antwortet weiter bis zum Abschaltdatum, das ihr Changelog-Eintrag nennt.

In 1.1.0 ist nichts veraltet. Jede dokumentierte Operation ist aktuell.

Wo man hinschaut

Vier Orte, an denen eine Änderung angekündigt wird. Einem zu folgen genügt; ein Breaking Change erscheint an allen.

Das Changelog

Jede Änderung, nach Kategorie abgelegt. Nach breaking filtern, um nur das zu sehen, was Ihre Aufmerksamkeit braucht.

Der Feed

https://api.gunspec.io/changelog.xml trägt dieselben Einträge im Moment der Veröffentlichung, für einen Feedreader oder einen CI-Job, der bei einem neuen Breaking-Eintrag den Build fehlschlagen lässt.

Das OpenAPI-Dokument

https://api.gunspec.io/openapi.json trägt info.version und jede deprecated-Markierung. Es in CI gegen die Kopie zu diffen, aus der Sie gebaut haben, ist die mechanische Prüfung; siehe Werkzeuge für die Postman- und Swagger-Wege dorthin.

SDK-Releases

Ein neues Präfix ist ein Major-Release der SDKs, eine additive Änderung ein Minor-Release, sodass das Festpinnen der SDK-Major-Version auch die API-Version festpinnt.

Changelog öffnenFeed abonnieren

Einen Client schreiben, der überlebt

Fünf Gewohnheiten, die jede kompatible Änderung unsichtbar und jeden Breaking Change zu einem geplanten Upgrade machen.

  • Das Präfix festpinnen. /v1 in die Basis-URL bauen, nie in eine Einstellung, die ein Deploy versehentlich ändern kann.
  • Unbekanntes ignorieren. Unbekannte Felder, Parameter, Vokabularwerte und error.reason-Werte sind normal; als abwesend behandeln, nicht als Fehler.
  • Auf error.code verzweigen, dann auf die Gründe, auf die Sie reagieren können. Die Fehlerreferenz listet beide.
  • Von der erhaltenen Seite aus blättern, nicht von einer Gesamtzahl, die Sie vielleicht nicht haben. Die Paginierungsseite hat die Schleife.
  • Wo möglich ein SDK nutzen. Seine Major-Version folgt dem Präfix, seine Typen der Spec, und Auto-Paging und Retry folgen diesen Regeln bereits.