How to versioning the REST API URI address?

Question

I’m looking at ways to view the Uris from a REST Spring API because if they launch a new application, the REST API will meet the new application and support the old application requests for a certain period of time. But I am in doubt of how the database, system entities and Uris in general looks like whenever a version is added to a URI.

Example:

No version, a request to fetch all users:

http://host:8080/api/usuarios

Versioned:

http://host:8080/v1/usuarios

http://host:8080/v2/usuarios

http://host:8080/v1/produtos

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 User v2dto so that it mainly serves the User entity making the validations with the necessary Annotations. For the v1 version of the URI, let’s say that user does not have the attribute 'dataNascimento' and thus he receives a User v1dto that does not have the attribute dataNascimento and when converting the DTO to Entity the attribute Entity.dataNascimento is null because it is not required.

What I want to know is if this is a correct way to use, because in the database the attributes are not mandatory and the validation of the mandatory is in DTO ? I also want to know if all Uris of all features need to be changed to the latest 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

There are several approaches to versioning an API, but one should consider the context of the application that will expose that interface to the client.

Let’s understand the API as a layer completely separate from your application that contains domains in order to facilitate understanding:

1. On the edge A you have your entire application (entity domains, web layer, service layer...)

In this context, you have the application that changes from time to time, including the database, where I believe to be the X of your question.

Let’s apply some concepts to your Urls:

• http://host:8080/api/v1/users
• http://host:8080/api/v2/users

To follow this version of Urls, it is of utmost importance that each response, for each method of your API, is documented and don’t change. To achieve this a good strategy is to use Dtos, they will express the contract of your API (for request and Sponse). For example:

POST http://host:8080/api/v1/users will receive data such as:

{
    "nome": "alberto",
    "sobrenome": "ptr"
}

And will return:

HTTP 200

{
    "usuario": {
        "id": "YA1skAAOISm12"
        "nome": "alberto",
        "sobrenome": "ptr"
    },
    "links": {
        "_self": {
            "href": "http://host:8080/api/v1/usuarios/YA1skAAOISm12"
        }
    }
}

If you use the entity itself, there will be cases where a bank column may cease to exist, and that way your contract will be changed at each bank change.

Using Dtos, the API v1 will necessarily return this data, when you implement v2, usually it will bring additional data compared to v1, the request or return structure may or may not be completely different, and with very low coupling with your legacy.

If, for example, a fundamental fact of your API is changed in the database, and you cannot adjust the call in order to maintain the agreement, the version of the API should then be depreciated, and users should be guided to upgrade to the new version available.

---

Another interesting alternative if you want to keep the same URL independent of the version of your API is to move the property indicating the version to be accessed to a field in header of your request.

Companies such as Stripe and Juno use this strategy to keep Urls fixed, varying the header version as the API evolves. This way if the client wants to use an X or Y resource that is in a more updated version, just change the header and the request will be routed to the new resource.

---

Such managements become easier with the adoption of a API Gateway that processes the calls, and can route the requests to the desired resource using some strategy as mentioned

---

It is important to have the view that, there may be N clients using your API, and so it is utmost importance this layer be isolated, and with few structural changes in the body of responses or requests. Otherwise you will be breaking the applications using your service.