Como documentar API: passo a passo para otimizar integrações

Neste post escrito pelo dev da empresa Take Blip, Manoel Júnior, você acessa dicas de práticas e ferramentas de documentar APIs de maneira mais eficiente. Acompanhe!

Vivemos em um mundo digital cada vez mais integrado e conectado, com diversos serviços comunicando-se entre si e trazendo uma vasta quantidade de recursos e funcionalidades que aprimoram a experiência do usuário final na utilização de algum produto ou serviço.

A maneira mais usual de um sistema de TI possibilitar a integração e oferta de seus serviços é por meio de uma API (Application Programming Interface), que é um conjunto de rotinas e padrões que possibilitam a troca de informações entre sistemas variados e integram serviços, empresas, negócios e parceiros.

Uma integração bem sucedida passa pelo esforço de desenvolvedores e desenvolvedoras que criam soluções visando a plena comunicação entre os sistemas envolvidos.

Uma API bem construída deve facilitar este processo, para isso é preciso aprender como documentar API da maneira correta. O objetivo é apresentar uma documentação que permita que qualquer pessoa, que ainda não tenha pleno conhecimento do domínio da sua aplicação, desenvolva tais soluções de maneira rápida, eficaz e autônoma.

Como documentar API: primeiros passos

Nesse sentido, engajar devs é decisivo para o sucesso de sua API, e a documentação API é a principal ferramenta em que eles e elas se apóiam para utilizá-la — daí sua grande importância.

Sem documentar API de maneira adequada, a pessoa que vai utilizá-la perde tempo tentando desvendar seu funcionamento, o que cria barreiras para a adoção do seu serviço.

A API documentation deve ser bem completa e seu foco principal deve ser nos recursos e endpoints disponíveis.

A seguir, um passo a passo do que não pode faltar ao documentar API. Enumere-os e forneça informações como:

• Descrição da funcionalidade provida
• Parâmetros de entrada — aqui, é importante especificar quais são obrigatórios e quais são opcionais, bem como o tipo do valor esperado para cada um. Da mesma maneira, é importante deixar clara a forma como o valor é recebido (por querystring, pelo cabeçalho ou corpo da requisição, etc.)
• Formato da resposta (e.g. JSON, XML, etc.)
• Requerimento ou não de autenticação
• Limitação de uso
• No caso de uma API baseada no protocolo HTTP, especificação os métodos aceitos pelo endpoint
• Descrição dos possíveis retornos, tanto em caso de sucesso quanto os possíveis valores de erro — especifique, além dos códigos de erro, uma descrição que deixe claro o motivo pelo qual a requisição não pode ser atendida.

Abaixo apresentamos uma imagem da documentação API do Twitter.

O endpoint em questão retorna tweets públicos que correspondem a um ou mais filtros especificados. Perceba que é fornecida uma descrição textual do recurso, além de ser claro quais são os verbos suportados.

A URL do recurso é fornecida em destaque, bem como as informações sobre ele. Perceba que cada parâmetro é descrito em uma tabela contendo nome, se é ou não obrigatório e sua descrição.

Outra boa prática para documentar API é disponibilizar exemplos de uso, com modelos de requisições que possam ser utilizados facilmente. Se possível, mantenha um sandbox para que testes de integração possam ser feitos adequadamente e forneça informações sobre este ambiente na documentação.

De nada adianta construir uma boa documentação API se ela não é facilmente acessível. Disponibilize o documento em um ambiente de fácil acesso, como uma página web por exemplo.

Documentação API interativa

Até aqui, discutimos o processo de documentar API para a elaboração de um documento propriamente dito. Entretanto, em adição à documentação textual, existem hoje diversas ferramentas que permitem de maneira fácil a construção de interfaces de interação com sua API.

Essas ferramentas permitem testar as funcionalidades rapidamente e sem a necessidade de criar códigos. Aqui, vamos focar no Swagger, mas existem outras ferramentas de propósito parecido, como API Blueprint e RAML.

Swagger

O Swagger é uma poderosa ferramenta que ajuda devs a projetar, desenvolver, documentar e consumir serviços web RESTful.

Apesar de ser conhecida principalmente por sua interface Swagger UI, o software inclui suporte para:

• documentação API automatizada;
• geração de código;
• testes.

É uma ferramenta amplamente utilizada aqui na empresa Take Blip, em função de sua fácil integração com o código fonte. Ao mesmo tempo em que a API é criada, é possível documentar a API adicionando anotações no código fonte.

Existem 3 formas de documentar API pelo Swagger:

• Codegen: ao ser executado, o Swagger converte as anotações presentes no código fonte das APIs em documentação. A imagem abaixo mostra como essas anotações são feitas em um código escrito em C#.

• Automaticamente: permite gerar a documentação automaticamente ao mesmo tempo em que a API é desenvolvida.
• Manualmente: o próprio desenvolvedor ou desenvolvedora pode escrever de forma livre as especificações de sua API e publicá-la posteriormente.

Um bom exemplo de como funciona um servidor Swagger pode ser encontrado aqui. Este é um exemplo baseado em uma API de petstore e contempla:

• modelos;
• endpoints com diversas ações;
• autenticação.

A imagem abaixo mostra uma parte da interface do Swagger UI com os endpoints disponíveis.

Ao clicar em cada um deles, é possível executar a requisição preenchendo os parâmetros clicando no botão “Try it out”.

Note que ao final da página encontram-se os modelos das entidades envolvidas na API, contendo seus atributos com seus respectivos tipos. Dessa forma, a pessoa que utiliza esta documentação API sabe exatamente o que esperar nas respostas e o que enviar nas solicitações.

Como podemos perceber, existem diversas formas de manter uma API com um bom nível de documentação. Uma dica é se preocupar com este aspecto logo em sua concepção, para que o desenvolvimento da documentação e da API caminhem juntos.

Investir em interatividade, como vimos com o Swagger, é muito benéfico para as pessoas que desejam utilizar sua API, pois faz com que a integração seja mais dinâmica, rápida e de melhor qualidade.

E finalmente, mas não menos importante, após documentar a API é ideal “testa-la” para averiguar a sua capacidade de explanação.

Procure, se possível, pessoas que não participaram do desenvolvimento e obtenha feedbacks sobre o olhar delas para com a documentação e identifique as possíveis dúvidas e empecilhos que podem surgir.

Seguindo estas dicas e utilizando ferramentas adequadas para documentar API, é bem provável que seus parceiros e clientes irão obter uma boa experiência na integração com seus serviços, fazendo com que sua API tenha êxito em seu propósito.

Tem interesse em assuntos 4Devs? Então assine nossa newsletter e receba atualizações quinzenais sobre TI, inovação e mais temas!

Referências: iMasters, Sensedia, Wikipedia, I’d rather be writing, Sensedia