Links and versioning

[cmars]

There is a problem with versioned resources that link to each other.

Resource A releases on 2021-09-13. Its responses contain links to resource B, C and D.

On 2021-11-12, resource A gets updated and a new resource E is released. Resource A at 2021-11-12 now links to B, C, D and E in responses.

If I make a request for Resource A at 2021-09-13, that implementation should not provide links to Resource E, because it did not exist at that version.

This is a problem for implementors of resources that provide links. Typically you will want to pass the requested version through in the link URLs in the response. However there may be cases where you now need to know when each linked resource was actually released in order to do so.

Within a single project, this is possibly managed by sharing some implementation logic, or introspecting on the versions. However across services, how does one know if/when something is linkable.

It gets tricky too with stability levels. How can you know when the linked resources are at the same stability? Let's say A goes GA before E does in the example above. Now A needs to know when E is also GA in order to know whether to link to it?

[cmars]

This might be something middleware could handle within the same service -- if links match a locally routed path.

If not, the only place this could be handled is at the edge.

[cmars]

It's pretty difficult to nail down which versions of resources are compatible with other resources, unless these versions are bundled into a distribution release of versions that are all tested together as a whole.

This need supports a case for release cadence automation, where we aggregate all the versioned resources among all the services, and "cut a release" on a regular, say, quarterly cadence.

This maps nicely to the fine-grained, "rolling release" model of API versioning too, we don't really need to change anything except on the front end! We might even use rewrite rules to transform requests, such as:

/2022-07/rest/... => /rest/...?version=2022-07-01

If you use a quarterly release, you know it all "works together". If you use a rolling release of everything, you might have to work out which versions of resources have what you need when following links.