Lesson 2.12.2 ended with a table: what in the contract breaks a caller? A renamed property is on it. That is exactly the kind of change the office wants now: since K1 the Kladde has stored a contact with one name, “Ilse Kranich”. For letters, for sorting by last name and for the salutation, the office needs first and last names apart. But whoever uses the contacts API today reads name. In this lesson you build a version 2 of the contacts API in which the name is split, while version 1 keeps running unchanged and announces its end in good time.

What breaks and what does not

The rule of thumb from lesson 2.12.2, once more in short: adding rarely breaks, removing and renaming always do.

  • New fields in responses: yes. A caller reads what it knows and ignores the rest. JSON in .NET does that by itself.
  • New optional fields in requests: yes. Old callers don't send them, and the server doesn't need them.
  • Renaming: no. name becomes lastName, and everyone who reads name reads nothing anymore.
  • Making something required: no. What was optional yesterday is missing from the requests of all old callers.
  • Only extend enumerations, and only in requests without worry. In responses a new value hits a caller that handles all the known values with a switch and doesn't know the new one. So: callers always handle unknown values with a default case, and the server announces new values.

Most of the time a change can be built so that it doesn't break: a new field beside the old one instead of a renamed one. For the names that would mean: name stays, firstName and lastName come in addition. That works, but in the long run it is a nuisance, because the same information now exists twice, and someone has to decide what counts when a caller changes name and not lastName. If the shape is really supposed to become a different one, a new version is more honest.