API versioning

1 min read
On trails:ASPNETAPIstep 3/4

As APIs evolve, breaking changes may be necessary. A versioning strategy is essential so that clients can keep using older versions while new versions are introduced. Common strategies:

Strategy Example Notes
URL versioning /api/v1/products, /api/v2/products Simple and explicit.
Query string versioning /api/products?api-version=1.0
Custom header versioning X-API-Version: 1.0 or Accept-Version: 1.0
Media type versioning (content negotiation) Accept: application/vnd.mycompany.product.v1+json

The choice of versioning strategy has implications for routing, caching and client usability. A clear strategy should be established early.

The rest of the API design checklist is in the RESTful design noteRESTful API designNaming, methods, status codes, formats and security for an API that is easy to use.Opens in a new tab.

Sources