O que é versionamento de API
O controle de versão de API é um processo muito importante para os designers de API, pois permite introduzir novos recursos, melhorar funções existentes ou corrigir bugs sem a necessidade de desenvolver um produto completamente novo. Esta prática constitui um mecanismo de diferenciação para os momentos em que uma API sofre mudanças significativas, exigindo que os consumidores da API alterem seus aplicativos. O ciclo típico começa com a versão 1 (v1) de uma API, e após alterações que necessitam de adaptações pelos desenvolvedores, a versão 2 (v2) é lançada. Muitas vezes, as versões anteriores da API permanecem ativas por algum tempo, proporcionando aos desenvolvedores a oportunidade de se adaptarem.
No entanto, se essas adaptações não são realizadas, a versão antiga da API pode induzir mudanças drásticas que resultam em falhas em outros componentes do sistema. Isso pode levar a uma quebra de contrato, com desenvolvedores tendo que gastar várias horas de codificação para identificar e resolver o problema. Inevitavelmente, haverá momentos em que as APIs ultrapassarão seu escopo original e necessitarão de alterações significativas. Essas alterações são a chave para determinar a necessidade de uma nova versão em muitas estratégias de versionamento. Portanto, aprender a criar uma versão e entender o momento certo para fazê-lo é essencial para desenvolver uma estratégia eficaz que se comunique claramente com os desenvolvedores, mantendo assim um relacionamento saudável com usuários e parceiros.
A importância do versionamento de API
No desenvolvimento de uma API, o primeiro grande desafio reside em definir o que será exposto, uma decisão muitas vezes ligada mais ao entendimento do negócio do que à tecnologia em si. Após a API entrar em produção, o desafio se amplia para a sua manutenção, considerando três pilares principais: segurança, performance e evolução de negócio. Caso a solução afete a interface pública do serviço, isso pode resultar em clientes inoperantes. Para mitigar possíveis impasses, a prática do “versionamento” é fundamental.
Com a crescente presença dos microsserviços, o versionamento de APIs tornou-se cada vez mais essencial, pois permite a evolução de todos os serviços de uma mesma solução. Além disso, o versionamento também informa aos clientes sobre as alterações, indicando quando uma nova versão está disponível e mantendo a compatibilidade com as versões anteriores. Isso proporciona uma maior flexibilidade de integração de acordo com as necessidades do cliente. No entanto, é importante salientar que em certas situações, a evolução da API pode ser obrigatória, como no caso da inclusão de um novo atributo indispensável para o provedor do serviço.
A manutenção das APIs, especialmente em ambientes complexos e multifacetados, pode ser uma tarefa difícil. Como Thoran Rodrigues, fundador e CEO da Big Data Corp, observa: “O problema da integração é um desafio eterno na área de tecnologia. Há décadas, temos sistemas que não se comunicam entre si, e as APIs são uma forma de solucionar isso”. Este é exatamente o motivo pelo qual uma estratégia sólida de versionamento de API é essencial: para facilitar essa integração e comunicação.
Quando criar versões de API
Um aspecto crítico na construção de APIs é o versionamento e a evolução. A verdadeira arte do desenvolvimento de APIs reside em criar soluções que não apenas resolvam problemas presentes, mas que também estejam preparadas para desafios futuros. Os desenvolvedores frequentemente criam APIs com um foco restrito no “problema atual”, sem considerar as necessidades futuras. Uma API eficaz, no entanto, deve ser flexível, capaz de evoluir e se adaptar à medida que as necessidades dos usuários mudam.
Principais alterações de versão
As modificações principais de versão são as que incorporam mudanças relevantes e demandam adaptações necessárias para clientes, sejam eles novos ou já existentes. Normalmente, nos planos de versionamento de API, somente o número da versão principal é alterado, uma vez que ele sinaliza a ocorrência de uma modificação de grande porte. Alguns exemplos disso são:
- Alterações em campos ou rotas, que englobam tanto remoções quanto renomeações;
- Modificações na carga de dados transportada;
- Exclusão de pontos de acesso para aperfeiçoamento do design HTTP.
Alteração secundária
Em certas ocasiões, é possível implementar correções ou modificações menores na sua API sem causar impacto aos usuários já existentes. Mudanças sutis, que abrangem novas funcionalidades, métodos ou recursos, podem ser descartadas pelos usuários atuais, caso eles não tenham interesse em utilizá-las. Atualizações na documentação, como a correção de erros de digitação, costumam ser realizadas por meio de um procedimento de aplicação de correções.
Sistemas de versionamentos mais utilizados
O CVS, uma das ferramentas de controle de versão mais antigas, ainda possui relevância atualmente, apesar de não ser a mais utilizada. Originada em 1968, continua sendo empregada por diversas equipes de desenvolvimento.
Em contrapartida, o SVN foi introduzido com novas funcionalidades e com a correção de algumas falhas identificadas no CVS. Ele se destaca por sua simplicidade e velocidade de uso, sendo ideal para equipes pequenas, uma vez que possui um sistema de controle de versão centralizado. O Mercurial, por sua vez, é conhecido por ser usado por grandes empresas, como a Meta e a Google. Apesar de ser mais complexo que o SVN, o Mercurial é veloz e dispõe de robustas medidas de segurança para minimizar erros, estando associado a um sistema de controle de versão descentralizado.
Por fim, temos o Git, uma das ferramentas mais populares entre os desenvolvedores atualmente, tanto em ambientes corporativos quanto em projetos individuais. Ele consegue cumprir com eficácia todos os objetivos de um bom controle de software. Entretanto, é preciso destacar que, comparativamente às outras ferramentas, o Git apresenta maior complexidade, e está vinculado a um sistema de controle de versão descentralizado.
Tipos de versionamento
URI Path
A forma mais frequente de versionamento de APIs envolve o uso do caminho URI, em que a versão é detalhada no Identificador Uniforme de Recursos (URI) da solicitação. Este método é intuitivo e fácil de implementar.
Accept Header
O versionamento aqui é conduzido por meio do cabeçalho, o que resulta em uma URI descomplicada. Esta estratégia é tipicamente empregada em situações de negociação de conteúdo, onde se trabalha com uma única representação por recurso.
Custom HTTP Header
Similar ao Cabeçalho Aceitar, o versionamento por meio de Cabeçalho HTTP Personalizado também se dá através do cabeçalho, mas com uma abordagem personalizada. Neste caso, um método personalizado é desenvolvido no backend para lidar com a versão da API. Embora aplicável aos mesmos cenários do Cabeçalho Aceitar, este tipo proporciona maior adaptabilidade.
Query Parameter
Como no caso do Caminho URI, o versionamento por meio de Parâmetro de Consulta é de fácil implementação, mas pode ser um pouco mais complexo no que se refere ao roteamento de versões.
Subdomínio
A versão por subdomínio normalmente envolve diferentes tipos de serviço (backend). Nesta situação, é possível ter versões distintas para diferentes serviços. Por exemplo, a versão v1 poderia ser aplicada a um serviço web, e a v2 a um microsserviço.
5 passos para uma boa estratégia de versionamento de APIs
Passo 1: Determinar a necessidade de versionamento
A primeira etapa da estratégia de versionamento envolve decidir se há uma necessidade real de versionar a API. Uma vez que se entende que o versionamento é uma necessidade incontornável, o próximo estágio é identificar os usuários que serão afetados por essa mudança. Presume-se que se tenha conhecimento total de todos os desenvolvedores e aplicações que estão utilizando as APIs.
Para se aprofundar no assunto, baixe o material de apoio do podcast!
Passo 2: Estabelecer um plano de comunicação
Após identificar os usuários, a etapa seguinte é formular uma estratégia de comunicação. Essa estratégia pode envolver comunicação via e-mail, através de um portal de desenvolvedores, ou outros meios que sejam mais eficazes.
Passo 3: Definir o prazo para a adaptação
O terceiro passo na estratégia de versionamento é estabelecer um prazo para os usuários se adaptarem à nova versão da API. Esse prazo dependerá de vários fatores, incluindo o tipo de API, a quantidade e o tipo de usuários, e a natureza da mudança que está sendo implementada. Algumas organizações dão um prazo de seis meses, enquanto outras podem dar até dois anos.
Passo 4: Antecipar possíveis problemas
O quarto passo é prever quaisquer problemas potenciais que possam surgir ao versionar a API. A abordagem ideal ao versionamento é garantir que haja compatibilidade com as versões anteriores. Assim, se surgir um problema, o usuário poderá facilmente reverter para a versão anterior sem muitos contratempos.
Passo 5: Limitar o número de versões da API
O quinto e último passo, que, na verdade, é mais uma sugestão, é manter o máximo de duas versões da API disponíveis ao mesmo tempo. Sabemos que isso pode parecer fácil na teoria, mas nem sempre é tão simples na prática. Contudo, é importante lembrar que, quanto menos versões da API estiverem em uso, menor será o risco de impactos negativos na governança e, consequentemente, na segurança do sistema.
Os desafios da segurança da API
As APIs desempenham um papel essencial na estrutura dos aplicativos modernos, sejam eles móveis, com base na Web ou SaaS. Estes componentes estão presentes tanto em aplicações direcionadas aos clientes, quanto em soluções para parceiros ou de uso interno. Devido à sua funcionalidade, as APIs revelam a lógica por trás do aplicativo e, muitas vezes, lidam com dados sensíveis, incluindo Informações Pessoalmente Identificáveis (PII). Por conta dessa exposição, elas se tornaram um alvo crescente para invasores, denunciando a necessidade de medidas robustas de segurança.
De acordo com Thoran Rodrigues, “Nós estamos passando por uma revolução em termos de dados. A informação que estava armazenada em planilhas, documentos e sistemas internos agora está sendo exposta ao mundo por meio das APIs. E isso é uma revolução que ainda está apenas começando”. Isso ressalta a importância vital de estratégias de versionamento eficazes e robustas medidas de segurança para garantir que essas informações sejam gerenciadas de maneira eficaz e segura.
De acordo com o relatório da OWASP, os principais riscos à segurança de APIs no ano de 2023 são devido a quebra de autorização em níveis de objeto, geralmente devido à exposição excessiva de endpoints ou implementação inadequada de controles de acesso. Além disso, a autenticação quebrada devido a falhas de implementação pode comprometer os tokens de autenticação, ameaçando a identificação segura do usuário.
Problemas de consumo irrestrito de recursos e acesso descontrolado a fluxos de negócios confidenciais podem resultar em negação de serviço ou danos comerciais. Falhas de falsificação de solicitação do lado do servidor (SSRF) e configurações de segurança incorretas também aumentam a vulnerabilidade a ataques. A gestão inadequada do inventário de API e o consumo não seguro de APIs, especialmente de terceiros, representam riscos significativos à segurança, levando a padrões de segurança mais fracos e à exposição de pontos de extremidade obsoletos ou de depuração.
O versionamento de APIs é uma etapa essencial no desenvolvimento e manutenção de uma estrutura de TI eficiente. O processo de versionamento permite que alterações significativas na API sejam comunicadas de maneira clara e eficiente aos usuários, mitigando possíveis interrupções de serviços e conflitos de funcionalidades. A escolha de uma estratégia de versionamento deve considerar tanto a natureza da API quanto os requisitos dos usuários, e deve ser comunicada de maneira eficaz para garantir a transição suave entre versões.
Ao mesmo tempo, a segurança da API deve permanecer no centro das preocupações, com medidas robustas implementadas para evitar a exposição de dados sensíveis. Desta forma, os líderes de TI podem garantir uma evolução suave e segura das suas APIs, favorecendo o desenvolvimento ágil de aplicações e a melhoria contínua dos serviços.
