Versioning an API is versioning a promise

Version numbers in a URL suggest that consumers can be moved forward on a schedule. They cannot — a mobile application on a customer’s phone is a client you do not control, and it will keep calling v1 for years.

// additive changes need no version: old clients ignore new fields
{ "id": 91, "total": 4900, "currency": "TRY" }

// these do:
// - removing or renaming a field
// - changing a type ("4900" to 4900)
// - making an optional request field required
// - changing the meaning of an existing value

Most changes are additive if the design allows for it, which is the argument for returning objects rather than bare values and for never using an array where a list of one might grow fields. When a version is genuinely needed, the cost is running both until the old one has no traffic — so instrument it before you need to decide, or the retirement date is guesswork.