Vários são os motivos que levam à exposição de funcionalidades do negócio na forma de uma API. Mas seja qual for o objetivo de uma API, com certeza ela existe para que outras pessoas possam usar seus recursos de forma autônoma.

Engajar desenvolvedores é um dos fatores determinantes para o sucesso de sua API, e uma parte importante para engajamento de desenvolvedores é a documentação da API. Uma API bem documentada melhora a experiência do usuário, acelera integrações, amplia o alcance, incentiva a propaganda boca a boca e, consequentemente, aumenta o índice de felicidade de todos os envolvidos.

Documentar uma API pode não ser tão simples, pois é mais do que oferecer um conjunto de páginas html falando de como fazer a autenticação, quais são os tipos de retorno possíveis e o que cada recurso faz. Documentar passa por fornecer uma experiência visual e interativa com a API, permitindo que funcionalidades sejam testadas “ao vivo”.

A boa notícia é que existem várias ferramentas e estratégias que ajudam a criar uma boa documentação interativa para os recursos da sua API.

Nesse sentido, existem três especificações principais:

Swagger, liderada pela Reverb (e, mais recentemente, pela Smartbear), tem a maior e mais ativa comunidade de desenvolvedores, parte disso em função de ser a mais antiga no mercado.
API Blueprint, encabeçada pela Apiary, tem um website bonito e intuitivo, no qual é fácil encontrar o projeto de interesse.
RAML, padrão aberto suportado por um grupo de developers que inclui pessoas da MuleSoft, AngularJS e PayPal. É o mais intuitivo para começar a escrever a documentação.

Cada uma delas tem foco em determinados aspectos, como design, integração com outras ferramentas, legibilidade, curva de aprendizado etc. Vamos ver cada uma em detalhes.

Swagger

Essa especificação foi construída com base no próprio JSON (suporta também XML), o formato mais popular para APIs no estilo RESTful, o que traz à documentação uma familiaridade confortável. Além da especificação, o Swagger é um framework completo para descrição, consumo e visualização de serviços RESTful.

O grande objetivo dos criadores do Swagger foi permitir que a documentação evoluísse no mesmo ritmo da implementação, já que pode ser gerada automaticamente com base em anotações do código, porém essa nem é uma característica muito explorada atualmente.

Foi originalmente criada em 2011 pela Wordnik (dicionário de inglês online) para uso interno em suas próprias APIs, mas mostrou-se especialmente útil por atender, ao mesmo tempo, a necessidades de documentação/sandbox, do cliente e do servidor.

Tem um módulo de UI que permite aos developers interagirem com as APIs em sandbox de forma muito intuitiva, sem exigir conhecimento da implementação ou mesmo dos parâmetros e opções (que são explícitas na documentação).

Existem basicamente três formas de criar uma especificação do Swagger:

Codegen: ao ser executado, o aplicativo swagger codegen converte as anotações do código-fonte das APIs em documentação.
Automaticamente: alguns servidores, como o swagger-node-express e o swagger-play, poderm criar, ao mesmo tempo, a documentação e as APIs.
Manualmente: de forma totalmente livre, é possível escrever manualmente os arquivos JSON com a especificação swagger das APIs e publicá-los no seu próprio servidor ou em algum dos disponíveis, como o node.js server generator.

API Blueprint

É uma especificação baseada em Markdown, o que pode ser uma vantagem para diminuir a curva de aprendizado de alguns e confundir outros, que vão precisar de uma boa imersão nos tutoriais disponibilizados pela Apiary.

Ela se propõe a cuidar, além do design, de aspectos relacionados ao ciclo de vida da API, possibilitando que seja usada para fomentar discussões e gerar uma suíte de testes rapidamente (tem ferramentas disponíveis para isso).

O grande objetivo da especificação é torná-la legível para humanos, o que conduzirá a fácil colaboração e rápida prototipação.

Apesar de ter uma empresa à frente da especificação (Apiary), seu parser e a maioria das ferramentas são open source, então ovendor lock-in não deve ser uma preocupação. Por outro lado, a quantidade de contribuidores é razoável (são 34 membros enquanto escrevo este artigo), mas as contribuições extremamente focadas em apenas dois developers.

RAML

Quando você ainda não definiu sua API, e quer uma ferramenta que ajude a fazer o design, o RAML pode ajudar. Ele possui um editor interessante e permite o desenho de APIs quase-RESTful, ou seja, aquelas que não seguem exatamente o estilo RESTful (isso pode ser uma vantagem, ou não!).

À parte dos nomes da indústria que apoiam essa especificação, o RAML é aberto e usa padrões como o YAML (formato para serialização de dados) e o JSON. O foco da especificação é em:

Clareza: a descrição dos recursos, métodos, parâmetros etc. deve estar explicitamente manifestada na documentação.
Corretude: a documentação é o contrato da API e deve refletir exatamente o seu comportamento.
Precisão: deve ser possível gerar um cliente seguindo rigorosamente o que está definido na documentação.
Consistência: a especificação encoraja o reuso, permite descoberta e compartilhamento de padrões, sempre mirando a adoção das melhores práticas.
Legibilidade e facilidade para escrita: está organizada de forma que seja fácil para um humano ler – e escrever – a documentação diretamente no código.
Ser intuitiva e natural: com o objetivo de facilitar o desenho da API, tenta ser o mais próxima possível do modelo mental que um humano usaria descrevendo para um amigo, em um e-mail, como seria sua API.

Ela foi criada de olho na demanda latente de design-first. Se você tem uma ideia e quer rapidamente desenhar uma API para validá-la, o RAML é sua escolha mais natural. O RAML não garante um bom design para sua API, mas é simples, sucinto e consegue capturar sua essência.

Quick takeaways

Developers não querem apenas saber o que um recurso faz, eles querem interagir com ele e saber o que acontece com uma chamada na hora.
Se é pra ser fácil de humanos normais lerem e escreverem, vá de RAML (YAML). Mas tenha em mente que developers não são humanos normais.
A especificação Swagger é, sem dúvida, a mais completa, o que não significa que é a mais apropriada para você.
Markdown nunca foi e nem será intuitivo, por mais que os entusiastas digam o contrário. É uma linguagem que precisa ser aprendida assim como qualquer outra.
Não existe escolha certa ou errada, desde que sejam entendidas as nuances de cada especificação, seus principais objetivos, ferramentas disponíveis, comunidade envolvida etc.
A recente “aquisição” do Swagger pela Smartbear, comentada acima entre parênteses, é um movimento bem importante para o mercado. Stay tuned!

Correndo por fora, existem ainda outras especificações, como IO Docs, Mashape e WADL, mas isso é assunto para outros artigos.

Se quiser saber como fazer um bom design para sua API, confira nosso Webinar de Design de APIs RESTful. Então, vamos colocar sua API na rua?

Referências:

De 0 a 10, o quanto você recomendaria este artigo para um amigo?

Powered by:

Documentar API é preciso (e as ferramentas estão aí)!

José Vahl

Swagger

API Blueprint

RAML

Quick takeaways

José Vahl