Add HTTP header for versioning information

[CasperWA]

Talking with @sygout we think it makes sense to have version information in a header for a client to understand whether it has gotten the newest version (or not) of an entity.

[CasperWA]

Looking around a bit, it seems adding custom headers with a x- prefix is deprecated, see RFC6648.
Looking further around for an existing header that defines the version of the content I came across ETag, but that should only be used if the version of the content changes without the URL/URI changing. So in the case of http://onto-ns.com/meta/SomeEntity is used and does not redirect to the latest entity version URL, then ETag makes sense, but I think I'd rather implement a redirect to the "proper" identity of SomeEntity, i.e., a URL/URI that contains the version, e.g., http://onto-ns.com/meta/2.3/SomeEntity.

The question now is, how should we implement a message for a client to understand that if it requests for example http://onto-ns.com/meta/2.0/SomeEntity, then it is not getting the latest version, but should instead go to http://onto-ns.com/meta/2.3/SomeEntity (if that was the newest version).
As the URL/URI is changed, it does not make sense to use ETag.
And since the x- prefix for custom headers is deprecated, I suggest starting a new header namespace: SOFT-.

So the header here could be, for example, SOFT-Latest-Version. Examples of how it would look could be:

SOFT-Latest-Version: "http://onto-ns.com/meta/2.3/SomeEntity"
SOFT-Latest-Version: "2.3"

I'm not sure whether it should be the version or the URI. One could also have both with two different headers, although that may be overkill? For example a SOFT-Latest-URI header?

[sygout]

Yes it think the SOFT-Latest-URI is more interesting as you might be able to even cover the change in entity name.

[CasperWA]

If there's a change in the entity name, it should be a completely new entity, really. Semantically. But I suppose one could semantically have a deprecation of one entity in favor of another. This is something different than a "simple" version bump of the same entity - but in practice could very well be the exact same thing.

[sygout]

Yes that is what I am thinking as well. So maybe it is a bit twisting the meaning of version and should be avoided. Better to have a deprecated tag and pointing to the newest entity. But that is far in the future.

[CasperWA]

Yes that is what I am thinking as well. So maybe it is a bit twisting the meaning of version and should be avoided. Better to have a deprecated tag and pointing to the newest entity. But that is far in the future.

It doesn't need to be. But for now we could implement it in part by having SOFT-Latest-URI. Then the whole deprecation procedure can come later?

Maybe with the explicit rule that the name part should not change?