Estratégia de controle de versão do api

Quatro estratégias de versão da API REST.

Este artigo descreve quatro estratégias comuns de versão do REST API e explica como versão a API REST no xMatters.

Na xMatters, seguimos a especificação SemVer & # 8211; nós atualizamos a versão principal da API sempre que apresentamos mudanças de quebra. Internamente, atualizamos versões menores e patch sempre que adicionamos funcionalidades e atualizações compatíveis com versões anteriores. Quando lançamos uma nova versão principal da API REST do xMatters, os clientes podem optar por continuar usando uma versão principal existente ou migrar para a nova.

REST é, de longe, o estilo arquitetônico mais proeminente usado hoje para expor serviços a terceiros pela internet. Ele usa o padrão HTTP em vez de protocolos mais complexos, como SOAP ou RPC. A razão pela qual o REST foi tão bem sucedido é que imita como a web funciona:

Apátrida: não retém o contexto do cliente entre solicitações Cacheable: depende de regras de cache HTTP Orientação para cliente / servidor: separa preocupações entre clientes e servidores em camadas: aproveita um sistema em camadas e uma interface unificada.

Quatro estratégias comuns de controle de versão REST API.

Existem quatro maneiras comuns de versão de uma API REST.

1. Versões através do caminho URI.

Um caminho para a versão de uma API REST é incluir o número da versão no caminho do URL.

Esta estratégia é utilizada pela xMatters, bem como por outras empresas como Facebook, Twitter, Airbnb e outros.

Esta solução geralmente usa o roteamento URI para apontar para uma versão específica da API. Como as chaves de cache (nesta situação URIs) são alteradas pela versão, os clientes podem facilmente armazenar em cache os recursos. Quando uma nova versão da API REST é lançada, ela é percebida como uma nova entrada no cache.

A versão interna da API é a seguinte:

Versão principal: a versão usada na URI e denota alterações de quebra para a API. Internamente, uma nova versão importante implica criar uma nova API e o número da versão é usado para rotear para o host correto.

Versões menores e remessas: são transparentes para o cliente e são usadas internamente para atualizações compatíveis com versões anteriores. Eles geralmente são comunicados em logs de mudanças para informar os clientes sobre uma nova funcionalidade ou uma correção de bugs.

Esta solução tem uma pegada muito grande na base de código, pois introduzir mudanças de interrupção implica ramificar toda a API.

2. Versão através dos parâmetros da consulta.

Outra opção para a versão de uma API REST é incluir o número da versão como um parâmetro de consulta.

Esta é uma maneira direta de versão de uma API a partir do ponto de vista da implementação. Também é fácil predefinir a versão mais recente se um parâmetro de consulta não for especificado.

A principal desvantagem comparada à versão de URI é a dificuldade de roteamento. Os parâmetros de consulta são, de fato, mais difíceis de usar para rotear solicitações para a versão adequada da API.

3. Versões através de cabeçalhos personalizados.

As APIs REST também podem ser controladas através do fornecimento de cabeçalhos personalizados com o número de versão incluído como um atributo.

A principal diferença entre essa abordagem e as duas anteriores é que ela não destrói o URI com informações de versão.

4. Versões através da negociação de conteúdo.

Curl - H & # 8220; Aceitar: application / vnd. xm. device + json; versão = 1 e # 8221; exemplo / api / produtos.

A última estratégia que estamos abordando é o controle de versão através da negociação de conteúdo.

Esta abordagem nos permite a versão de uma única representação de recursos em vez de controlar a versão completa da API, o que nos dá um controle mais detalhado sobre o controle de versão. Ele também cria uma pegada menor na base de código, pois não precisamos empilhar todo o aplicativo ao criar uma nova versão. Outra vantagem desta abordagem é que não requer a implementação de regras de roteamento URI introduzidas pelo controle de versão através do caminho URI.

Uma das desvantagens desta abordagem é que é menos acessível do que as APIs com versão URI: exigir cabeçalhos HTTP com tipos de mídia torna mais difícil testar e explorar a API usando um navegador.

A negociação de conteúdo é uma abordagem mais granular porque ele representa as representações de recursos em vez de controlar a versão completa da API, mas também vem com um alto custo de implementação para clientes e desenvolvedores. Na maioria das vezes, a negociação de conteúdo precisa ser implementada a partir do zero, pois existem poucas bibliotecas que oferecem isso fora da caixa. As outras abordagens são mais fáceis de implementar e usar, mas limitam a capacidade do desenvolvedor de refatorar devido ao alto custo de introduzir mudanças de quebra no contrato da API.

Algum pensamento ou recomendação? Deixe um comentário abaixo!

Livro Branco gratuito: Saiba sobre o padrão + caso.

Saiba mais sobre como adotar uma abordagem holística para TI da Rob England em seu blog, The IT Skeptic, e de seus livros, incluindo Plus! A abordagem padrão + caso. Para obter mais informações, leia o novo white paper da Rob ao transformar situações de gerenciamento de casos indefinidas em novos modelos de resposta padrão, escritos para xMatters: padrão + caso: como os modelos de resposta de TI impulsionam as operações modernas.

Precisamos fazer o pacote (pasta) conforme a versão principal?

Outra questão é: como a versão do esquema, se a Mudança do Api requer mudança nas tabelas do banco de dados. algum link?

Uma coisa que não é muitas vezes documentada é como gerenciar o código e todas as versões suportadas pela API.

