Versionamento de APIs REST. Cada API tem sua própria versão

14

É muito comum especificar a versão das APIs REST na URL, especificamente no início do caminho, ou seja, algo como:

POST /api/v1/accounts
GET /api/v1/accounts/details

No entanto, não vi nenhum design em que a versão esteja associada a cada API. Em outras palavras, mantemos a versão de cada API separadamente. ou seja:

POST /api/accounts/v2
GET /api/accounts/details/v3

Usando essa abordagem, incrementamos a versão da API da API específica ao interromper as alterações, não é necessário incrementar a versão de todas as APIs.

Quais são os inconvenientes de usar este estilo em vez do estilo comum?

    
por Eng.Fouad 29.08.2017 / 01:41
fonte

3 respostas

13

O que você chama de APIs REST únicas pode ser chamado de conjunto específico de recursos da API REST ou recursos . Você também poderia vê-lo como uma funcionalidade da API REST . Como qualquer tipo de software, todo o pacote é versionado / atualizado, não possui funcionalidades ou recursos únicos.

Sua pergunta faria sentido no contexto em que os recursos do pacote REST API são modulares e, portanto, potencialmente desenvolvidos e versionados separadamente.

Então, até onde eu vejo, os principais contras de sua convenção de nomenclatura de localizador de recursos proposta:

  • Para o usuário da API , isso resultaria em localizadores de recursos muito mais complexos, menos previsíveis, menos memoráveis e menos estáveis. Mais difícil lembrar qual versão específica está em cada recurso e conjunto de recursos ...
  • Para o (s) desenvolvedor (es) do módulo , agora é mais trabalho ter que lidar com essa versão no seu próprio localizador de recursos.
  • As alterações nos localizadores de recursos se tornam muito mais freqüentes, tanto quanto há vários módulos sendo atualizados ... A longo prazo, os contras acima podem se tornar desagradáveis o suficiente ...

Ao criar uma API, um dos seus principais objetivos é facilitar o uso ...

Você pode encontrar uma maneira melhor de introduzir uma alteração ou até mesmo criar versões na API REST com talvez um cabeçalho HTTP?
Para saber um pouco mais sobre a abordagem de cabeçalhos HTTP, veja outras respostas abaixo e: link

    
por 29.08.2017 / 02:58
fonte
11

Veja uma abordagem ainda melhor: use negociação de conteúdo para criar uma versão da sua API com os cabeçalhos Content-Type e Accept :

POST /api/accounts
Accept: application/vnd.my-api.account.v1+json

201 Created
Location: /api/accounts/285728
Content-Type: application/vnd.my-api.account.v1+json
{ ... account data here ... }

Para obter uma versão diferente, basta solicitá-la com um tipo de conteúdo diferente em Accept . Dessa forma, as versões específicas suportadas pelo seu servidor são completamente independentes da sua estrutura de URL. O mesmo servidor poderia suportar várias versões escolhendo apenas com qual responder com base no cabeçalho Accept . Como alternativa, se você quiser manter implantações diferentes para versões diferentes, poderá colocar um proxy na frente de diferentes versões de seu serviço que escolheu para qual encaminhar solicitações com base no cabeçalho Accept .

Isso também permite que você suporte novos formatos com diferentes semântica (não apenas versões diferentes) nos mesmos pontos de extremidade. Por exemplo, postar uma lista de contas para /api/accounts poderia significar a criação de lotes, e você não precisaria criar um ponto de extremidade de API separado para ela.

    
por 29.08.2017 / 11:06
fonte
5

O principal é que, se você modificar cada ponto de extremidade separadamente, deverá poder implantar cada ponto de extremidade separadamente.

As APIs geralmente têm uma versão porque todos os pontos finais estão na mesma base de código e, portanto, têm dependências compartilhadas e são implantados juntos.

Se você não estiver atualizando a versão quando fizer uma alteração porque "Ah, tenho certeza que minha alteração não afeta isso", você terá problemas quando cometer um erro.

Além disso, você desejará ter as v1 e v2 de sua API implementadas ao mesmo tempo. Isso normalmente é feito implantando cada versão em um servidor separado e roteando o tráfego de acordo.

Se você não tiver uma única versão da API, isso se tornará muito mais complexo.

    
por 29.08.2017 / 09:56
fonte