API First: Uma Breve Reflexão

À primeira vista, é uma boa ideia manter sua API de serviços documentada usando arquivos isolados em formatos como Swagger, Raml ou OpenApi.

Mas com que frequência seus serviços mudam?

E quanto tempo é gasto refletindo essas alterações na documentação da API?

Como você pode ter certeza de que sua API é compatível com sua implementação?

O API First vem para responder a essas perguntas e trazer fácil manutenção à documentação da sua API. A principal preocupação é iniciar todas as alterações pela documentação da API, em vez da alteração do código-fonte.

A princípio, pode parecer um trabalho adicional desnecessário, porém, do ponto de vista da engenharia de software, quanto mais cedo as mudanças são planejadas e validadas, torna-se mais barato e mais rápido qualquer ajuste, melhorando o tempo e o esforço empregados.

Documentação da API: diferentes abordagens

Existem algumas formas mais comuns de se documentar APIs, como:

Mantendo a documentação em paralelo

O caminho mais comum é manter a documentação da API em um arquivo junto com o código-fonte da aplicação.

A desvantagem dessa solução é que sempre que você precisar fazer alterações, elas precisarão ser refletidas em dois lugares.

Isso torna mais difícil garantir que sua documentação esteja correta, exigindo muitos testes automatizados para validar a especificação em relação à implementação.

Documentação em código-fonte

Embora possa reduzir as chances de uma documentação desatualizada, não há garantia de que mantê-la misturada no código-fonte reflita com precisão a implementação.

O principal benefício é definir um local comum para ambos, mas também serão necessários testes para garantir que a documentação esteja correta.

Código-fonte gerado com base nas especificações da API

Essa abordagem permite que os desenvolvedores economizem muito tempo na implementação, teste e manutenção do código-fonte.

Além disso, o código-fonte gerado com base na especificação da API (na maioria dos casos) estará pronto para produção, pois o próprio gerador de código-fonte é mantido e testado como outro projeto.

Se um projeto precisar ser migrado para outra stack ou linguagem de programação, novamente, basta utilizar a geração de código-fonte, agora, compatível com a nova solução.

Um desafio adicional criado por essa abordagem é manter o código customizado compatível com o código-fonte gerado automaticamente. É importante seguir algumas regras relacionadas à organização e merge de código-fonte no projeto (por exemplo, convenções de pacotes, interfaces, etc.).

Outra limitação está relacionada à stack e a versão da linguagem de programação disponibilizadas pelo gerador de código-fonte escolhido.

Esta abordagem expõe a busca de equilíbrio e bom senso entre a necessidade de controle e independência total sobre o código-fonte versus quanto tempo se está disposta a perder implementando código-fonte genérico.

Compartilhando sua API

Para evitar mal-entendidos, é muito importante fornecer a mesma documentação da API tanto para os desenvolvedores, quanto para os clientes externos da API. Manter a mesma fonte para todos economiza muitas dores de cabeça em relação a versões e atualizações.

Melhor ainda é ter a documentação disponível na Internet com controle de acesso (se essa não for uma API pública).

Mantenha suas especificações de APIs na nuvem

Ter especificações de API hospedadas em serviços baseados na nuvem (por exemplo, swaggerhub.io ou postman.com) pode facilitar muito as coisas, com funcionalidades como: gestão de trabalho colaborativo, histórico de alterações, controle de versão, controle de acesso, simulador de API, integração com serviços de gerenciamento de código-fonte, alta disponibilidade e uma maneira melhor de editar e compartilhar seu conteúdo.

Além das APIs

Da mesma forma que o uso de interfaces define o contrato e o comportamento nas classes que as implementam, a especificação de APIs pode e deve ser usada para definir um contrato de serviço antes de qualquer implementação.

Todos os conceitos de uma aplicação e seus endpoints podem ser concebidos antes de se implementar uma única linha de código, permitindo focar nas reais necessidades de seus serviços.