Estou interessado em encontrar um bom padrão para administrar nosso código e evitar o pesadelo da versão.

Minha implementação da 3ª abordagem para a primavera-webmvc:

Você também pode estar interessado em.

Como Hacked a experiência do Airbnb com a AT & # 038; T, HP e Intel.

A nova integração do ServiceNow reduz o tempo para resolver.

Moogsoft e integração de xMatters leva a gestão de incidentes para um novo nível.

Os trabalhos de Zombie não podem ser interrompidos por transmissões de e-mail.

Precisa de suporte?

Nosso site comunitário dedicado é o melhor lugar para obter ajuda em todos os produtos xMatters. Nossa equipe de pessoal de suporte especializado e usuários dentro de nossa comunidade podem ajudá-lo a obter a resposta correta.

O seu controle de versão da API é errado, razão pela qual eu decidi fazer 3 maneiras erradas diferentes.

No final, eu decidi que a maneira mais justa e equilibrada era irritar todos com igualdade. Claro que eu estou falando sobre o controle de versão da API e não desde o grande & # x201C; tabs versus spaces & # x201D; debate eu vi tantas crenças fortes em campos completamente diferentes.

Isso estava bem. Quando eu construí Eu fui escolhido? (HIBP) no final de novembro, pretendia ser um serviço simples e rápido que algumas pessoas usariam. Eu acho que é justo dizer que os dois primeiros pontos foram alcançados, mas não o último. Não foi & # x201C; alguns & # x201D ;, de fato, no final da primeira semana, foi mais do que o Google Analytics poderia lidar. O objetivo é que você sempre pode prever o futuro quando você escreve sua API e, em algum momento, você pode precisar mudar algo em que as pessoas já dependem.

Mas aqui, o problema & # x2018; Toda vez que você começa a falar sobre qualquer coisa a ver com APIs por HTTP, isso acontece:

Todo o caminho em que você se transforma há diferentes pontos de vista filosóficos em & # x201C; o caminho certo & # x201D; e muito retroceder e avançar no REST, o que é RESTful, o que não é e se importa. Deixe uma conversa sobre as mudanças da API, o impacto no controle de versão, por que há tantas idéias divergentes sobre como deve ser feito e, em última análise, por que nenhuma das palavras é tão importante como realmente conseguir coisas feitas.

Puxando mais dados de violação.

Tendo em mente que a mesma API é usada para o recurso de pesquisa no site e agora também por terceiros que criam tudo, desde aplicativos de smartphones até ferramentas de teste de penetração, a resposta acima funcionou bem no início, mas foi limitada. Por exemplo, essa resposta também não funciona bem:

Por quê? Porque & # x201C; BattlefieldHeroes & # x201D; é Pascal-encapsulado, o que é ótimo para combiná-lo com classes CSS codificadas (embora provavelmente não seja uma boa abordagem de longo prazo) e para ter um & # x201C; stable & # x201D; nome para se referir a (eu ganhei & # x2019; t mudá-lo, mesmo se houver uma segunda violação), mas não é adequado para exibição como título. Tudo isso sai do Azure Table Storage e depois entrei no SQL Azure para extrair dados relacionais que realmente descrevem a violação. Um dos atributos desse armazenamento relacional é o nome que você vê acima.

O que eu realmente queria fazer era algo mais parecido com isto:

Pegue? Para o ponto anterior sobre o nome da infração, esse ainda está lá no atributo de nome, mas agora temos um título também. Isto é o que você mostra para as pessoas & # x2018; & # x201C; Battlefield Heroes & # x201D; & # x2018; Mas, mais importante ainda, se Gawker for repetidamente, eu posso nomear a violação de algo como Gawker2018 e o título pode ser algo amigável ao longo das linhas de & # x201C; Gawker (Syrian Electronic Army Attack) & # x201D ;. Ele segmenta o que é estável e previsível a partir do que não é e significa que as pessoas podem criar dependências, como imagens ou outros recursos no atributo de nome.

Os outros dados devem ser bastante claros: a data da violação, quando foi adicionada ao sistema, o número de contas, a descrição da violação (novamente, isso pode mudar se a verbiagem precisa ser modificada) e & # x201C; DataClasses & # x201D ;. Uma das coisas que muitas pessoas pediram foi uma descrição do que foi comprometido na violação, então agora há um monte de atributos que podem ser adicionados através de uma coleção sobre a violação em si. Eu já mostrando estes abaixo de cada violação na página dos sites Pwned (esta é outra razão pela qual agora posso ajustar algumas das descrições).

Esta é uma mudança radical. Embora o sentimento da API seja o mesmo & # x2018; fornecer um nome de conta, recuperar uma lista de violações & # x2018; não há mais um conjunto de caracteres de violação de nomes de violação. Se eu simplesmente substituísse a API antiga por essa, as coisas iriam quebrar. APIs. Devo. Evoluir.

O software evolui, as APIs devem ser controladas.

Deixe-se ficar claro sobre isso: o mundo continua. A API para o HIBP durou cerca de 2 meses, não porque estava mal concebida, mas porque o serviço tornou-se selvagem, inesperadamente bem sucedido. Eu gosto desse tipo de problema, e você também deveria.

