Am Ende von Lektion 2.12.2 stand eine Tabelle: Was im Vertrag bricht einen Aufrufer? Eine umbenannte Eigenschaft gehört dazu. Genau so eine Änderung wünscht sich das Büro jetzt: Die Kladde speichert seit K1 einen Kontakt mit einem Namen, „Ilse Kranich“. Für Briefe, für die Sortierung nach Nachnamen und für die Anrede braucht das Büro Vor- und Nachnamen getrennt. Wer die Kontakte-API heute benutzt, liest aber name. In dieser Lektion bauen Sie eine Version 2 der Kontakte-API, in der der Name aufgeteilt ist, während Version 1 unverändert weiterläuft und ihr Ende rechtzeitig ankündigt.

Was bricht und was nicht

Die Faustregel aus Lektion 2.12.2, noch einmal kurz: Hinzufügen bricht selten, Wegnehmen und Umbenennen immer.

  • Neue Felder in Antworten: ja. Ein Aufrufer liest, was er kennt, und übergeht den Rest. JSON in .NET macht das von selbst.
  • Neue freiwillige Felder in Anfragen: ja. Alte Aufrufer schicken sie nicht, und der Server braucht sie nicht.
  • Umbenennen: nein. name wird zu lastName, und jeder, der name liest, liest nichts mehr.
  • Pflicht machen: nein. Was gestern freiwillig war, fehlt in den Anfragen aller alten Aufrufer.
  • Aufzählungen nur erweitern, und das nur in Anfragen sorglos. In Antworten trifft ein neuer Wert einen Aufrufer, der mit switch alle bekannten Werte behandelt und den neuen nicht kennt. Darum: Aufrufer behandeln unbekannte Werte immer mit einem Standardfall, und der Server kündigt neue Werte an.

Meist lässt sich eine Änderung so bauen, dass sie nicht bricht: ein neues Feld daneben statt eines umbenannten. Für die Namen hieße das: name bleibt, firstName und lastName kommen dazu. Das geht, ist aber auf Dauer ein Ärgernis, denn dann gibt es dieselbe Information zweimal, und jemand muss entscheiden, was gilt, wenn ein Aufrufer name ändert und lastName nicht. Wenn die Form wirklich eine andere werden soll, ist eine neue Version ehrlicher.