A breaking change — a renamed field, a removed endpoint, a different error shape — would fail every client built against the old behaviour. Versioning lets the provider ship the new behaviour as a new version while the old one keeps working, and gives clients a period in which to migrate.
The version is usually carried in the URL path (/v1/, /v2/), sometimes in a header or the Accept media type, occasionally as a date. Non-breaking changes — new optional fields, new endpoints — ship within a version. When an old version is retired, the provider announces it in advance, often with Deprecation and Sunset headers on its responses.
That adding a field is always safe. It is for clients that ignore unknown fields, and breaks those with strict deserialisers or snapshot tests. What counts as "breaking" depends on what clients actually do, which is why providers publish their compatibility rules.
The Friends API runs both versions: GET /friends/v1/characters is marked deprecated, and GET /friends/v2/characters renames job to occupation and re-wraps the list; GET /friends/version lists what is supported.
All glossary terms · Testing techniques · All 39 mock REST APIs
Last updated