Agora eu tinha uma escolha; Ou eu poderia me contentar com o que eu tinha e privar as pessoas de uma maneira melhor, eu poderia adicionar ao serviço existente de forma não rompente ou eu poderia criar uma nova versão (embora expondo a mesma entidade de uma maneira diferente) e construa da melhor maneira que eu sabia; sem bytes desnecessários, modelados corretamente (até que eu decida que uma nova versão é mais correta) e uma boa representação da entidade que eu finalmente tentarei entrar nos consumidores & # x2019; aplicativos.

Não há nada de errado em apresentar uma nova versão de uma API quando é a coisa mais sensível. Por todos os meios, faça o seu mais difícil para obtê-lo & # x201C; right & # x201D; desde o primeiro dia, mas faça isso com a expectativa de que & # x201C; right & # x201D; é um estado temporário. É por isso que precisamos ser capazes de versão.

Os vários campos de versão.

Certo, então, como é difícil esse negócio de versão? Quero dizer, deve ser um exercício simples, certo? O problema é que ele é muito filosófico, mas, em vez de ficar atolado, por enquanto, deixe-me esboçar as três escolas comuns de pensamento em termos de como elas são praticamente implementadas:

URL: Você simplesmente invade a versão da API no URL, por exemplo: https: // haveibeenpwned / api / v2 / breachedaccount / foo Cabeçalho de solicitação personalizado: Você usa o mesmo URL que antes, mas adicione um cabeçalho como o & # x201C; api - versão: 2 & # x201D; Aceitar cabeçalho: você modifica o cabeçalho de aceitação para especificar a versão, por exemplo & # x201C; Aceitar: application / vnd. haveibeenpwned. v2 + json & # x201D;

Houve muitas, muitas coisas escritas sobre isso e eu vou ligar para elas no final da publicação, mas aqui a versão abreviada é:

Os URLs sugam porque devem representar a entidade: na verdade eu realmente concordo com isso na medida em que a entidade I & # x2019; m recuperando é uma conta quebrada, e não uma versão da conta violada. Semanticamente, não é realmente correto, mas sim, é fácil de usar! Os cabeçalhos de solicitação personalizados sugam porque ele não é realmente uma maneira semântica de descrever o recurso: a especificação HTTP nos dá um meio de solicitar a natureza que nós gostamos do recurso representado por meio do cabeçalho de aceitação, por que reproduzir esta? Aceite cabeçalhos sugam porque eles são mais difíceis de testar: eu não posso mais apenas dar a alguém um URL e dizer & # x201C; Aqui, clique neste & # x201D; antes eles precisam construir cuidadosamente a solicitação e configurar o cabeçalho de aceitação adequadamente .

Os vários argumentos para e contra cada abordagem tendem a passar de & # x201C; Este é o & # x2018; right & # x2019; maneira de fazê-lo, mas é menos prático & # x201D; através de & # x201C; Esta é a maneira mais fácil de criar algo consumível o que, portanto, o torna & # x2018; direito & # x2019; & # x201D ;. Há muita discussão sobre hipermídia, negociação de conteúdo, o que é & # x201C; REST & # x201D; e todas as outras questões. Infelizmente, isso muitas vezes se torna filosófico e perde a visão do objetivo real: construir um software que funcione e particularmente para uma API, tornando-o facilmente consumível.

É sobre ter um contrato estável, estúpido!

Mais importante do que todo o desencadeamento e delírio sobre fazê-lo dessa maneira ou dessa forma é dar às pessoas estabilidade. Se eles investem o seu código de escrita de esforço duro para consumir a sua API, então você melhorará muito, não vá e quebre-a mais na linha.

Honestamente, os debates sobre o que é & # x201C; RESTful & # x201D; versus o que não é como se o próprio termo ditar seu sucesso é apenas louco. Transforme essa discussão em & # x201C; Aqui estão os motivos práticos pelos quais isso faz sentido e isso é o que pode acontecer se você não fizer isso e # x201D ;, e eu e todos os ouvidos. O problema é que até mesmo as vozes da razão nas discussões barulhentas deixam dúvidas sobre o que realmente é a melhor abordagem e, portanto, eu alcancei um compromisso & # x2026;

Aqui estão 3 maneiras erradas de consumir a API HIBP que você pode escolher agora.

Ok, agora que nós estabelecemos claramente o que você faz é errado, eu gostaria de lhe dar a escolha de escolher entre qualquer uma das 3 maneiras erradas. Aguarde & # x2018; o que?! É assim: no entanto, implemento a API, será muito difícil de consumir, muito acadêmico, muito provável que falhe no proxy ou algo como algo. Ao invés de escolher 1 maneira errada, eu decidi você dar todas as 3 maneiras erradas e você pode escolher aquele que é o menos errado para você.

Wrong way 2 - cabeçalho de solicitação personalizado:

Inevitavelmente, alguém me dirá que fornecer 3 maneiras erradas é a coisa errada a fazer. Won & # x2019; t significa mais código kludge para manter? Não, simplesmente significa que a implementação da API da Web subjacente é decorada com dois atributos:

O primeiro é simplesmente uma restrição de roteamento que implementa RouteFactoryAttribute. Eu passo na rota e passa na versão que pode mapear para essa rota, então a implementação procura a presença de uma & # x201C; api-version & # x201D; cabeçalho ou um cabeçalho de aceitação correspondente a este padrão:

Se a versão especificada em qualquer uma dessas combina com a especificada na restrição de roteamento, então esse é o método que será invocado. Esta é uma adaptação simples desta amostra no CodePlex.

