As melhores práticas para controle de versões em APIs REST
Em alguns projetos deixamos para escolher qual padrão de controle de versão iremos utilizar já no final do projeto, nesse artigo iremos entender, por que esse é um caminho ruim.
Introdução
O controle de versão da API costuma ser uma consideração tardia durante o processo de desenvolvimento, no entanto, esse deveria ser um dos primeiros itens que temos que construir no projeto.
Ao longo desse artigo gostaria de descrever os vários tipos de controle de versão de API, para aprimorar a experiência dos consumidores da sua API.
Aqui, está algumas opções que você pode utilizar:
1. Versão por path (URI) (opção muito utilizada no mercado)
2. Query String (será que essa é uma boa opção?)
3. Accept headers (uma reflexão tardia, na minha opinião)
O princípio básico é esse — para gerenciar a complexidade e as mudanças significativas em sua API, crie uma versão da sua API. O controle de versão da API permite que você itere rapidamente ao identificar erros ou alterações de contrato na sua API.
Quando fazer o Versionamento da sua API.
Se você não deseja criar uma versão da sua API ou tem medo de que isso aumente a complexidade durante o processo de construção, recomendo que leve em consideração os seguintes pontos:
- Se você tiver que remover um recurso da sua API que não está mais sendo utilizado, sem um controle de versão adequado, os usuários ainda podem estar atingindo este recurso(endpoint), apenas para descobrir que recebem um 404. Códigos de status como 404s não são exatamente divertidos para os desenvolvedores lidar, independentemente de você atualizar ou não sua documentação — é uma etapa extra, o desenvolvedor será obrigado a receber esse retorno para então tomar uma ação.
- Sua API agora requer uma credencial para o método POST. Na API original, você não precisa desse controle; no entanto, em sua próxima iteração, a API irá retornar o status 401 (não autorizado) se essa informação não for enviada.
- A estrutura da rota da sua API sofre uma alteração devido à uma solicitação de negócio, isso irá fazer com que a sua rota anterior não esteja mais disponível. Bem, eu poderia trazer aqui muitos outros exemplos, mas a essência disso é que você deve sempre criar uma versão da sua API para garantir que os desenvolvedores tenham uma maneira clara e concisa de se comunicar com uma API em constante mudança e atualizada.
Como fazer a versão
Quando falamos de versionamento de API’S, existem três maneiras possíveis de criar uma versão adequada de uma API:
- URL, também conhecido como versão de path (URI).
Exemplo: /v2/products/product-name)
2. Controle de versão por meio de um header customizado.
Exemplo: Accept-Version: v2.
3. Parâmetro por Query string.
Exemplo /products/product-name?version=v2.
Prós e contras
URL ou por path (URI) é um dos modelos mais utilizados. É muito mais claro e simples para o usuário qual API ele está acessando, permitindo que o usuário consulte a documentação correta.
Muitos frameworks oferecem suporte ao controle de versão definido por rota(URI) ,e quando isso não ocorre, você pode simplesmente estruturar sua API, para que, permita o controle de versão de rota. Por isso, é extremamente fácil de implementar; entretanto, ele adiciona comprimento à sua rota da API REST, o que é a desvantagem.
Os cabeçalhos personalizados seria a próxima opção — eles especificam a versão da API, e o servidor pode responder apropriadamente com os dados de resposta corretos.
Isso pode soar como uma solução fácil; porém, considere os desenvolvedores que simplesmente desejam extrair dados por meio de sua API de código aberto, sem fornecer cabeçalhos personalizados.
Por último, mas não menos importante, há o controle de versão por query string. Isso é conhecido como má prática por muitos desenvolvedores;
Pensamentos finais
Em caso de dúvida, use o controle de versão de URL / rota, se puder. Eu prometo que isso simplificará seu processo de desenvolvimento no futuro.
Já estava me esquecendo de comentar sobre esses itens, existem pelo menos dois códigos de status HTTP de redirecionamento apropriados para cenários de controle de versão de API:
301 Moved permanently
Indicando que o recurso com um URI solicitado é movido permanentemente para outro URI (que deve ser um link permanente de instância de recurso que não contém informações de versão da API). Este código de status pode ser usado para indicar uma versão de API obsoleta / sem suporte, informando ao cliente de API que um URI de recurso com versão foi substituído.
Requisição do cliente
GET /index.php HTTP/1.1Host: www.example.org
Resposta do servidor
HTTP/1.1 301 Moved PermanentlyLocation: http://www.example.org/index.asp
302 not found
Indicando que o recurso solicitado está temporariamente localizado em outro local, enquanto o URI solicitado ainda pode ser suportado. Este código de status pode ser útil quando os URIs sem versão estão temporariamente indisponíveis e uma solicitação deve ser repetida usando o endereço de redirecionamento.
Client request:
GET /index.html HTTP/1.1Host: www.example.com
Server response:
HTTP/1.1 302 FoundLocation: http://www.example.org/domains/example/
outros cenários podem ser encontrados no capítulo Redirecionamento 3xx da especificação HTTP 1.1
Ficou interessado? Fica ligado no Medium gb.tech que estamos lançando conteúdos focados em desenvolvimento.
Até a próxima.
