Melhores Práticas de Versionamento de API RESTful: Por que a v1 é a #1
Chris McFadden
24 de mai. de 2017
1 min read
Principais Conclusões
A versionamento da API previne mudanças disruptivas e preserva a confiança entre provedores de API e desenvolvedores.
Convencões de versionamento claras ajudam a evitar uma mistura caótica de versões em endpoints.
APIs RESTful emparelhadas com URIs de versão simples e explícitas mantêm as integrações intuitivas para os desenvolvedores.
Grupos de governança garantem consistência entre equipes, prevenindo mudanças disruptivas acidentais.
Nem todas as mudanças exigem uma nova versão — apenas aquelas que quebram integrações existentes.
Uma boa documentação é essencial para evitar confusões e prevenir mudanças disruptivas inadvertidas.
Separar o deployment do release permite que as equipes testem e refinem endpoints com segurança antes de anunciá-los.
Quando mudanças disruptivas são inevitáveis, elas devem ser cuidadosamente avaliadas e comunicadas.
Destaques de Perguntas e Respostas
Por que a versão da API é importante?
Isso previne mudanças inesperadas que podem quebrar a integração para desenvolvedores que utilizam sua API, protege a confiança e garante a estabilidade a longo prazo para aplicações que dependem de um comportamento consistente.
O que são mudanças disruptivas em uma API?
Qualquer modificação que altere o comportamento das integrações existentes — como remover endpoints, alterar padrões, adicionar campos obrigatórios ou modificar formatos de resposta.
Por que a SparkPost escolheu o REST como a base para sua API?
O uso do REST de HTTP e JSON facilita para desenvolvedores de diferentes linguagens (PHP, Ruby, Java, etc.) a integração sem precisar de conhecimento especializado sobre os sistemas subjacentes.
Como o SparkPost decidiu seu método de versionamento?
Eles avaliaram a versão do cabeçalho Accept contra a versão da URI e escolheram a versão da URI porque é explícita, simples e mais amigável para desenvolvedores.
Qual é o papel de um grupo de governança de API?
Estabelece padrões, impõe consistência e impede que as equipes introduzam alterações que conflitam com as convenções ou quebrem a compatibilidade.
Quais tipos de mudanças não são consideradas breaking?
Adicionando novos parâmetros opcionais, introduzindo novos endpoints, adicionando novas chaves em cargas úteis JSON ou mudando endpoints não públicos — qualquer coisa que não prejudique o comportamento existente.
Quais mudanças são consideradas quebradoras?
Adicionando parâmetros obrigatórios, removendo endpoints, alterando comportamentos padrão, modificando a estrutura da resposta ou introduzindo campos JSON obrigatórios.
Por que a documentação precisa ser precisa?
Ele evita mudanças não intencionais, ajuda os desenvolvedores a entender o comportamento e garante que as equipes atualizem a API de maneira confiável. O SparkPost usou Markdown (API Blueprint) e GitHub para manter a clareza e a transparência.
Qual é o benefício de separar a implantação da liberação?
As equipes podem implantar continuamente novos endpoints ou melhorias internamente, testá-los em fluxos de trabalho reais, refiná-los e só liberar publicamente uma vez que estejam estáveis — evitando exposição prematura e potencialmente prejudicial.
O que acontece se uma mudança significativa se tornar necessária?
Deve ser raro, justificado por benefícios claros, avaliado cuidadosamente quanto ao impacto no usuário e comunicado de forma abrangente. Exemplo: ajustar a API de Supressão somente após confirmar efeito mínimo e fornecer aviso.
Então, quão difícil pode ser versionar uma API? A verdade é que não é difícil, mas o que é difícil é manter uma sanidade ao não se transformar desnecessariamente em um número ofuscante de versões e subversões aplicadas em dezenas de endpoints de API com compatibilidades confusas.
Então, quão difícil pode ser versionar uma API? A verdade é que não é difícil, mas o que é difícil é manter uma sanidade ao não se transformar desnecessariamente em um número ofuscante de versões e subversões aplicadas em dezenas de endpoints de API com compatibilidades confusas.
Então, quão difícil pode ser versionar uma API? A verdade é que não é difícil, mas o que é difícil é manter uma sanidade ao não se transformar desnecessariamente em um número ofuscante de versões e subversões aplicadas em dezenas de endpoints de API com compatibilidades confusas.
Doh!
É justo admitir que houve momentos em que não atendemos aos nossos ideais de “sem mudanças disruptivas” e essas situações merecem ser aprendidas. Em uma ocasião, decidimos que seria melhor para os usuários se uma determinada propriedade padrão fosse verdadeira em vez de falsa. Depois que implementamos a mudança, recebemos várias reclamações dos usuários, pois o comportamento mudou inesperadamente. Revertíamos a mudança e adicionamos uma configuração em nível de conta – uma abordagem muito mais amigável para o usuário, sem dúvida.
Ocasionalmente, somos tentados a introduzir mudanças disruptivas como resultado de correções de bugs. No entanto, decidimos deixar essas idiossincrasias de lado, em vez de arriscar quebrar as integrações dos clientes em nome da consistência.
Existem casos raros em que tomamos a decisão séria de fazer uma mudança disruptiva – como descontinuar um recurso ou método de API – no interesse da comunidade de usuários em geral e somente depois de confirmar que há pouco ou nenhum impacto para os usuários. Por exemplo, fizemos deliberadamente a escolha de alterar o comportamento de resposta da API de Supressão, mas somente depois de pesar cuidadosamente os benefícios e impactos para a comunidade e comunicar cuidadosamente a mudança aos nossos usuários. No entanto, nós nunca introduziríamos uma mudança que tenha uma remota possibilidade de impactar diretamente o envio do e-mail de produção de um usuário.
É justo admitir que houve momentos em que não atendemos aos nossos ideais de “sem mudanças disruptivas” e essas situações merecem ser aprendidas. Em uma ocasião, decidimos que seria melhor para os usuários se uma determinada propriedade padrão fosse verdadeira em vez de falsa. Depois que implementamos a mudança, recebemos várias reclamações dos usuários, pois o comportamento mudou inesperadamente. Revertíamos a mudança e adicionamos uma configuração em nível de conta – uma abordagem muito mais amigável para o usuário, sem dúvida.
Ocasionalmente, somos tentados a introduzir mudanças disruptivas como resultado de correções de bugs. No entanto, decidimos deixar essas idiossincrasias de lado, em vez de arriscar quebrar as integrações dos clientes em nome da consistência.
Existem casos raros em que tomamos a decisão séria de fazer uma mudança disruptiva – como descontinuar um recurso ou método de API – no interesse da comunidade de usuários em geral e somente depois de confirmar que há pouco ou nenhum impacto para os usuários. Por exemplo, fizemos deliberadamente a escolha de alterar o comportamento de resposta da API de Supressão, mas somente depois de pesar cuidadosamente os benefícios e impactos para a comunidade e comunicar cuidadosamente a mudança aos nossos usuários. No entanto, nós nunca introduziríamos uma mudança que tenha uma remota possibilidade de impactar diretamente o envio do e-mail de produção de um usuário.
É justo admitir que houve momentos em que não atendemos aos nossos ideais de “sem mudanças disruptivas” e essas situações merecem ser aprendidas. Em uma ocasião, decidimos que seria melhor para os usuários se uma determinada propriedade padrão fosse verdadeira em vez de falsa. Depois que implementamos a mudança, recebemos várias reclamações dos usuários, pois o comportamento mudou inesperadamente. Revertíamos a mudança e adicionamos uma configuração em nível de conta – uma abordagem muito mais amigável para o usuário, sem dúvida.
Ocasionalmente, somos tentados a introduzir mudanças disruptivas como resultado de correções de bugs. No entanto, decidimos deixar essas idiossincrasias de lado, em vez de arriscar quebrar as integrações dos clientes em nome da consistência.
Existem casos raros em que tomamos a decisão séria de fazer uma mudança disruptiva – como descontinuar um recurso ou método de API – no interesse da comunidade de usuários em geral e somente depois de confirmar que há pouco ou nenhum impacto para os usuários. Por exemplo, fizemos deliberadamente a escolha de alterar o comportamento de resposta da API de Supressão, mas somente depois de pesar cuidadosamente os benefícios e impactos para a comunidade e comunicar cuidadosamente a mudança aos nossos usuários. No entanto, nós nunca introduziríamos uma mudança que tenha uma remota possibilidade de impactar diretamente o envio do e-mail de produção de um usuário.
Mudanças drásticas são ruins! Versionamento de API é bom!
Como qualquer um que construiu ou usa regularmente uma API percebe mais cedo ou mais tarde, mudanças que quebram compatibilidade são muito ruins e podem ser uma mancha muito séria em uma API que, de outra forma, seria útil. Uma mudança que quebra compatibilidade é uma alteração no comportamento de uma API que pode prejudicar a integração de um usuário e resultar em muita frustração e perda de confiança entre o provedor da API e o usuário. Mudanças que quebram compatibilidade exigem que os usuários sejam notificados com antecedência (acompanhar com desculpas sinceras) em vez de uma alteração que apenas aparece, como um novo recurso encantador. A maneira de evitar essa frustração é versionar uma API com garantias do proprietário da API de que não haverá mudanças surpreendentes introduzidas dentro de qualquer versão única.
Então, quão difícil pode ser versionar uma API? A verdade é que não é, mas o que é difícil é manter alguma sanidade, evitando a devolução desnecessária a um número vertiginoso de versões e subversões aplicadas em dezenas de endpoints de API com compatibilidades pouco claras.
Apresentamos a v1 da API há três anos e não percebemos que ela continuaria forte até hoje. Então, como conseguimos continuar fornecendo a melhor API de entrega de e-mail por mais de dois anos, mas ainda mantendo a mesma versão da API? Essa estabilidade é crucial para os desenvolvedores que constroem aplicações com APIs de e-mail em infraestrutura de nuvem, onde confiabilidade e consistência são primordiais. Embora haja muitas opiniões diferentes sobre como versionar APIs REST, espero que a história da nossa humilde, mas poderosa v1 possa guiá-lo em seu caminho para a iluminação sobre versionamento de APIs.
Como qualquer um que construiu ou usa regularmente uma API percebe mais cedo ou mais tarde, mudanças que quebram compatibilidade são muito ruins e podem ser uma mancha muito séria em uma API que, de outra forma, seria útil. Uma mudança que quebra compatibilidade é uma alteração no comportamento de uma API que pode prejudicar a integração de um usuário e resultar em muita frustração e perda de confiança entre o provedor da API e o usuário. Mudanças que quebram compatibilidade exigem que os usuários sejam notificados com antecedência (acompanhar com desculpas sinceras) em vez de uma alteração que apenas aparece, como um novo recurso encantador. A maneira de evitar essa frustração é versionar uma API com garantias do proprietário da API de que não haverá mudanças surpreendentes introduzidas dentro de qualquer versão única.
Então, quão difícil pode ser versionar uma API? A verdade é que não é, mas o que é difícil é manter alguma sanidade, evitando a devolução desnecessária a um número vertiginoso de versões e subversões aplicadas em dezenas de endpoints de API com compatibilidades pouco claras.
Apresentamos a v1 da API há três anos e não percebemos que ela continuaria forte até hoje. Então, como conseguimos continuar fornecendo a melhor API de entrega de e-mail por mais de dois anos, mas ainda mantendo a mesma versão da API? Essa estabilidade é crucial para os desenvolvedores que constroem aplicações com APIs de e-mail em infraestrutura de nuvem, onde confiabilidade e consistência são primordiais. Embora haja muitas opiniões diferentes sobre como versionar APIs REST, espero que a história da nossa humilde, mas poderosa v1 possa guiá-lo em seu caminho para a iluminação sobre versionamento de APIs.
Como qualquer um que construiu ou usa regularmente uma API percebe mais cedo ou mais tarde, mudanças que quebram compatibilidade são muito ruins e podem ser uma mancha muito séria em uma API que, de outra forma, seria útil. Uma mudança que quebra compatibilidade é uma alteração no comportamento de uma API que pode prejudicar a integração de um usuário e resultar em muita frustração e perda de confiança entre o provedor da API e o usuário. Mudanças que quebram compatibilidade exigem que os usuários sejam notificados com antecedência (acompanhar com desculpas sinceras) em vez de uma alteração que apenas aparece, como um novo recurso encantador. A maneira de evitar essa frustração é versionar uma API com garantias do proprietário da API de que não haverá mudanças surpreendentes introduzidas dentro de qualquer versão única.
Então, quão difícil pode ser versionar uma API? A verdade é que não é, mas o que é difícil é manter alguma sanidade, evitando a devolução desnecessária a um número vertiginoso de versões e subversões aplicadas em dezenas de endpoints de API com compatibilidades pouco claras.
Apresentamos a v1 da API há três anos e não percebemos que ela continuaria forte até hoje. Então, como conseguimos continuar fornecendo a melhor API de entrega de e-mail por mais de dois anos, mas ainda mantendo a mesma versão da API? Essa estabilidade é crucial para os desenvolvedores que constroem aplicações com APIs de e-mail em infraestrutura de nuvem, onde confiabilidade e consistência são primordiais. Embora haja muitas opiniões diferentes sobre como versionar APIs REST, espero que a história da nossa humilde, mas poderosa v1 possa guiá-lo em seu caminho para a iluminação sobre versionamento de APIs.
REST é o melhor
O API SparkPost se origina de quando éramos a Message Systems, antes das nossas aventuras na nuvem. Na época, estávamos ocupados fazendo os preparativos finais para o lançamento beta do Momentum 4. Esta foi uma grande atualização para a versão 3.x, nosso MTA líder de mercado local. O Momentum 4 incluiu uma interface totalmente nova, análises em tempo real e, mais importante, uma nova API web para injeção e geração de mensagens, gerenciamento de templates e obtenção de métricas de e-mail. Nossa visão era de uma arquitetura com API em primeiro lugar – onde até mesmo a interface interagiria com pontos de extremidade da API.
Uma das primeiras e melhores decisões que tomamos foi adotar um estilo RESTful. Desde o final dos anos 2000, a transferência de estado representacional (REST) baseada em APIs web é o padrão de fato das APIs em nuvem. Usar HTTP e JSON facilita a vida dos desenvolvedores, independentemente de qual linguagem de programação utilizem – PHP, Ruby e Java – para se integrar à nossa API sem saber ou se importar com nossa tecnologia subjacente. No entanto, construir APIs nativas em nuvem em grande escala pode apresentar desafios de infraestrutura inesperados, como os limites de escala de DNS que encontramos na AWS ao lidar com tráfego de API de alto volume.
Escolher usar a arquitetura RESTful foi fácil. Escolher uma convenção de versionamento não foi tão fácil. Inicialmente, deixamos de lado a questão do versionamento não versionando o beta de jeito nenhum. No entanto, dentro de poucos meses, o beta estava nas mãos de alguns clientes e começamos a construir nosso serviço em nuvem. Hora de versionar. Avaliamos duas convenções de versionamento.
Abordagem de versionamento | Como funciona | Compensação |
|---|---|---|
Versionamento de URI | Versão incluída no caminho do endpoint | Explícito e fácil de entender |
Versionamento via cabeçalho de Aceitação | Versão passada via cabeçalho HTTP | Menos visível, mais complexo para os desenvolvedores |
A primeira foi colocar o versionamento diretamente no URI e a segunda foi usar um cabeçalho de Aceitação. A primeira opção é mais explícita e menos complicada, o que é mais fácil para os desenvolvedores. Como amamos desenvolvedores, foi a escolha lógica.
O API SparkPost se origina de quando éramos a Message Systems, antes das nossas aventuras na nuvem. Na época, estávamos ocupados fazendo os preparativos finais para o lançamento beta do Momentum 4. Esta foi uma grande atualização para a versão 3.x, nosso MTA líder de mercado local. O Momentum 4 incluiu uma interface totalmente nova, análises em tempo real e, mais importante, uma nova API web para injeção e geração de mensagens, gerenciamento de templates e obtenção de métricas de e-mail. Nossa visão era de uma arquitetura com API em primeiro lugar – onde até mesmo a interface interagiria com pontos de extremidade da API.
Uma das primeiras e melhores decisões que tomamos foi adotar um estilo RESTful. Desde o final dos anos 2000, a transferência de estado representacional (REST) baseada em APIs web é o padrão de fato das APIs em nuvem. Usar HTTP e JSON facilita a vida dos desenvolvedores, independentemente de qual linguagem de programação utilizem – PHP, Ruby e Java – para se integrar à nossa API sem saber ou se importar com nossa tecnologia subjacente. No entanto, construir APIs nativas em nuvem em grande escala pode apresentar desafios de infraestrutura inesperados, como os limites de escala de DNS que encontramos na AWS ao lidar com tráfego de API de alto volume.
Escolher usar a arquitetura RESTful foi fácil. Escolher uma convenção de versionamento não foi tão fácil. Inicialmente, deixamos de lado a questão do versionamento não versionando o beta de jeito nenhum. No entanto, dentro de poucos meses, o beta estava nas mãos de alguns clientes e começamos a construir nosso serviço em nuvem. Hora de versionar. Avaliamos duas convenções de versionamento.
Abordagem de versionamento | Como funciona | Compensação |
|---|---|---|
Versionamento de URI | Versão incluída no caminho do endpoint | Explícito e fácil de entender |
Versionamento via cabeçalho de Aceitação | Versão passada via cabeçalho HTTP | Menos visível, mais complexo para os desenvolvedores |
A primeira foi colocar o versionamento diretamente no URI e a segunda foi usar um cabeçalho de Aceitação. A primeira opção é mais explícita e menos complicada, o que é mais fácil para os desenvolvedores. Como amamos desenvolvedores, foi a escolha lógica.
O API SparkPost se origina de quando éramos a Message Systems, antes das nossas aventuras na nuvem. Na época, estávamos ocupados fazendo os preparativos finais para o lançamento beta do Momentum 4. Esta foi uma grande atualização para a versão 3.x, nosso MTA líder de mercado local. O Momentum 4 incluiu uma interface totalmente nova, análises em tempo real e, mais importante, uma nova API web para injeção e geração de mensagens, gerenciamento de templates e obtenção de métricas de e-mail. Nossa visão era de uma arquitetura com API em primeiro lugar – onde até mesmo a interface interagiria com pontos de extremidade da API.
Uma das primeiras e melhores decisões que tomamos foi adotar um estilo RESTful. Desde o final dos anos 2000, a transferência de estado representacional (REST) baseada em APIs web é o padrão de fato das APIs em nuvem. Usar HTTP e JSON facilita a vida dos desenvolvedores, independentemente de qual linguagem de programação utilizem – PHP, Ruby e Java – para se integrar à nossa API sem saber ou se importar com nossa tecnologia subjacente. No entanto, construir APIs nativas em nuvem em grande escala pode apresentar desafios de infraestrutura inesperados, como os limites de escala de DNS que encontramos na AWS ao lidar com tráfego de API de alto volume.
Escolher usar a arquitetura RESTful foi fácil. Escolher uma convenção de versionamento não foi tão fácil. Inicialmente, deixamos de lado a questão do versionamento não versionando o beta de jeito nenhum. No entanto, dentro de poucos meses, o beta estava nas mãos de alguns clientes e começamos a construir nosso serviço em nuvem. Hora de versionar. Avaliamos duas convenções de versionamento.
Abordagem de versionamento | Como funciona | Compensação |
|---|---|---|
Versionamento de URI | Versão incluída no caminho do endpoint | Explícito e fácil de entender |
Versionamento via cabeçalho de Aceitação | Versão passada via cabeçalho HTTP | Menos visível, mais complexo para os desenvolvedores |
A primeira foi colocar o versionamento diretamente no URI e a segunda foi usar um cabeçalho de Aceitação. A primeira opção é mais explícita e menos complicada, o que é mais fácil para os desenvolvedores. Como amamos desenvolvedores, foi a escolha lógica.
Governança de API
Com uma convenção de versionamento selecionada, tínhamos mais perguntas. Quando devemos aumentar a versão? O que é uma mudança quebradora? Devemos reversionar toda a API ou apenas determinados endpoints? Na SparkPost, temos várias equipes trabalhando em diferentes partes da nossa API. Dentro dessas equipes, as pessoas trabalham em diferentes endpoints em tempos diferentes. Portanto, é muito importante que nossa API seja consistente no uso de convenções. Isso era maior do que versionamento.
Estabelecemos um grupo de governança incluindo engenheiros representando cada equipe, um membro da equipe de Gestão de Produtos e nosso CTO. Este grupo é responsável por estabelecer, documentar e aplicar nossas convenções de API em todas as equipes. Um canal de Slack de governança da API também é útil para debates vibrantes sobre o tópico.
O grupo de governança identificou várias maneiras de mudanças que podem ser introduzidas na API que são benéficas para o usuário e não constituem uma mudança quebradora.
Tipo de mudança | Considerado quebrador? | Razão |
|---|---|---|
Novo recurso ou endpoint | Não | Não afeta integrações existentes |
New optional parameter | Não | Requisições existentes permanecem válidas |
Nova chave JSON opcional | Não | Clientes podem ignorá-la com segurança |
Novo campo de resposta | Não | Compatível com versões anteriores para consumidores |
Novo parâmetro obrigatório | Sim | Quebra requisições existentes |
Nova chave POST obrigatória | Sim | Invalida cargas úteis existentes |
Remoção de um endpoint | Sim | Integrações existentes falham |
Alterando o comportamento padrão | Sim | Altera os resultados esperados |
Essas incluem:
Um novo recurso ou endpoint de API
Um novo parâmetro opcional
Uma mudança em um endpoint de API não público
Uma nova chave opcional no corpo JSON de POST
Uma nova chave retornada no corpo da resposta JSON
Por outro lado, uma mudança quebradora inclui qualquer coisa que poderia quebrar a integração de um usuário, como:
Um novo parâmetro obrigatório
Uma nova chave obrigatória nos corpos de POST
Remoção de um endpoint existente
Remoção de um método de requisição de endpoint existente
Um comportamento interno materialmente diferente de uma chamada de API – como uma mudança no comportamento padrão.
Com uma convenção de versionamento selecionada, tínhamos mais perguntas. Quando devemos aumentar a versão? O que é uma mudança quebradora? Devemos reversionar toda a API ou apenas determinados endpoints? Na SparkPost, temos várias equipes trabalhando em diferentes partes da nossa API. Dentro dessas equipes, as pessoas trabalham em diferentes endpoints em tempos diferentes. Portanto, é muito importante que nossa API seja consistente no uso de convenções. Isso era maior do que versionamento.
Estabelecemos um grupo de governança incluindo engenheiros representando cada equipe, um membro da equipe de Gestão de Produtos e nosso CTO. Este grupo é responsável por estabelecer, documentar e aplicar nossas convenções de API em todas as equipes. Um canal de Slack de governança da API também é útil para debates vibrantes sobre o tópico.
O grupo de governança identificou várias maneiras de mudanças que podem ser introduzidas na API que são benéficas para o usuário e não constituem uma mudança quebradora.
Tipo de mudança | Considerado quebrador? | Razão |
|---|---|---|
Novo recurso ou endpoint | Não | Não afeta integrações existentes |
New optional parameter | Não | Requisições existentes permanecem válidas |
Nova chave JSON opcional | Não | Clientes podem ignorá-la com segurança |
Novo campo de resposta | Não | Compatível com versões anteriores para consumidores |
Novo parâmetro obrigatório | Sim | Quebra requisições existentes |
Nova chave POST obrigatória | Sim | Invalida cargas úteis existentes |
Remoção de um endpoint | Sim | Integrações existentes falham |
Alterando o comportamento padrão | Sim | Altera os resultados esperados |
Essas incluem:
Um novo recurso ou endpoint de API
Um novo parâmetro opcional
Uma mudança em um endpoint de API não público
Uma nova chave opcional no corpo JSON de POST
Uma nova chave retornada no corpo da resposta JSON
Por outro lado, uma mudança quebradora inclui qualquer coisa que poderia quebrar a integração de um usuário, como:
Um novo parâmetro obrigatório
Uma nova chave obrigatória nos corpos de POST
Remoção de um endpoint existente
Remoção de um método de requisição de endpoint existente
Um comportamento interno materialmente diferente de uma chamada de API – como uma mudança no comportamento padrão.
Com uma convenção de versionamento selecionada, tínhamos mais perguntas. Quando devemos aumentar a versão? O que é uma mudança quebradora? Devemos reversionar toda a API ou apenas determinados endpoints? Na SparkPost, temos várias equipes trabalhando em diferentes partes da nossa API. Dentro dessas equipes, as pessoas trabalham em diferentes endpoints em tempos diferentes. Portanto, é muito importante que nossa API seja consistente no uso de convenções. Isso era maior do que versionamento.
Estabelecemos um grupo de governança incluindo engenheiros representando cada equipe, um membro da equipe de Gestão de Produtos e nosso CTO. Este grupo é responsável por estabelecer, documentar e aplicar nossas convenções de API em todas as equipes. Um canal de Slack de governança da API também é útil para debates vibrantes sobre o tópico.
O grupo de governança identificou várias maneiras de mudanças que podem ser introduzidas na API que são benéficas para o usuário e não constituem uma mudança quebradora.
Tipo de mudança | Considerado quebrador? | Razão |
|---|---|---|
Novo recurso ou endpoint | Não | Não afeta integrações existentes |
New optional parameter | Não | Requisições existentes permanecem válidas |
Nova chave JSON opcional | Não | Clientes podem ignorá-la com segurança |
Novo campo de resposta | Não | Compatível com versões anteriores para consumidores |
Novo parâmetro obrigatório | Sim | Quebra requisições existentes |
Nova chave POST obrigatória | Sim | Invalida cargas úteis existentes |
Remoção de um endpoint | Sim | Integrações existentes falham |
Alterando o comportamento padrão | Sim | Altera os resultados esperados |
Essas incluem:
Um novo recurso ou endpoint de API
Um novo parâmetro opcional
Uma mudança em um endpoint de API não público
Uma nova chave opcional no corpo JSON de POST
Uma nova chave retornada no corpo da resposta JSON
Por outro lado, uma mudança quebradora inclui qualquer coisa que poderia quebrar a integração de um usuário, como:
Um novo parâmetro obrigatório
Uma nova chave obrigatória nos corpos de POST
Remoção de um endpoint existente
Remoção de um método de requisição de endpoint existente
Um comportamento interno materialmente diferente de uma chamada de API – como uma mudança no comportamento padrão.
O Grande 1.0
À medida que documentamos e discutimos essas convenções, também chegamos à conclusão de que era do interesse de todos (incluindo o nosso!) evitar fazer mudanças drásticas na API, uma vez que gerenciar várias versões adiciona um bom tanto de sobrecarga. Decidimos que havia algumas coisas que deveríamos corrigir em nossa API antes de nos comprometermos com a “v1”.
Enviar um simples e-mail exigia muito esforço. Para “manter as coisas simples”, atualizamos o corpo do POST para garantir que tanto casos de uso simples quanto complexos fossem acomodados. O novo formato também era mais à prova de futuro. Em segundo lugar, abordamos um problema com o endpoint de Métricas. Esse endpoint usava um parâmetro “group_by” que mudava o formato do corpo da resposta GET de tal forma que a primeira chave seria o valor do parâmetro do grupo. Isso não parecia muito RESTful, então dividimos cada grupo em um endpoint separado. Finalmente, auditamos cada endpoint e fizemos pequenas alterações aqui e ali para garantir que estivessem em conformidade com os padrões.
À medida que documentamos e discutimos essas convenções, também chegamos à conclusão de que era do interesse de todos (incluindo o nosso!) evitar fazer mudanças drásticas na API, uma vez que gerenciar várias versões adiciona um bom tanto de sobrecarga. Decidimos que havia algumas coisas que deveríamos corrigir em nossa API antes de nos comprometermos com a “v1”.
Enviar um simples e-mail exigia muito esforço. Para “manter as coisas simples”, atualizamos o corpo do POST para garantir que tanto casos de uso simples quanto complexos fossem acomodados. O novo formato também era mais à prova de futuro. Em segundo lugar, abordamos um problema com o endpoint de Métricas. Esse endpoint usava um parâmetro “group_by” que mudava o formato do corpo da resposta GET de tal forma que a primeira chave seria o valor do parâmetro do grupo. Isso não parecia muito RESTful, então dividimos cada grupo em um endpoint separado. Finalmente, auditamos cada endpoint e fizemos pequenas alterações aqui e ali para garantir que estivessem em conformidade com os padrões.
À medida que documentamos e discutimos essas convenções, também chegamos à conclusão de que era do interesse de todos (incluindo o nosso!) evitar fazer mudanças drásticas na API, uma vez que gerenciar várias versões adiciona um bom tanto de sobrecarga. Decidimos que havia algumas coisas que deveríamos corrigir em nossa API antes de nos comprometermos com a “v1”.
Enviar um simples e-mail exigia muito esforço. Para “manter as coisas simples”, atualizamos o corpo do POST para garantir que tanto casos de uso simples quanto complexos fossem acomodados. O novo formato também era mais à prova de futuro. Em segundo lugar, abordamos um problema com o endpoint de Métricas. Esse endpoint usava um parâmetro “group_by” que mudava o formato do corpo da resposta GET de tal forma que a primeira chave seria o valor do parâmetro do grupo. Isso não parecia muito RESTful, então dividimos cada grupo em um endpoint separado. Finalmente, auditamos cada endpoint e fizemos pequenas alterações aqui e ali para garantir que estivessem em conformidade com os padrões.
Documentação Acurada
É importante ter documentação de API precisa e utilizável para evitar mudanças drásticas, sejam elas deliberadas ou não intencionais. Decidimos usar uma abordagem simples de documentação de API aproveitando uma linguagem Markdown chamada API Blueprint e gerenciar nossa documentação no Github. Nossa comunidade contribui e melhora esses documentos de código aberto. Também mantemos um conjunto não público de documentos no Github para APIs e endpoints internos.
Inicialmente, publicamos nossa documentação para Apiary, uma ótima ferramenta para prototipagem e publicação de documentos de API. No entanto, incorporar o Apiary em nosso site não funciona em dispositivos móveis, então agora usamos Jekyll para gerar documentos estáticos. Nossa última documentação da API SparkPost agora carrega rapidamente e funciona bem em dispositivos móveis, o que é importante para desenvolvedores que não estão sempre sentados em seus computadores.
É importante ter documentação de API precisa e utilizável para evitar mudanças drásticas, sejam elas deliberadas ou não intencionais. Decidimos usar uma abordagem simples de documentação de API aproveitando uma linguagem Markdown chamada API Blueprint e gerenciar nossa documentação no Github. Nossa comunidade contribui e melhora esses documentos de código aberto. Também mantemos um conjunto não público de documentos no Github para APIs e endpoints internos.
Inicialmente, publicamos nossa documentação para Apiary, uma ótima ferramenta para prototipagem e publicação de documentos de API. No entanto, incorporar o Apiary em nosso site não funciona em dispositivos móveis, então agora usamos Jekyll para gerar documentos estáticos. Nossa última documentação da API SparkPost agora carrega rapidamente e funciona bem em dispositivos móveis, o que é importante para desenvolvedores que não estão sempre sentados em seus computadores.
É importante ter documentação de API precisa e utilizável para evitar mudanças drásticas, sejam elas deliberadas ou não intencionais. Decidimos usar uma abordagem simples de documentação de API aproveitando uma linguagem Markdown chamada API Blueprint e gerenciar nossa documentação no Github. Nossa comunidade contribui e melhora esses documentos de código aberto. Também mantemos um conjunto não público de documentos no Github para APIs e endpoints internos.
Inicialmente, publicamos nossa documentação para Apiary, uma ótima ferramenta para prototipagem e publicação de documentos de API. No entanto, incorporar o Apiary em nosso site não funciona em dispositivos móveis, então agora usamos Jekyll para gerar documentos estáticos. Nossa última documentação da API SparkPost agora carrega rapidamente e funciona bem em dispositivos móveis, o que é importante para desenvolvedores que não estão sempre sentados em seus computadores.
Separando a Implantação da Liberação
Aprendemos desde cedo o valioso truque de separar uma implantação de um lançamento. Dessa forma, é possível implantar mudanças frequentemente quando estão prontas por meio de entrega e implantação contínuas, mas nem sempre anunciamos ou documentamos publicamente ao mesmo tempo. Não é incomum para nós implantar um novo endpoint de API ou uma melhoria em um endpoint de API existente e usá-lo a partir da interface do usuário ou com ferramentas internas antes de documentá-lo publicamente e oferecê-lo suporte. Dessa forma, podemos fazer alguns ajustes para usabilidade ou conformidade com padrões sem nos preocuparmos em fazer uma temida mudança disruptiva. Uma vez que estamos satisfeitos com a mudança, a adicionamos à nossa documentação pública.
Aprendemos desde cedo o valioso truque de separar uma implantação de um lançamento. Dessa forma, é possível implantar mudanças frequentemente quando estão prontas por meio de entrega e implantação contínuas, mas nem sempre anunciamos ou documentamos publicamente ao mesmo tempo. Não é incomum para nós implantar um novo endpoint de API ou uma melhoria em um endpoint de API existente e usá-lo a partir da interface do usuário ou com ferramentas internas antes de documentá-lo publicamente e oferecê-lo suporte. Dessa forma, podemos fazer alguns ajustes para usabilidade ou conformidade com padrões sem nos preocuparmos em fazer uma temida mudança disruptiva. Uma vez que estamos satisfeitos com a mudança, a adicionamos à nossa documentação pública.
Aprendemos desde cedo o valioso truque de separar uma implantação de um lançamento. Dessa forma, é possível implantar mudanças frequentemente quando estão prontas por meio de entrega e implantação contínuas, mas nem sempre anunciamos ou documentamos publicamente ao mesmo tempo. Não é incomum para nós implantar um novo endpoint de API ou uma melhoria em um endpoint de API existente e usá-lo a partir da interface do usuário ou com ferramentas internas antes de documentá-lo publicamente e oferecê-lo suporte. Dessa forma, podemos fazer alguns ajustes para usabilidade ou conformidade com padrões sem nos preocuparmos em fazer uma temida mudança disruptiva. Uma vez que estamos satisfeitos com a mudança, a adicionamos à nossa documentação pública.