O segundo atributo que decora o método GetV2 acima vem com cortesia da Web API 2 e o recurso de roteamento de atributos. Claro que sempre poderíamos fazer o roteamento na API da Web, mas geralmente foi definido globalmente. O roteamento de atributos como esse traz a definição da rota para o contexto onde ela é aplicada e torna mais fácil ver qual ação do controlador vai ser chamada por qual rota. Isso também significa que as implementações para todas as 3 maneiras erradas de chamar a API se juntam em um local limpo.

Então, em suma, não, isso não cria muito kludge e é muito fácil de manter. Cada uma das 3 abordagens retornará exatamente o mesmo resultado e, o mais importante, eles permanecerão estáveis ​​e ganharão mudar em qualquer maneira de quebrar e, no final do dia, isso é o máximo coisa importante, independentemente da opção que você escolher. A implementação inteira agora também está claramente documentada na página API do site.

Mas e se você não especificar uma versão?

Você conhece o pouco onde eu disse que você pode quebrar o que já existe? Sim, então isso significa que se você fizer o que faz agora & # x2018; não especifique uma versão & # x2018; então você obtém o que você recebe agora. Em outras palavras, nenhum pedido para uma versão específica significa que você obteve a versão 1.

Estou bem com isso, independentemente de ter alcançado este ponto por padrão. Eu sei que algumas pessoas sempre gostam de retornar a versão mais recente se um número não for especificado, mas IMHO que quebra todo o contrato & # x201C; estável & # x201D; objetivo; O que você obtém da API hoje pode ser completamente diferente do que você obtém amanhã se eu a revisar. Isso sugaria e isso quebraria coisas.

Você tem 3 opções, mas minha preferência pessoal é & # x2026;

Tenho o luxo de controlar a API e o principal consumidor de ser o próprio site da HIBP. Dado que eu forneci 3 opções para consumir a API, qual eu uso eu?

Eu fui com o favorito filosófico que é especificá-lo através do cabeçalho de aceitação. Eu não acho que isso é correto e os outros estão errados, e acho que isso faz mais sentido por duas razões principais:

Eu concordo que o URL não deve ser alterado: se concordarmos que o URL representa o recurso, a menos que tenhamos tentado representar diferentes versões do próprio recurso, então não, eu não acho que o URL deve mudar. As brechas para foo são sempre as brechas para foo e eu não acho que apenas porque eu mudo os dados retornados para que a localização do foo mude. Eu concordo que aceitar cabeçalho descreva como você gosta dos dados: Esta é uma semântica da especificação HTTP e assim como a semântica dos verbos de solicitação faz muito sentido (ou seja, estamos recebendo ou colocando ou excluindo ou postando) Da mesma forma, a maneira como o cliente gostaria que o conteúdo fosse representado.

De modo algum isso significa que eu acho que os outros dois estão errados e, francamente, não há melhor maneira de compartilhar a API com alguém do que dizer & # x201C; Aqui, clique neste & # x201D ;, mas quando eu puder construa facilmente a solicitação e gerencie os cabeçalhos, I & # x2019; fui com esta rota.

Na verdade, penso nisso, também uso a versão na rota do domínio. Por quê? Apenas através do processo de escrever esta API, eu estava constantemente me comunicando com as pessoas sobre as formas de consultá-lo (mais sobre isso mais tarde) e os atributos que retorna. Ser capaz de enviar um e-mail e dizer & # x201C; Ei, aqui, o que eu penso e # x201D; e eles simplesmente clicam nela e obtêm resultados inestimáveis. Este é o ponto que os proponentes da abordagem de versão de URL têm razão: você simplesmente não pode fazer isso quando você depende dos cabeçalhos.

Ah, e no caso de você voltar a verificar-me, no momento da escrita, eu ainda não enviei o site para v2 da API. Agora que os dados de violação são retirados na API quando ocorre uma pesquisa, significa que tenho o luxo de não carregar todas as violações na fonte na carga inicial (isso nunca mais será sustentável à medida que o conjunto de dados se expandir). Este salvará um monte de tráfego de saída e acelerará as coisas para as pessoas em termos de obter o site carregado, mas também significa apenas um pouco mais de trabalho no meu fim. Fique ligado.

No encerramento.

Claramente, eu fiquei um pouco embaixo da boca em relação a tudo o que está errado, mas, honestamente, quanto mais você lê sobre isso e quanto mais perguntas você faz, mais errado toda rota parece de uma forma ou de outra. Na verdade, eu sei muito bem que existem aspectos da minha implementação que serão referidos como & # x201C; wrong & # x201D; (Eu posso pensar em pelo menos um casal) e, naturalmente, estou me preparando para o ataque potencial de feedback para esse efeito. Entretanto, cada uma dessas opções funciona e, francamente, para todos os propósitos práticos, elas funcionam tão bem quanto entre si.

Se eu puder deixar outros considerando como versão suas APIs com um pensamento final: Ninguém usará sua API até que você a tenha construído. Pare de procrastinar. Nenhum destes são & # x201C; bad & # x201D; em qualquer sentido tangível, eles simplesmente são diferentes. Todos são facilmente consumíveis, todos retornam o mesmo resultado e nenhum deles provavelmente terá algum impacto real no sucesso do seu projeto.

Referências.

