APIs e Microsserviços

18 set, 2014

Review: Apiary – Fazendo muito mais que apenas documentar

Publicidade

Há algum tempo, venho trabalhando diretamente com APIs de diversos tipos. Tanto APIs públicas abertas, quanto fechadas. Em partes, meu trabalho está na criação de documentações, SDKs e artigos técnicos para utilização e consumo.

Uma das maiores dificuldades na criação de documentação de API, além, claro, da manutenção, é a ilustração de sua utilização para o desenvolvedor que está tento o primeiro contato com ela. Ao iniciar a integração, é natural que o desenvolvedor precise, por exemplo, saber como suas requisições HTTP estão sendo recebidas pela API e qual está sendo a resposta da API, para aquela requisição específica.

Ilustrar o recebimento da requisição e a resposta para essa requisição, em uma documentação, não é uma tarefa simples. E é justamente nesse ponto que o Apiary mostra sua força.

Primeiro contato

Eu já tinha uma conta no Apiary há algum tempo, mas apenas recentemente fui realmente utilizá-lo para um caso de uso em produção. A interface do Apiary é bastante simples e a organização facilita sua utilização:

ri01

De um lado, temos o conteúdo da API. A separação por recurso/verbo HTTP simplifica tanto a criação da documentação para aquele recurso/verbo, quanto o entendimento daquilo que está sendo documentado. Algumas documentações podem ter diversos recursos e o ToC no lado direito facilita a navegação entre os recursos.

Documentação facilitada

A ferramenta já seria excelente, por cumprir muito bem seu propósito de documentar. Mas como manter a documentação é uma tarefa, talvez, ainda mais complexa que escrever a documentação, o Apiary oferece a integração com um repositório no Github.

Isso significa que podemos escrever toda a documentação em Markdown e, ao fazer push para o repositório, a documentação no Apiary é atualizada automaticamente.

Ambiente de testes

Pronto, escrevi a documentação da minha API. E agora?

Apesar de o Apiary ter a documentação como foco, o ponto mais forte, na minha opinião, é o Mock Server. Ao definir os recursos da API e os verbos, podemos também definir o que é esperado para determinada requisição HTTP e qual será a resposta, se a requisição for feita corretamente.

O Mock Server é composto por dois ambientes distintos:

  • O próprio Mock Server, para onde devemos enviar as requisições de teste.
  • O Traffic Inspector, que monitora as requisições feitas para o Mock Server.

Para localizar a URL do Mock Server, basta observar a coluna da direita, logo abaixo a tabela de conteúdo. Será alguma coisa como: netojoaobatista.apiary-mock.com.

Uma vez localizada a URL do Mock Server, basta fazer uma requisição HTTP como documentado na sua API. Assim que a requisição for feita, basta verificar o Traffic Inspector, para ver como ela chegou na API e qual foi a resposta dada pela API:

ri02

Prós

  • A interface é simples e intuitiva. Muito fácil de utilizar.
  • Permite a utilização de Markdown para a documentação.
  • É possível documentar cada verbo HTTP de cada recurso.
  • É possível descrever como serão as requisições e respostas HTTP.
  • O Mock Server e Traffic Inspector facilitam a integração, ao ilustrar como a requisição foi recebida e o que foi retornado. Permite, ainda, mostrar se a requisição foi bem sucedida ou se houve algum erro.
  • Permite integração com Github, tanto com repositórios públicos, quanto privados.

Contras

  • O Mock Server é bastante rígido com o que foi especificado. Se você colocou 3 espaços na documentação, então a requisição deve ser feita com 3 espaços.

Conclusão

Se você está desenvolvendo uma API e precisa documentá-la, o Apiary é, certamente, uma excelente ferramenta. A facilidade de escrever e manter a documentação, já seriam argumentos o suficiente para sua utilização. Mas o Mock Server + Traffic Inspector são o algo mais. Documentação de API é algo feito para o desenvolvedor. O que melhor, então, para o desenvolvedor, que oferecer um ambiente para ele “brincar” com sua API, enquanto lê a documentação?

***

Artigo publicado na revista iMasters: http://issuu.com/imasters/docs/rim11-issuu_11