3

Estou analisando as formas de versionar as URIs de uma API REST Spring pois, no caso de lançarem um aplicativo novo, a API REST atende o aplicativo novo e suporta as requisições do aplicativo antigo por um determinado período. Mas estou na duvida de como fica o banco de dados, entidades do sistema e as URIs em geral sempre que é adicionada uma versão em uma URI.

Exemplo:

Sem versão, uma requisição para buscar todos os usuários:

http://host:8080/api/usuarios

Com versionamento:

http://host:8080/v1/usuarios

http://host:8080/v2/usuarios

http://host:8080/v1/produtos

Estava pensando em fazer uma entidade Usuario e ao definir os atributos eu anoto eles como não obrigatórios e a entidade sempre é a 'versão' mais atual. Para a versão 'v2' da URI eu crio um UsuarioV2DTO de forma que ele atende principalmente a entidade Usuário fazendo as validações com as annotations necessárias. Para a versão 'v1' da URI, digamos que usuário não possui o atributo 'dataNascimento' e dessa forma ele recebe um UsuarioV1DTO que não possui o atributo dataNascimento e na hora de converter o DTO para Entity o atributo Entity.dataNascimento fica nulo pois não é obrigatório.

O que quero saber é se essa é uma forma correta de versionar, pois no banco de dados os atributos não são obrigatórios e a validação da obrigatoriedade fica na DTO ? Também quero saber se todas as URIs de todos os recursos precisam ser alterados para a ultima versão ou se, no caso de 'produtos' ele pode ficar em V1 até que um dia seja necessário mudar apenas ele ?

1 Resposta 1

5

Existem várias abordagens para o versionamento de uma API, mas deve-se considerar o contexto da aplicação que irá expor essa interface para o cliente.

Vamos entender a API como uma camada totalmente apartada da sua aplicação que contém os domínios afim de facilitar o entendimento:

  1. Na ponta A você possui sua aplicação completa (domínios de entidades, camada web, camada de serviços...)

Neste contexto, você possui a aplicação que vai mudando de tempos em tempos, inclusive o banco de dados, onde acredito ser o X da sua questão.

Vamos aplicar alguns conceitos nas suas URLs:

Para seguir com esse versionamento de URLs, é de extrema importância que cada resposta, para cada método da sua API, seja documentada e não mude. Para conseguir isso uma boa estratégia é utilizar DTOs, eles irão expressar o contrato da sua API (para request e response). Por exemplo:

POST http://host:8080/api/v1/usuarios irá receber dados como:

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

E irá retornar:

HTTP 200

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

Se você utilizar a própria entidade, vão haver casos em que uma coluna do banco possa deixar de existir, e dessa forma seu contrato irá ser alterado à cada mudança de banco.

Utilizando DTOs, a API v1 irá necessariamente retornar estes dados, quando você implementar a v2, normalmente ela trará dados adicionais comparados a v1, a estrutura de requisição ou retorno pode ou não ser completamente diferente, e com baixíssimo acoplamento com seu legado.

Caso venha ocorrer de, por exemplo, um dado fundamental da sua API ser alterado na base de dados, e você não puder adequar a chamada afim de manter o contrato, a versão da API deve-se então ser depreciada, e os usuários devem ser orientados à atualizar para a nova versão disponibilizada.


Uma outra alternativa interessante caso você deseje manter a mesma URL independente da versão da sua API é mover a propriedade que indique a versão a ser acessada para um campo no header da sua requisição.

Empresas como Stripe e Juno utilizam essa estratégia para que seja possível manter as URLs fixas, variando a versão no header conforme a API vai sendo evoluída. Dessa forma caso o cliente deseje utilizar um recurso X ou Y que se encontra em uma versão mais atualizada, basta alterar o header e a requisição será roteada para o novo recurso.


Tais gerenciamentos se tornam mais fáceis com a adoção de um API Gateway que centralize as chamadas, e consiga rotear as requisições para o recurso desejado utilizando alguma estratégia conforme citado


É importante ter a visão de que, podem haver N clientes utilizando a sua API, e por isso é de extrema importância dessa camada ser isolada, e com poucas alterações estruturais no corpo das respostas ou requisições. Caso contrário você vai estar quebrando as aplicações usuárias do seu serviço.

Você deve fazer log-in para responder a esta pergunta.

Esta não é a resposta que você está procurando? Pesquise outras perguntas com a tag .