Sobrecarga de pilha: melhores práticas para o controle de versão da API? (ótima pergunta, ótimas respostas, fechadas como & # x201C; não construtivas & # x201D ;, eu assumi porque & # x201C; Bill the Lizard & # x201D; saiu no lado errado da cama naquela manhã) Lexical Scope blog: Como é REST APIs versão? (boa comparação de práticas de versão em todos os serviços), embora agora tenha dois anos de idade) CodePlex: exemplo de restrição de roteamento (vinculado na página da API da Web da Microsoft como um exemplo de APIs de versão adicionando um cabeçalho personalizado) CodeBetter: Versioning RESTful Serviços (muito pragmático e uma boa descrição das várias formas em que uma API pode mudar) O blog de Vinay Sahni & # x2019; Melhores Práticas para Projetar uma API RESTURA pragmática (ele está discutindo a versão de URL por causa de & # x201C Exploração do navegador & # x201D;) Pivotal Lans: versão de API (boa visão das opiniões conflitantes lá fora) Web Stack of Love: Versão da API Web ASP com tipos de mídia (bom passo a passo para a criação de um aplicativo para suportar o controle de versão por negociação de conteúdo)

Oi, Troy Hunt, escrevo este blog, crie cursos para a Pluralsight e sou Diretor Regional da Microsoft e MVP que viaja no mundo falando em eventos e treinando profissionais da tecnologia.

Oi, Troy Hunt, escrevo este blog, crie cursos para a Pluralsight e sou Diretor Regional da Microsoft e MVP que viaja no mundo falando em eventos e treinando profissionais da tecnologia.

Próximos eventos.

Costumo executar workshops particulares em torno destes, aqui estão os próximos eventos públicos em que irei:

Já não tem o Pluralsight? Que tal uma versão gratuita de 10 dias? Isso lhe dará acesso a milhares de cursos entre os quais são dezenas de meus, incluindo:

"The Cloud Never Goes Down", Azure SLAs e outras trivia de disponibilidade.

Veja como Bell foi pirateado - injeção SQL por sopro.

Inscreva-se agora!

Copyright 2018, Troy Hunt.

Este trabalho está licenciado sob uma licença internacional Creative Commons Attribution 4.0. Em outras palavras, compartilhe generosamente, mas forneça atribuição.

Aviso Legal.

As opiniões expressadas aqui são minhas e podem não refletir as pessoas com quem trabalho, meus companheiros, minha esposa, as crianças, etc. A menos que eu esteja citando alguém, eles são apenas meus próprios pontos de vista.

Publicado com o Ghost.

Este site funciona inteiramente no Ghost e é possível graças ao seu amável suporte. Leia mais sobre por que eu escolhi usar Ghost.

RESTFul API Versioning Insights.

No que diz respeito ao controle de API, existem muitas práticas recomendadas e informações, mas ainda não há uma sólida prática sólida.

Para entender a versão do Restful API, primeiro precisamos entender o problema.

O Problema de Versões.

Não é possível quebrar seus clientes.

Alterar sua API é uma coisa bastante fundamental para fazer. Você está mudando literalmente a interface com a qual os clientes se comunicaram antes da mudança. O fato é que você não quer quebrar os clientes que se conectam a você hoje, enquanto ainda precisam alterar (adicionar, remover ou alterar) sua API. Isso não afeta apenas o que a API parece, ou seja, os formatos de solicitação ou resposta também podem incluir funcionalidade, e. os padrões agora funcionam de forma diferente.

Infelizmente, não importa o quão brilhantemente você arquiteta sua solução, você pode achar que, ao longo do tempo, você deve mudá-la.

Pode-se argumentar que os micro-serviços contornam esse problema ao serem pequenos. Os micro-serviços devem ser tão pequenos que são tão simples que você não terá espaço para mudá-los - você pode ler mais sobre o que são micro-serviços, mas não vou falar sobre eles hoje.

Então, supondo que você precise alterar sua API, o que você realmente quer fazer é garantir que seus clientes saibam que a sua API mudou e dê-lhes alguma maneira de decidir, ou de outra forma, a forma como a versão que eles vão se conectar que eles continuam trabalhando.

Agora que entendemos o problema, quais são as soluções possíveis?

As 4 Possíveis Soluções para a Versão da API.

Antes de eu dizer mais, gostaria de indicar que cada opção tem seus prós e contras particulares. O que você acaba escolhendo pode ser afetado não só pelas melhores práticas, restrições da infra-estrutura e outros aspectos. Atualmente, não existe a melhor solução para o Restful API Versioning e há mesmo aqueles que acreditam que não devemos precisar nossas APIs como esta publicação "Do not Version Your Web API" por Jan Stenberg.

Neste método, a versão é explicitamente colocada no URI da API. Por exemplo:

. / mapas / versão / 2. / mapas / versão / 2 / edifícios / versão / 3. / mapas / v2 / edifícios.

As opções acima mostram três formas diferentes de expor versões através do URI;

Em primeiro lugar, um modelo inteiro de hierarquia de grãos grosseiros e, em seguida, um método de sub-tópico mais refinado que nos permite a versão elementos separados da API (estradas neste caso). A terceira opção apenas mostra o modelo ligeiramente menos expressivo de ter um argumento de versão única (por exemplo, 'v2') sem o nó da versão explícita na hierarquia de URL.

Eu, pessoalmente, não gosto desse modelo. Do ponto de vista mais puro, argumenta-se que a URI em REST deve representar apenas a estrutura de recursos.

Uma versão não é um recurso, é um atributo do recurso.

No entanto, em um lado positivo, posso ver como é muito claro o que está acontecendo! Eu também vejo isso sendo recomendado por muitos fornecedores de ferramentas API. Aqui estão alguns prós e contras para esse método específico.

Já podemos ver como as vantagens para uma pessoa podem ser vistas como desvantagens para outra.

URIs sugam porque devem representar a entidade - Eu quero recuperar a entidade de mapas, não uma versão da conta quebrada. Semanticamente, não é realmente correto, mas é muito fácil de usar!

2) O cabeçalho de aceitação.

