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


15

É muito comum especificar a versão das APIs REST no 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 específica quando é necessária uma alteração final, não sendo necessário incrementar a versão de APIs inteiras.

Quais são as desvantagens de usar esse estilo em vez do estilo comum?

Respostas:


13

O que você chama de APIs REST únicas pode ser chamado de conjunto ou recursos específicos da API REST . Você também pode considerar as funcionalidades da API REST . Como qualquer tipo de software, todo o pacote é versionado / atualizado, não funcionalidades ou recursos únicos.

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

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

  • 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.
  • Para os desenvolvedores do módulo , agora é mais trabalhoso lidar com esse controle de versão em seu próprio localizador de recursos.
  • As alterações nos localizadores de recursos se tornam muito mais frequentes, pois há vários módulos atualizados, portanto os contras acima são exponenciais ...

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

Você pode encontrar uma maneira melhor de introduzir uma alteração de última hora ou até mesmo versionar a API REST com talvez um cabeçalho HTTP?

Para saber um pouco mais sobre a abordagem de cabeçalhos HTTP, consulte outras respostas abaixo e: https://www.troyhunt.com/your-api-versioning-is-wrong-which-is/


12

Aqui está uma abordagem ainda melhor: usar negociação de conteúdo para a versão sua API com o Content-Typee Acceptcabeçalhos:

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 Accept. Dessa forma, as versões específicas suportadas pelo servidor são completamente independentes da sua estrutura de URL. O mesmo servidor pode suportar várias versões escolhendo apenas as respostas com base no Acceptcabeçalho. Como alternativa, se você quiser se manter em implantações diferentes para versões diferentes, poderá colocar um proxy na frente de versões diferentes do seu serviço que escolham qual delas encaminhar solicitações com base no Acceptcabeçalho.

Isso também permite que você suporte novos formatos com diferentes semânticas (não apenas versões diferentes) nos mesmos pontos de extremidade. Por exemplo, POSTAR uma lista de contas /api/accountspode significar a criação de lotes, e você não precisará criar um terminal de API separado para ele.


omg, o cabeçalho de aceitação deve ser a pior escolha de sinalização de versão. usar um cabeçalho de versão se você puder, caminho url se você deve (ou seja AWS roteamento)
Ewan

@Ewan Why? Um cabeçalho de versão personalizado implica que versões diferentes são o mesmo recurso sem informar aos intermediários que o conteúdo pode ser diferente. Um proxy de armazenamento em cache não saberia usar seu cabeçalho para não fornecer respostas em cache da v1 para solicitações da v2.
Jack

use o cabeçalho de resposta varia, se você ainda não estiver usando no-cache para solicitações de API !. tipo de conteúdo já tem um significado, subornando-lo para seu uso privado, apenas torna a vida difícil para os consumidores
Ewan

@ Ewan É para isso que servem a vndparte e a +sintaxe do tipo: para indicar que este é um subtipo específico do fornecedor application/json. É exatamente para isso que os tipos de conteúdo são projetados. Seu recurso está disponível em vários formatos. Você está pedindo ao cliente para escolher qual formato ele deseja. Além disso, não há razão para que as solicitações de API não possam usar a semântica padrão de cache HTTP.
Jack

se você corrigir um bug no myapi v2, não retornará um novo tipo mime.
Ewan

5

O principal é que, se você fizer a versão de cada terminal separadamente, deverá poder implantar cada terminal 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 "Oh, tenho certeza de que minha alteração não afeta isso", você terá problemas quando cometer um erro.

Além disso, você deseja que a v1 e a v2 da sua API sejam implantadas 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 possui uma única versão da API, isso se torna muito mais complexo.

Ao utilizar nosso site, você reconhece que leu e compreendeu nossa Política de Cookies e nossa Política de Privacidade.
Licensed under cc by-sa 3.0 with attribution required.