02. Versionamento

Uma API é um contrato

Quando uma aplicação HTTP disponibiliza uma API de serviços Web para ser consumida por outras aplicações, é estabelecido implicitamente um contrato entre as duas. É responsabilidade do fornecedor do serviço não quebrar a compatibilidade da sua API. Alterar aplicações construídas sobre interfaces HTTP podem causar impacto para quem as consome.

No desenvolvimento de sistemas é comum não quebrar o que está funcionando. No entanto, um software ativo, está em evolução constante, ou seja, sempre está mudando. Para possibilitar a evolução do software, mitigando o impacto imediato nas funcionalidades utilizadas pelos clientes, é adotado um versionamento das APIs. Ao criar uma API de um serviço, é estabelecido uma versão para a interface da aplicação desenvolvida, prevenindo uma possível necessidade futura de alterar versões anteriores.

Quando uma API desenvolvida precisar ser alterada, será estabelecido uma nova versão para ela. Sempre que possível, o fornecedor do serviço suportará também aplicações clientes que usem versões anteriores à atual, evitando assim que as aplicações já feitas para essa API não sofram impacto. Pode ser estabelecido um período de suporte às versões antigas, pressionando as aplicações clientes para que atualizem para as novas versões. Não existe uma regra para o tempo ideal de suporte a versões anteriores, isso envolve muitos fatores que estão além do escopo deste documento.

Existem várias estratégias para fazer o versionamento de serviços, mas, este documento trata somente a forma usada no Bematech ERP. Esse modelo de versionamento á apenas uma convenção adotada e não é exigida pelo Framework.

APIs versionadas

Uma API HTTP consiste de um conjunto de URLs, os verbos HTTP suportados por elas, os parâmetros informados via URL, o formato esperado do corpo da requisição e o formato esperado do corpo da resposta. Esse conjunto de URLs e as ações associadas a elas são o que chamamos de roteamento e a essa definição deve ser dada uma versão. Para isso, por convenção se agrupa as URLs associadas a uma API sobre uma mesma URL base acrescida de um número de versão. Abaixo segue um exemplo de rotas de uma API cuja URL base é “/api/operacoes” e está na versão 1.

/api/operacoes/v1/pedido/:id/cabecalho

/api/operacoes/v1/pedido/:id/itens

Uma mudança de versão de um recurso é necessária somente quando houver perda de compatibilidade da API alterada com as aplicações clientes já existentes. A adição de novos comportamentos, em geral, não exige a mudança de versão, pois as aplicações clientes que não fazem uso desse comportamento não sofrerão impacto. Essa estratégia permite que o sistema evolua sua APIs de forma rápida, algumas vezes transparentemente para as aplicações clientes. No entanto, uma aplicação cliente que se utilize de recursos recém-disponíveis numa versão nova do sistema, falhará ao tentar acessar uma outra base de dados que, apesar de publicar a mesma versão de API, não está com última versão do Bematech ERP. Ao adotar a política de atualização mensal, os clientes não serão prejudicados por esse comportamento.

É recomendado que, ao criar uma nova versão, seja mantido inalterado os comportamentos existentes na versão anterior, reduzindo o impacto na migração das aplicações clientes já desenvolvidas para a nova versão.

Alterações que não requerem uma nova versão

• • Novos recursos

  • Novos métodos HTTP em recursos existentes

  • Novos formatos de dados suportados

  • Novos atributos e elementos em existentes tipos de dados

Alterações que requerem uma nova versão

• • URL’s renomeadas ou removidas

  • Dados diferentes retornados por uma mesma URL

  • Removido suporte para um determinado método HTTP para uma URL existente.

Versão da API e a evolução do modelo de dados

O modelo de dados do Bematech ERP pode ser alterado pela Bematech, parceiros ou pelos clientes. As modificações podem ser a criação de campos, a alteração dos existentes ou a exclusão deles. Também podem ser criadas, alteradas ou removidas validações e sugestões de valores nos eventos do modelo de dados. Essas mudanças podem ocorrer a cada versão do Bematech ERP, mas alterações com essas naturezas não irão alterar a versão das APIs HTTP.

A maioria dessas mudanças não deverão alterar as APIs existentes, pois, normalmente, campos novos são opcionais. No entanto, algumas mudanças podem exigir a revisão dos clientes consumidores da API, como: criar campos obrigatórios, tornar campos somente para leitura, excluir campos utilizados pela API cliente, adicionar novas validações de regras de negócio ou integridade. Para todos esses casos será retornado um erro HTTP.

A princípio, esse é um comportamento indesejado, pois uma vez que a versão da API estabelece um contrato, ele deveria ser respeitado. No entanto, mudanças no modelo de dados, como a adição de campos requeridos, podem ser exigências de uma nova regra de negócio e não faria sentido permitir que as APIs introduzissem dados inconsistentes com as regras estabelecidas pelo negócio. Além disso, mudanças do modelo de dados fogem do controle do criador da API. Por exemplo, se um cliente ou um parceiro tornar um campo requerido por meio de uma customização, não seria possível a Bematech evoluir a versão de uma API que faz parte do produto, visto que ela nem tomará conhecimento dessa alteração.

Estruturas mais voláteis, como as classes de dados, que podem alterar a cada versão do Bematech ERP, poderão ser consultadas em tempo de execução por meio da API de Classes. Nela é possível consultar o modelo de dados de uma classe, de forma similar ao método classDefManager.getModelDef().

Por motivos que vão além das APIs HTTP, é importante que os desenvolvedores responsáveis pela definição do modelo de dados avaliem os impactos das mudanças, sempre que possível sugerindo valores que antes não eram exigidos, quando isso for possível. Mudanças que produzam impactos aos usuários ou consumidores das APIs sempre devem ser documentadas por meio de publicações técnicas da versão.

< Recursos Página anterior | Próxima página Declaração de Controladores e das Rotas >