Existe um conhecido cabeçalho HTTP chamado Aceitar, que é enviado em uma solicitação de um cliente para um servidor. Por exemplo.

Esta notação está dizendo que eu, o cliente, gostaria que a resposta fosse no json, por favor.

Os cabeçalhos de aceitação estão usando este cabeçalho para criar seus próprios tipos de recursos, por exemplo:

Aceite: application / vnd. myapi. v2 + json.

Agora; Aguarde aqui porque essa é uma sintaxe um pouco estranha que nos encontramos olhando, então vamos passar por isso.

As especificações da internet dizem que eu, como fornecedor, pode definir (e ter que registrar) um tipo de mídia. Se eu fizer isso, chama-se (sem surpresa) um tipo de mídia "fornecedor". Eu deveria prefixar meu tipo com 'vnd' para deixar claro que é minha própria definição. Eu então preciso dizer qual é o nome do tipo real que eu estou definindo, p. 'myapi'. No entanto, a especificação não indica nada sobre um número de versão para que as pessoas tenham adotado para dizer que seu nome de tipo de mídia inclui um número de versão, por exemplo:

Agora, porque eu, como aplicativo cliente, ainda preciso definir o tipo de conteúdo que eu realmente quero (além da versão), isso pode ser adicionado como um sufixo ao tipo de mídia solicitado, e. '+ json' neste caso.

Observe que existe um método alternativo para fazer isso sem qualquer pré-registro do tipo de mídia usando x. como o prefixo:

O uso do cabeçalho Accept se parece com um corte muito pequeno da especificação para mim - mas funciona e é bem conhecido, se não for totalmente especificado como tal.

O maior problema com este método é que está bastante escondido - e as coisas escondidas são sempre um pouco mais difíceis de trabalhar. É quase sempre melhor ser explícito no que você está fazendo. Eu também suspeito que pedir ao seu administrador de firewall para abrir seu firewall para qualquer tipo de mídia vnd antigo poderia levar a um risco de segurança bastante grande.

No entanto, parece que é muito mais fácil passar pelo cabeçalho Accept: vnd do que para passar por cabeçalhos de solicitação personalizados.

Aceite cabeçalhos sugam porque eles são mais difíceis de testar - eu não posso mais apenas dar a alguém um URL e dizer "Aqui, siga este link", em vez disso, eles devem construir cuidadosamente a solicitação e configurar o cabeçalho de aceitação apropriadamente.

3) Cabeçalho de pedido personalizado.

Nas especificações HTTP originais, você poderia definir qualquer cabeçalho HTTP antigo que você gostasse no seu pedido de cliente, desde que você tenha sido pré-fixado com 'X-', por exemplo,

As especificações mudaram e você ainda pode passar qualquer cabeçalho de solicitação antigo, mas não precisa ser pré-fixado com 'X-' mais, por exemplo,

Isso significa que você poderia pedir aos clientes de sua API para passar em algo como.

Esta opção não é recomendada nem usada demais devido às seguintes razões:

Alguns dos roteadores (embora hoje as coisas sejam diferentes e a maioria delas passará todos os cabeçalhos) pode rejeitar toda a solicitação HTTP ou simplesmente não passar o cabeçalho especial. Depurar isso pode ser uma coisa muito difícil de fazer. Eu tive a mudança para encontrar uma coisa em que algumas máquinas estavam se conectando através de roteadores diferentes e um roteador particular tinha sido configurado para remover tipos de cabeçalho não padrão. Permitiu a mensagem através - incluindo todos os outros cabeçalhos - mas apenas removia silenciosamente aqueles que não gostava!

Está escondido novamente - assim como o cabeçalho Aceitar. O cabeçalho Aceitar já é uma maneira de ser bastante explícito sobre o que o cliente aceita, então, se vamos esconder coisas, pelo menos, vamos usar uma maneira que é conhecida.

Os cabeçalhos de solicitação personalizados sugam porque não é realmente uma maneira semântica de descrever o recurso - A especificação HTTP nos dá um meio de solicitar a natureza que gostaríamos do recurso representado por meio do cabeçalho de aceitação, por que reproduzir isso?

4) O parâmetro URI.

Aqui é óbvio que não vejo muitas pessoas usando:

Este método é altamente utilizado pela Amazon, Google e Netflix, mas ainda não é tão popular. Hmmm - talvez haja algo para isso ?!

Pensando no controle de versão do primeiro dia.

Com isso, quero dizer - quando você cria sua API real, acredita que isso irá mudar, mesmo que não hoje - algum dia. Isso afetará o que você codifica - não apenas suas decisões sobre onde colocar o número da versão.

Se você é um desenvolvedor ágil, então você poderia estar gritando na tela agora.

