API Versioning

1. The Pattern

A published API cannot be taken back. Clients you cannot see, cannot update, and cannot schedule have built on every field you ever shipped. So evolution runs on three disciplines: change additively whenever possible, version explicitly when you cannot, and retire old versions as a managed lifecycle.

The incident is the module intro's third question, answered badly. The team renames order.state to order.status. It is a good rename, because the old name was genuinely confusing. They ship it. Within the hour, 200 partner integrations throw parse errors