Já imaginou se existisse um jeito de documentar a sua API de forma organizada, com pouco trabalho, e ainda aproveitar essa documentação para realizar testes automatizados e verificar se a API cumpre com o que foi documentado, independentemente da linguagem que você utilizou para escrever seu back-end? Peraí…isso é possível? Siiim!! Utilizando a API Blueprint + Dredd!

 

API Blueprint

 

Ela é apenas um padrão de escrita, portanto não é necessário fazer o download de nenhum pacote externo. Você lê, entende os fundamentos, escreve um arquivo de descrição da sua API seguindo esse padrão, e pronto.

 

A parte importante disso é que ela tem uma curva de aprendizagem rápida. Existem outros padrões utilizados e conhecidos no mercado – como o Swagger , mas a API Blueprint é mais fácil de aprender, de escrever e de se ler. Além disso, se você já trabalhou em projetos onde times separados trabalham em partes diferentes do produto (como front-end e back-end), esse(s) arquivo(s) de Blueprint serve(m) como uma base para estabelecer um acordo entre as duas partes – como um serviço deve se comunicar com o outro.

 

Outro ponto importante é que existem ferramentas que trabalham em cima de documentos escritos utilizando esse padrão, como por exemplo o Dredd (que vamos tratar nesse artigo), ou outras como o Apiary, que gera uma documentação em HTML a partir do seu Blueprint.

 

Dredd

 

O Dredd é o foco principal deste artigo, e ao integrá-lo no seu processo de desenvolvimento, você traz as seguintes vantagens:

  • Sua API obrigatoriamente deve ser documentada utilizando o formato API Blueprint (ou Swagger, se preferir), o que traz todas as vantagens citadas anteriormente;
  • Testes automáticos são gerados baseados na documentação, com pouco ou nenhum trabalho;
  • Se você escrever a documentação da API antes de desenvolvê-la, você estará aplicando o conceito de Test Driven Development e como consequência trazendo as vantagens do mesmo, além de facilitar o desenvolvimento de outros serviços dependentes (como um front-end que será alimentado pela sua API) em paralelo.

 

Na minha opinião, essas vantagens valem muito a pena considerando que o esforço de implementação é mínimo.

 

Exemplo prático

 

Já que abordamos os conceitos e eu disse que o esforço de implementação é baixo, vamos para a prática!

 

Primeiro, vou criar a documentação de uma API que quero desenvolver (fazer esta etapa antes de começar a desenvolver é importante para projetos com times maiores, mas não é obrigatório). Neste exemplo vou criar uma API simples com respostas falsas, pois o foco do artigo é a documentação e os testes. Para isso precisarei de:

  • uma rota para listar todos os posts;
  • uma rota para obter informações de um post específico;
  • uma rota para listar todos os comentários;
  • uma rota para ver o meu perfil.

 

O documento em API Blueprint fica assim:

 

<script src=”https://gist.github.com/eduardotkoller/7d1573cfa019bdffd700d1c2d88cc27c.js“></script> (link para ver o código: https://gist.github.com/eduardotkoller/7d1573cfa019bdffd700d1c2d88cc27c)

 

Vou aproveitar e utilizar o json-server, uma ferramenta feita para criar APIs “de mentirinha” de uma forma muito simples e fácil: criando um arquivo json contendo coleções de itens. Se você não se interessa por isso, pode pular para a próxima seção.

 

O json-server faz todo o trabalho de gerar rotas baseadas nessas coleções. Para instalar o json-server, precisamos do NodeJS instalado, e executamos  

$ sudo npm install -g json-server     

 

O nosso json de coleções de itens fica assim:

 

<script src=”https://gist.github.com/eduardotkoller/6ec295adc0bd0017bfb099503a3e1d22.js“></script> (link para ver o código: https://gist.github.com/eduardotkoller/6ec295adc0bd0017bfb099503a3e1d22)

 

A partir disso, o json-server já cria todas as rotas que eu comentei que precisava (e até mais). Para executar o servidor, basta irmos até a pasta onde está este arquivo e executar  $  json-server db.json  e voilá, temos uma API simples mas funcionando. Para acessá-la, basta entrar em http://localhost:3000.

 

Agora vem a parte importante: Testá-la!

 

Certifique-se que sua API está funcionando, e execute os seguintes comandos:

 

$ sudo npm install -g dredd – para instalar o dredd na sua máquina (você precisa do nodeJS)

$ dredd <caminho até o arquivo de blueprint> <URL da sua API>

 

No meu caso, minha API está rodando e respondendo na URL http://localhost:3000, e chamei meu arquivo de blueprint.apib. Meu comando ficou desse jeito:

$ dredd blueprint.apib http://localhost:3000   

 

E o resultado:

 

api blueprint

 

É fácil assim! Nessa resposta, o Dredd informa quais rotas ele testou, quais passaram no teste e quais não, além do tempo de resposta.

 

O Dredd leu o arquivo Blueprint que escrevemos anteriormente (passamos ele como parâmetro para o comando dredd, além da localização da nossa API funcionando – no caso, http://localhost:3000) e testou todas as rotas que documentamos, verificando se as respostas têm o mesmo formato que especificamos no arquivo .apib (abreviação de API Blueprint, é um tipo de arquivo reconhecido pela W3C para essa linguagem).

 

É tão simples que parece até bom demais pra ser verdade, mas o conceito é que torna isso possível. Como o Dredd só vai realizar requisições para uma URL e verificar se ela responde de acordo, ele independe da linguagem em que seu back-end está escrito, o que torna o processo realmente simples.

 

Mas (sempre tem um mas…) as coisas não são tããããão simples assim quando se trata de APIs mais complexas, principalmente quando jogamos autenticação no meio da equação. Felizmente, o Dredd nos dá ferramentas para lidar com isso: hooks. Não irei entrar em detalhes neste artigo sobre isso, mas é importante entender o conceito – são pedaços de código que você escreve para serem chamados antes ou depois de chamadas para rotas que você especifica. Por exemplo, é possível fazer o Dredd realizar uma chamada para a rota de Login, guardar o token obtido, e passar este token como uma parte do header para todas as outras requisições. O importante aqui é que, apesar de não ser tão simples quanto o exemplo acima, não deixa de ser simples! Você pode encontrar mais informações sobre isso na documentação deles.

 

Enfim, espero que este artigo tenha passado uma noção do que é a API Blueprint e o Dredd, ambas ferramentas que podem organizar e facilitar não só o seu trabalho, mas também o de quem trabalha com você. Se você é fã deste tipo de coisa e quiser bater um papo sobre ferramentas, metodologias ou tecnologias, estou à disposição: eduardo@bossabox.com.

API Blueprint + Dredd: Como documentar e testar suas APIs
Avalie esse post
Você pode também gostar