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

É 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?

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/

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.

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.