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

A sigla API, em inglês, quer dizer “Application Programming Interface”. Na prática, APIs podem integrar um ou mais sistemas. O fato é que já usamos esses em nosso dia a dia, podendo integrar softwares e aplicativos com diferentes linguagens, viabilizando uma série de recursos.

Neste contexto, a maneira mais comum de um sistema possibilitar a integração e oferta de seus serviços é por meio de uma API, que é um conjunto de rotinas e padrões que possibilitam trocar informações entre sistemas variados e integram serviços, empresas, negócios e parceiros.

Por exemplo, é por meio de uma API que você consegue utilizar o WhatsApp em uma plataforma como o Blip. Com isso, o objetivo é justamente fazer com que os dois sistemas possam interagir entre si. Além da API do WhatsApp, existem muitas outras aplicações que podem ser utilizadas de exemplo, como a API do Google Maps.

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

Mas para ter uma API bem construída e que facilite o processo, é muito importante saber como documentar API corretamente.

Continue a leitura e aprenda como criar uma documentação que permita a qualquer pessoa entender o que acontece no conjunto de padrões de uma API.

Como documentar API: primeiros passos

Antes de mais nada, engajar devs é decisivo para o sucesso de sua API, e a documentação API é a principal ferramenta em que eles e elas se apoiam para utilizá-la — daí sua grande importância.

Sem documentar API adequadamente, um usuário pode perder 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. Application 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.

Para entendermos na prática, vamos analisar a 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, a obrigatoriedade e sua descrição.

Outra boa prática ao documentar APIs é 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.

Além disso, de nada adianta construir uma boa documentação API se ela não é facilmente acessível. Logo, 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 algumas ferramentas que permitem facilmente 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 os profissionais 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 em Blip, por exemplo, principalmente 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.

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 quem deseja utilizar sua API, pois faz com que a integração seja mais dinâmica, rápida e de melhor qualidade.

Por fim, depois de documentar a API, o ideal é fazer testes para conferir a 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 possam 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.

Quer continuar aprendendo sobre assuntos técnicos como este? Acesse a nossa central de ajuda e aprenda tudo que precisa saber!