API Versioning

The Pattern

Published APIs are a one-way door: clients you can't see, can't update, and can't schedule have built on every field you ever shipped. Evolution therefore runs on three disciplines: change additively whenever possible, version explicitly when you can't, and retire old versions as a managed lifecycle: last year's tax forms stay valid while this year's roll out.

The incident is the module intro's third question, answered badly: the team renames order.state to order.status: a good rename, the old name was genuinely confusing: and ships it