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:

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:

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