How to do versioning in the REST API URI address?

Question

I'm looking at ways to version the URIs of a Spring REST API because, in the case of launching a new application, the REST API handles the new application and supports the old application requests for a certain period. But I am in doubt as to what database, system entities, and URIs are in general whenever a version is added to a URI.

Example:

No version, a request to fetch all users:

http://host:8080/api/users

With versioning:

http://host:8080/v1/users

http://host:8080/v2/users

http://host:8080/v1/products

I was thinking of making a User entity and when defining the attributes I note them as not mandatory and the entity is always the most current version. For the 'v2' version of the URI I create a UserV2DTO so that it primarily serves the User entity doing the validations with the required annotations. For the 'v1' version of the URI, let's say that the user does not have the 'dateBirth' attribute and in this way it receives a UserV1DTO that does not have the dateBirth attribute and at the time of converting the DTO to Entity the Entity.dateBirth attribute is null because is required.

What I want to know is if this is a correct form of versioning, because in the database the attributes are not mandatory and the validation of the mandatory is in the DTO? Also I want to know if all the URIs of all the resources need to be changed to the last version or if in the case of 'products' it can stay in V1 until one day it is necessary to change only it?

Answer 1

How to do versioning in the REST API URI address?

Real answer? Any way you want, consistent with your local conventions.

In REST, URI are just identifiers; effectively they are keys used to look up information in a cache. Embedding information in the URI is done at the discretion of the server, and for its own exclusive use.

Roy Fielding, who defined REST while leading the specification work for HTTP/1.1, wrote

The reason to make a real REST API is to get evolvability … a "v1" is a middle finger to your API customers, indicating RPC/HTTP (not REST)

As an example, consider Google -- how many different implementations of web search do you suppose that they have had, over the years? But the API itself has been stable: navigate to the bookmarked home page, enter data in the search form, submit -- dispatching the data to whatever URI was described in the form meta data.

Of course, even if you aren't doing REST, you might still want a URI design that is sane. Using path segments to partition your resource hierarchy has advantages when it comes to relative URI, because you can then use dot-segments to produce other identifiers in the hierarchy.

/v1/users + ../products -> /v1/products

Your life down the road will likely be considerably easier if you are clear as to whether you really have a new resource in each version, or a shared resource with different representations. If someone changes /v2/users, should that also change /v1/users? What are the correct cache invalidation semantics?