Quais são os prós e os contras dos métodos de versão da API

Question

Notei, em algum exemplo, duas maneiras de ver uma API.

Um deles está usando uma versão no URL

/api/v1/products

O outro está usando o cabeçalho do tipo de conteúdo e o cabeçalho aceita para marcar a versão da API para os dados enviados para o servidor

Content-Type=application/vnd.company.v2+xml

Quais são os prós e contras para essas abordagens? Quais são os casos de uso em que você usará cada abordagem?

Answer 1

Estou acostumado a ter o número da versão no próprio URL (/v1/). Pessoalmente, acho que essa é uma abordagem muito mais limpa - dessa maneira, o usuário final (ou desenvolvedor) não precisa lidar com cabeçalhos HTTP e pode simplesmente modificar a API/chamada REST para acessar diferentes versões da API, conforme necessário.

Penso que também é possível que algumas das APIs HTTP disponíveis em diferentes idiomas possam não ter suporte total aos cabeçalhos HTTP, para que você sempre faça a API mais prontamente disponível para o usuário final. Reescrever o URL é a maneira mais simples e deve funcionar com qualquer coisa que suporta o HTTP por aí.

Por fim, permitir que a versão da API seja especificada usando o URL permite testes simples usando um navegador da Web. Se você incorporar a versão em um cabeçalho HTTP, o desenvolvedor será forçado a usar uma linguagem de programação para fazer testes.

Answer 2

Ambos os mecanismos são válidos. Você precisa conhecer seu consumidor para saber qual caminho seguir. Em geral, trabalhar com empresas e pessoas de mente academicamente tende a apontar os desenvolvedores para a versão para cabeçalho de recursos. No entanto, se seus clientes forem empresas menores, a abordagem de versão do URL será mais amplamente utilizada.

Aqui estão os prós e os contras que eu pude encontrar (tenho certeza de que há mais, e alguns dos contras têm trabalhos não mencionados aqui)

1. É mais explorável. Para a maioria das solicitações, você pode usar um navegador, enquanto a implementação do cabeçalho do recurso requer uma abordagem mais programática para o teste. No entanto, como nem todas as solicitações HTTP são exploráveis, por exemplo, solicitações de postagem, você deve usar um plugin de cliente REST como Carteiro ou Pata. Uri Pro/Header Con

2. Com uma API com verificação ur-i, a identificação de recursos e a representação do recurso são distribuídos juntos. Isso viola os princípios básicos do descanso; Um recurso deve ser identificado por um e apenas um terminal. Nesse sentido, a opção de versão do cabeçalho do recurso é mais academicamente idealista. Cabeçalho pro/uri con.

3. Uma API com verificação ur-i é menos propensa a erros e mais familiar aos desenvolvedores do cliente. A versão da URL permite que o desenvolvedor descubra a versão de um serviço rapidamente. f O desenvolvedor do cliente esquece de incluir uma versão de recurso no cabeçalho, você deve decidir se eles devem ser direcionados para a versão mais recente (que pode causar erros ao incrementar a versão) ou um erro 301 (movido permanente). De qualquer maneira, há mais confusão para seus desenvolvedores de clientes mais iniciantes. Uri Pro/Header Con
4. O versão URI se presta a manguar várias versões no mesmo aplicativo. Nesse caso, você não precisa desenvolver ainda mais sua estrutura. Nota: Se você fizer isso, sua estrutura de diretório provavelmente conterá uma quantidade substancial de código duplicado no diretório V2. Além disso, a implantação de atualizações requer uma reinicialização do sistema - portanto, essa técnica deve ser evitada, se possível. Uri Pro/Header Con.
5. É mais fácil adicionar versão aos cabeçalhos HTTP para um projeto existente que ainda não tinha versão em mente desde o início. Cabeçalho pro/uri con.
6. De acordo com RMM Nível 3 Princípio do REST: Controles de hipermídia, você deve usar os cabeçalhos HTTP aceitam e do tipo conteúdo para lidar com a versão de dados, além de descrever dados. Cabeçalho pro/uri con.
7. Quando você coloca a versão no URL, seus clientes precisam coordenar uma alteração do código (ou se são inteligentes, sua configuração), para a nova API. Cabeçalho pro/uri con.

Aqui estão alguns links úteis se você quiser fazer mais uma leitura adicional:

• Descrição de Martin Fowler do modelo de maturidade de Richardson
• Versão da API - Laboratórios Pivotal
• Odos
• Artigo do Informit.com sobre serviços de repouso de versão

Answer 3

Melhor usar a versão no URL. Eu estava procurando por isso há algum tempo e me deparei com os 2 recursos a seguir que discutem Design de API RESTful no comprimento.

1. Melhores práticas para projetar uma API Pragmatic RESTful - Versão via URL, não por cabeçalhos.
2. programs.stackexchange.com : O que é um padrão recomendado para o planejamento de pontos de extremidade de REST para mudanças previstas?

Tl; dr resposta: Usar a versão # no URL é uma abordagem recomendada.

Alguns dos mais bem projetados de todos os tempos que eu encontrei- API do Instagram e API do Stackoverflow.com - Ambos usam essa abordagem para o versão da API.