Should location returned by HTTP header have version information?

Is there a standard or convention on whether location retuned by a REST server should also include the version information? Per REST, the URI is to a resource so by that definition, the URI returned in the Location header should not have a version.

But a GET on the location returned by the server is supposed to work, but it fails if version information is not added to the URI. Is the client supposed to know the preferred version of the server, especially when there may be API gateways that aggregate multiple backend microservices that are on different API versions?

Is there a standard on this, should or shouldn't the server return the API version in the response?


There is no standard when it comes to versioning and REST. REST is a system of constraints. There are, however, methods of versioning that adhere to the constraints and those that do not (such as in the URL path).

An API version should not be thought of in the same way as a version for binaries. While "API version" is a widely accepted term, it's a bit of a misnomer. An API version doesn't indicate which method to call for an API, it indicates the format. Remember that HTTP is the API. HTTP does not have method overloads or versions. What's behind that is an implementation detail.

This means that a media type best describes and serves the purpose of an API version, even if there are other ways to convey it. The server's job is to tell you where a resource is located via Location when you create a resource with a server-generated identifier. It is not obligated to tell you what format you (the client) want it in. Since you just created a resource specifying a specific API version (or format), you should know how to send a GET to retrieve that resource.

The same rules and logic apply for HATEOAS. If the server provides the location of related resources, it cannot know what API version (or format) of those resources that you - the client - want. The independent evolution of services often results in heterogenous versions across APIs.

Exactly how these concepts can be applied to microservices is a bit off-topic, but it is entirely possible that one service writes a resource in a v1 format, while another service reads the resource in a v2 or v3 format. Regardless, the Location of the resource should be the same and is shareable across service boundaries.