Agile é tudo sobre hoje. Na verdade, diz especificamente - não codifique coisas que não estão na especificação. No entanto, vamos ser claros: codificar a extensibilidade não é o mesmo que realmente colocar as extensões em si - a qual é a metodologia ágil.

Deixar espaço para futuras versões entra em ágil bem.

A versão de uma API é difícil!

Sim, é, no entanto, não é realmente difícil manter o código do cliente e do servidor em sincronia já foi. Você deve lembrar que o Building Restful APIs é muito mais fácil que os serviços da Web SOAP e é suportado praticamente por todos.

Tente permitir a extensibilidade em seu código no primeiro dia.

Com relação a como especificar a versão - Se você tiver uma convenção de controle de versão em mente, então certifique-se de que sua infraestrutura possa lidar com isso.

Leia mais postagens deste autor.

Compartilhe esta publicação.

Inscreva-se para REST API e Beyond.

Obtenha as últimas postagens enviadas diretamente para sua caixa de entrada.

ou assine via RSS com Feedly!

Orientações básicas da API RESTful.

Seu modelo de dados começou a se estabilizar e você está em condições de criar uma API pública para o seu & hellip;

REST API vs SOAP Web Services Management.

De volta ao dia, os Serviços da Web eram o padrão de fato para acessar "sistemas de registro". SOAP web services…

API Expertise.

One of the most frequent questions I receive during API training and coaching engagements involves versioning. When to version. How to version. Whether to version at all. While not all APIs are exactly the same, I have found that there are certain patterns and practices that work for most team. I have pulled these together to provide a recommendation for a versioning strategy that will help most API providers – whether they are deploying internal, private APIs or public APIs outside the organization.

Do you really need to version your API?

APIs are contracts established between you and your API consumers. Ideally, you will never have to break this contract. This includes URI patterns, payload structures, field and parameter names, expected behavior, and everything else in between. The biggest benefit of this approach is obvious: An API consumer’s understanding never expires. Applications continue to work, making your consumers happy.

However, that may not be reality. There may be times when you need to make a breaking change. When this happens, you need to ensure that you never do anything that will cause your API consumers to fix code.

Breaking vs. non-breaking changes.

Non-breaking changes tend to be additive: adding new fields or nested resources to your resource representations, adding new endpoints such as a PUT or PATCH that was previously unavailable. API consumers should build client code that is resilient to these kinds of non-breaking changes.

Breaking changes include:

Renaming fields and/or resource paths – often for clarity after your API is released Changing payload structures to accommodate the following: renaming or removing fields (even if they are considered optional – contracts!); changing fields from a single value to a one-to-many relationship (e. g. moving from one email address per account to a list of email addresses for an account) Fixing poor choices of HTTP verbs, response codes, or inconsistent design across your API endpoints.

In short, once you release your API into the wild, you have to live with it. If you encounter one or more of the items above, it may be time to version your API to prevent breaking your existing API consumers.

Defining Your API versioning strategy.

Any evolving, growing API will require an API versioning strategy. When and how you version may vary based on the expectations of your API consumers. I generally recommend the following API versioning strategy as part of an overall API governance model:

If your API is in an early preview release, perhaps to gain feedback from consumers, establish proper expectations that your API may change. At this stage, you will remain at version 1 for some time but your API design may change. Things are volatile as a consumer, so they should expect that changes may occur Once released, your API should be considered a contract and cannot be broken without a new version release API versions are major. minor, following the general principles of semantic versioning Non-breaking changes result in a bump in the minor version; clients are automatically migrated to the latest verison and should not experience any negative side-effects Breaking changes result in a new major version; clients must specifically migrate to this new version as it contains one or more breaking changes. You must establish an appropriate timeline and regular communication with your API consumers to ensure that they migrate to the new version. In some cases, this may not be possible and your team will be required to support the previous API version indefinitely.

How to implement API versioning.

Once you determine that you need a new version of your API, you need to decide how to handle it. Preferrably, you have decided ahead of time and encouraged API consumers to request version 1 of your API. There are three common approaches to implement API versioning:

Resource versioning: the version is part of the Accept header in the HTTP request. por exemplo. Accept: application/vnd. github. v3+json is sent to GET /customers . This considered the preferred form of versioning by many, as the resource representations are versioned while keeping resource URIs the same. Some APIs choose to provide the latest version as the default, if not provided in the Accept header URI versioning: the version is part of the URI, either as a prefix or suffix. por exemplo. /v1/customers or /customers/v1 . While URI-versioning isn’t as pure as content-based versioning, it tends to be the most common as it works across a variety of tools that may not support customized headers. The downside is that resource URIs change with each new version, which some consider counter to the intent of having a URI that never changes. Hostname versioning: the version is part of the hostname rather than the URI. por exemplo. https://v2.api. myapp/customers . This approach is used when technology limitations prevent routing to the proper backend version of the API based on the URI or Accept header.

No matter which option you choose, API versions should only include the major number. Minor numbers should not be required (e. g. /v1/customers , not /v1.1/customers ).

Pensamentos finais.

Remember, APIs are contracts with your consumers. Break your contract and a new version is required. Choose a strategy, have a plan, and communicate that plan with your API consumers. They will thank you for it.

Produtos.

Legal.

Get started instantly with Tyk SaaS. No credit card required, no trial period. Full access, generous quotas and FREE. Sign Up now.

