Schnittstellen versionieren: wie man ändert, ohne zu brechen
Was als brechende Änderung gilt
Ein Feld oder eine Route entfernen, einen Typ ändern, ein optionales Feld zur Pflicht machen, die Bedeutung eines bestehenden Werts ändern und Grenzen verschärfen. Ein optionales Feld hinzuzufügen bricht nicht — solange Verbraucher unbekannte Felder ignorieren, eine Regel, die zu dokumentieren sich lohnt.
Wie man einen Übergang steuert
Betreiben Sie die neue Version neben der alten, messen Sie, wer die alte noch nutzt, und schalten sie erst ab, nachdem die Nutzung null erreicht oder Sie genügend Hinweis gegeben haben.
Wenige Versionen mit bedeutsamem Inhalt schlagen eine Version je kleiner Änderung. Jede lebende Version ist Code zum Pflegen und Testen.
Stufenweise außer Dienst stellen
Markieren Sie Felder und Routen in der Doku und einem Antwort-Header als zur Entfernung vorgesehen, mit einem Datum. Senden Sie aktiven Verbrauchern einen Hinweis. Und schließlich, vor dem Abschalten — führen Sie eine „kontrollierte Dunkelheit“ durch: Schalten Sie für einige Minuten ab und sehen Sie, wer schreit.
Im Detail
Halten Sie Kennzahlen nach Version und Verbraucher, nicht nur nach Route. Ohne sie ist das Abschalten einer alten Version ein Glücksspiel, und wer geschädigt wird, entdeckt es in seiner Produktion — also in einem dringenden Anruf, der Sie erreicht.