<aside> 📝 Work in Progress: This page is still a very rough draft. This page aims to address common versioning practices and also perhaps propose our own solution, which needs to be carefully refined.

</aside>

Roy Fielding suggests never versioning APIs, and I’m inclined to agree with his original sentiment

In general, you should support older clients and applications for as long as possible. Each organization has its own needs and can take that concept as far as it wants to, but the whole point of REST is to decouple the server as much as possible to make that as practical as possible.

So, for that reason, we need to provide backwards compatibility checking features to make it easy to know and prove when APIs are backwards-compatible.

As described in API Design on the scale of Decades, (p. 23),

Within most public scenarios, an API service is updated by creating an entirely new v2 and slowly deprecating the original v1. Problems with v1 are tracked, [edits] are accumulated and introduced in a v2 that solves these issues, but introduces a complete breaking change with the previous version.

The downsides are

“Long Timeline”: it takes forever to roll out these changes
“Breaking”: It is indeed a breaking change, that causes headaches for everyone downstream
“Communication”: You have to document and communicate this change, which is an additional headache, though I’d argue not much more than the typical documentation everyone should be doing

Recommended Practice

where you can foresee a feature being unavailable, make the link nullable or gate it behind a flag
when an unavailable request is made, send an error message to the client
- make provisions for the client to be able to refresh itself or back out of the current context if that is the cause - maybe we should standardize this in re HTTP Semantics & Error conditions

Parallel versioning

where a data schema must change in a breaking manner, version that entity instead of the entire api - we should have a tool for this!
- maybe individual RCs can be versioned, and links can be versioned too, and there can be “context flags” - when the toolkit reads the RC, it applies its current version to determine which ones to use

Ideas

Maybe headers? A version header could be provided, or maybe something else, perhaps consistent with the spec concept of selected representations.

What even are the use cases