Versioning a public JSON API

API versioning is a policy for managing incompatible contracts. A number in the URL does not explain which changes are safe, how long old clients remain supported or how retirement is communicated.

State the compatibility rules

Document whether clients may ignore new fields, how null and missing differ, whether ordering is meaningful and which error structure remains stable. Treat behavioural changes as carefully as renamed fields.

Choose a visible version boundary

A path or media-type version can both work if routing, documentation and monitoring use it consistently. Keep fixes and additive changes within a version where the published contract allows them.

Operate deprecation

Measure requests by authenticated client and version, publish a retirement date and provide a migration environment. Continue security fixes during the support period and return an explicit response after retirement.