Boas práticas para documentação de APIs

Neste post escrito pelo dev da Take, Manoel Júnior, você acessa dicas de práticas e ferramentas para realizar uma boa documentação de APIs. 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, apresentando 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.

Primeiros passos para fazer uma boa documentação de APIs

Nesse sentido, engajar devs é decisivo para o sucesso de sua API, e a documentação é a principal ferramenta em que eles e elas se apóiam para utilizá-la — daí sua grande importância. Sem uma documentação 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 documentação deve ser bem completa e seu foco principal deve ser nos recursos e endpoints disponíveis. 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.

A imagem abaixo mostra uma imagem da documentação 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.

documentação de apis 1

Outra boa prática é 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 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 interativa

Até aqui, discutimos o processo de documentação como 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

documentação de apis 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 automatizada, geração de código e testes.

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

Existem três formas de criar documentação 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#.

documentação de apis 3

  • 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 e até mesmo 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”.

documentação de apis swagger petstore

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 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, é ideal “testar” a documentação desenvolvida 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, é 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

manoel post documentação de apis

Manoel Júnior

Estagiário de Desenvolvimento na Take

 

Leia mais:

Inteligência Artificial: desafios e oportunidades do mercado

Expectativas das empresas com TI: como apresentar o setor?

Front-end ou Back-end: entenda qual área você deve seguir