já tem uma conta? Click here to login to your account, or here to login to your dashboard.

Four strategies to version APIs and services.

Published on October 16, 2017.

To manage and maintain any runtime system, you need a comprehensive versioning strategy. Without a clear strategy in place, how do you know which services and APIs are deployed and which version to use? This article highlights four strategies to help you manage API and service interfaces and implementations. It also presents the advantages and disadvantages for each strategy.

The importance of versioning.

When you define a versioning strategy, you focus on your requirements for the following two key areas:

Service or API interface: When you change the interface, your users will need to change their code. Therefore, you must have a way to track and communicate to API and service consumers that they must change the version of their API or service interface. Service or API implementation: Each time that you change the implementation, your users should be aware of the change but might not have to change their code. However, your operations team will need to track which implementation a service or API uses.

The minimum number of versions.

Version strategies often have a clear system for getting new versions into production, but with little to no regard for how to retire a service. Consider an example of a platform that runs for a few years. It might have 30 services, each with 20 different versions. Without a plan to retire a service, the platform can end up with a total of 600 instances for just one service.

“ For an API or service, keep no more than three of its most granular versions in production… ”

By coupling a sensible versioning strategy with your management system, such as IBM® API Connect, you can reduce the number of services. For an API or service, keep no more than three of its most granular versions in production for each combination of its higher-level versions. For example, if the versioning scheme is vX. Y, every X version can have only three Y values in production. For the scheme vX. X.Y, every X. X version can have only three Y values in production.

The three production versions at each level relate to the following states:

Live: New consumers must use this version. Superseded: New consumers can subscribe to this version in extenuating circumstances. Deprecated: New consumers must not use this version.

The following table shows an example of a list with the maximum number of versions that are deployed with a one-dot strategy.

Maximum number of versions for a one-dot strategy.

In this example, the maximum number of deployments is the number of dots plus one to the power of three.

Maximum number of deployments.

When a new version is ready for release, it cannot go live until the following requirements are met:

The existing deprecated version is retired. The superseded version becomes deprecated . The live version becomes superseded .

By using a good API management tool, such as API Connect, you can quickly determine which consumers are using each version. You must notify them when the service becomes deprecated or superseded. If they do not migrate to the latest version, they must understand that they risk breaking their application.

In the following strategies, each version has its own branch in the source code repository. These branches are called code streams .

One-dot strategy.

The one-dot strategy indicates the major version, followed by a dot, and then the minor version. This strategy has the following syntax:

Overview of a one-dot strategy.

This strategy has the following characteristics:

É simples. It offers tight coupling between the interface and the implementation. It has two code streams for you to manage and support. Potentially nine instances are deployed. It does not highlight significant redesigns. It is unclear when a minor change affects an interface or implementation change.

Two-dot strategy.

The two-dot strategy indicates the major version, a dot, the minor version, a dot, and then the fix number. This strategy has the following syntax:

Overview of a two-dot strategy.

This strategy has the following characteristics:

At the Fix level, you can version a service without versioning the interface. All new deployments of the implementation increment the version even if the interface is not changed. It couples the interface and implementation version without tightly binding them. It has three code streams for you to manage and support. Potentially 27 instances are deployed if three versions per version level are deployed. It does not highlight when major redesigns occur, such as when many existing interfaces are redesigned. If significant rework is required, it is not apparent.

Three-dot strategy.

The three-dot strategy is similar to the Version, Release, Modification, and Fixpack (VRMF) strategy that is used in IBM product versioning. This strategy indicates the release version, a dot, the major version, a dot, the minor version, a dot, and then the fix version. This strategy has the following syntax:

Overview of a three-dot strategy.

This strategy has the following characteristics:

It offers more precision across versions. It can version a service without versioning the interface, which means you do not have to update any catalog or developer portals. It can couple the interface and implementation version without tightly binding them. It has four code streams to manage and support. Potentially 81 instances are deployed if three versions per version level are deployed. It highlights when major redesigns occur, such as when many existing interfaces are redesigned. If significant rework is required, it is not apparent.

Decoupled strategy.

The interface and implementation are versioned independently. In this strategy, both the interface and the implementation follow a one-dot strategy. However, they can follow a more complex strategy, such as a two-dot or three-dot strategy.

This strategy has the following characteristics:

It has two code repositories with two streams in each repository. It hides the implementation version from the user. The implementation and interface have a complete disconnect. Developers and designers must align on the same strategy but not on the same version number movements. Developers and designers must agree on guidelines for how the interface and implementation version numbers move. For example, they might agree that implementations must always have the same major version number as their interface but that the minor versions can be different. Potentially nine instances of the interface and nine instances of the implementation are deployed if three versions per version level are deployed. It is more difficult to track because of the two distinct numbers. It is difficult to quickly determine which implementation that a particular interface is using.

Summary of strategies.

The following table compares the four strategies to help you make the best choice for your services and APIs.

Strategy comparison.

Each level has three instances. Changes that are compatible with an earlier version are not automatically migrated.

Each level has three instances. All changes that are compatible with an earlier version are automatically migrated.

Conclusão.

In this article, you learned about the importance of versioning and four strategies to help you manage it. Many more strategies are possible that were not addressed in this article. Keep in mind that no strategy is a single perfect fit.

Downloadable resources.

Tópicos relacionados.

Sign in or register to add and subscribe to comments.