Changelog
Was sich an der SIDES LABS API geändert hat
Die API ist ein Vertrag. Ein Feld, einen Endpunkt oder einen Aufzählungswert zu ergänzen, finden Sie hier; eines zu entfernen, umzubenennen oder umzutypisieren braucht eine neue Hauptversion und sechs Monate Vorlauf. Auf dieser Seite wird beides festgehalten, in der Reihenfolge der Veröffentlichung.
Die Einträge
Veröffentlichte Änderungen, neueste zuerst
Dargestellt aus GET /v1/publication/public/changelog-entries. Ein Eintrag erscheint hier erst, wenn SIDES ihn veröffentlicht hat — eine Pipeline, die einen einliefert, legt einen Entwurf an, und ein Entwurf ist kein Changelog.
Noch keine Einträge
Bisher wurde nichts in das öffentliche Changelog veröffentlicht. Jedes Release schreibt einen Eintrag — mit dem ersten füllt sich diese Liste.
Wie man einen Eintrag liest
Sechs Arten, und nur zwei verlangen etwas von Ihnen
Jeder Eintrag trägt eine davon. Sie sind keine Schweregrade und nicht geordnet — sie sagen, was geschehen ist, und zwei von ihnen bedeuten, dass es ein Datum gibt, das Sie kennen sollten.
- Ergänzt
- Ein neuer Endpunkt, ein neues Feld, ein neuer Aufzählungswert oder eine neue Kopfzeile. Nichts, was Sie bereits senden oder auswerten, ändert sich. Ein Client, der unbekannte Felder ignoriert — worum der Vertrag jeden Client bittet — braucht überhaupt keine Arbeit.
- Geändert
- Verhalten, das sich verschoben hat, ohne den Vertrag zu brechen: ein Standardwert, eine Grenze, eine Reihenfolge, eine Fehlermeldung. Die Form ist dieselbe; was zurückkommt, vielleicht nicht.
- Abgekündigt
-
Noch da, noch funktionsfähig, und angekündigt. Ein Abkündigungseintrag trägt ein
Abschaltdatum und die API sendet dasselbe Datum in der
X-SIDES-Deprecation-Kopfzeile bei jeder Antwort des betroffenen Endpunkts. Das ist der Eintrag, auf den zu handeln ist, und Sie haben mindestens sechs Monate. - Entfernt
- Weg, und immer nur in einer neuen Hauptversion. Aus einer geltenden Version wird nichts entfernt — genau das bedeutet „die API ist ein Vertrag“ in der Praxis.
- Behoben
- Die API tat nicht, was diese Spezifikation von ihr behauptete, und jetzt tut sie es. Haben Sie das alte Verhalten umgangen, ist dies der Eintrag, der Ihnen sagt, dass die Umgehung weg kann.
- Sicherheit
- Eine sicherheitsrelevante Änderung. Sie wird veröffentlicht, sobald sie ausgeliefert ist, nie vorher, und sie nennt die Klasse des geschlossenen Problems, ohne jemandem ein Rezept zur Nachstellung zu geben.
Fragen
Bevor Sie uns fragen
Steht hier alles, oder nur, was SIDES erwähnen wollte?
Jede Veröffentlichung schreibt einen Eintrag — das ist eine Regel im Auslieferungsstandard und keine Gewohnheit. Was diese Seite nicht zeigt, sind Einträge, deren Zielgruppe partner ist statt des offenen Internets: Die erreichen einen angemeldeten Partner und stehen nie in diesem Feed. Die Unterscheidung gehört dem Eintrag und nicht dem Leser, und nichts, was Sie an diesen Endpunkt senden können, ändert sie.
Bekomme ich das auch ohne Browser?
Ja. Dieselben Einträge gibt es als Atom-1.0-Feed, mit denselben Filtern wie auf dieser Seite, und jede Eintragskennung bleibt über einen Rückzug und eine erneute Veröffentlichung stabil — ein Leser, der Ihnen einen Eintrag schon gezeigt hat, zeigt ihn also nicht erneut, weil SIDES einen Tippfehler korrigiert hat. Der Feed liegt hier unter /changelog.atom; dieselben Einträge gibt es als
GET /v1/publication/public/changelog-entries als JSON auf der API, wofür der Scope storefront nötig ist — jeder registrierte Client darf ihn anfordern und bekommt ihn.
Warum listet ein Eintrag Endpunkte auf?
Damit Sie in einer Zeile erkennen, ob eine Änderung Sie angeht. Ein Eintrag nennt die betroffene API, die Version, in der er veröffentlicht wurde, und die berührten Endpunkte, so geschrieben, wie diese Spezifikation sie schreibt — Platzhaltersegmente eingeschlossen. Eine Änderung an einem Endpunkt, den Sie nicht aufrufen, ist eine Änderung, die Sie überspringen können.
Meine Pipeline möchte eigene Einträge einliefern. Geht das?
Dafür ist die Einlieferungs-API da:
POST /v1/publication/changelog-entries unter
publication.changelog:write, idempotent über Ihre eigene Referenz, sodass ein erneuter Lauf keinen zweiten Eintrag anlegt. Er legt einen Entwurf an; die Veröffentlichung bleibt ein bewusster Akt. Der Tarif Ihrer Partnerschaft sagt, ob die Fähigkeit enthalten ist.
Bauen Sie gegen einen Vertrag mit Vorankündigung
Keine brechende Änderung ohne neue Hauptversion und sechs Monate Vorlauf, jede Abkündigung sowohl in der Antwortkopfzeile als auch auf dieser Seite datiert, und eine Einlieferungs-API, damit auch Ihre eigenen Veröffentlichungen hier erscheinen können.
