These are notes summarizing my research into how to version a RESTful API. These notes do not represent actual experience. They’re just me remembering links I found useful.
Restful API
Cribbed from Your API versioning is wrong… by Troy Hunt.
There are three ways to version a RESTful API:
- Something in the URI (“…/api/v2/…”)
- Something in the request header (“api-version: 2”)
- Something in the Accept header (“Accept: application/apiname.v2+json”)
Troy does them all at the same time. His framework makes it easy.
Semantic versioning
RESTful routes use semantic versioning, but only the major version number is used because only breaking API changes matter. Adding a route never hurt anyone. Deleting one, or changing one’s meaning, does.