Why versioning matters

APIs are contracts. Once a client depends on a field name or response shape, changing it silently breaks them. Versioning makes change explicit and controlled.

URL path versioning

GET /v1/orders
GET /v2/orders

Most common, most visible. Easy to test in a browser, easy to route at the load balancer, easy to document separately. Our default recommendation.

Header versioning

GET /orders
Accept: application/vnd.myapi.v2+json

Keeps URLs clean. Harder to test ad-hoc, not cacheable by default CDNs, easy to forget in client code.

Query parameter versioning

GET /orders?version=2

Simple but pollutes every URL. Versioning semantics mixed with query semantics. Avoid for new APIs.

Deprecation policy

Support at minimum two major versions simultaneously. Add a Sunset header to deprecated endpoints with the retirement date. Log usage of deprecated endpoints to know when it is safe to remove them.