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 de João Batista Neto, publicado originalmente no iMasters.
