Acompanhe o nosso guia e descubra a importância de documentar uma API e tenha acesso a boas práticas para realizar essa atividade de forma eficiente!

API's vem da abreviação do termo "Application Programming Interface" e, como o próprio nome diz, com elas, é possível criar interfaces para que sejam feitas integrações entre um ou mais sistemas.

Por meio das API's, dois sistemas escritos em diferentes linguagens conseguem trocar informações com facilidade.

Nesse cenário, um aspecto importante a ser levado em consideração é a documentação de API.

A documentação permite que desenvolvedores tenham uma visão mais clara do seu produto e de como o seu código pode funcionar em conjunto com o software deles.

Neste artigo, trouxemos algumas dicas importantes para te ajudar ao escrever a sua documentação de API. 

Além disso, abordaremos os principais problemas a serem considerados ao projetar sua própria documentação, independentemente da maneira que você distribua o seu aplicativo.

Quer saber como melhorar/criar a documentação de uma API? Acompanhe o nosso post!

Por que e como documentar uma API?

A documentação de uma API é uma entrega técnica de conteúdo, contendo instruções sobre como usar e integrar efetivamente a solução.

É um manual de referência resumido que contém todas as informações necessárias para trabalhar com a API, com detalhes sobre: 

• funções; 
• classes; 
• tipos de retorno; 
• argumentos;
• tutoriais de exemplos.

Tradicionalmente, a documentação de uma API é feita usando exemplos práticos que sejam facilmente identificados.

Ao se deparar com a API, o usuário vai procurar informações acessíveis, claras e completas para que possa integrar algum sistema.

No desenvolvimento da documentação não se pode pular etapas, pois esse é o caminho para aumentar as integrações e o número de usuários, garantindo assim o sucesso. É ela que vai mostrar as funções e vantagens da sua API.

Independentemente da função ou objetivo da API, existem alguns critérios básicos que toda API deve ter em sua documentação.

6 boas práticas para documentar uma API

Deixar de elaborar qualquer um desses recursos pode ter efeitos drasticamente negativos na adoção, compreensão e usabilidade. Para que isso não aconteça, trouxemos 6 boas práticas a respeito do assunto, confira!

1. Elabore uma documentação completa

É preciso lembrar que a documentação deve conter todo conteúdo que auxilie os usuários e desenvolvedores a interagir com a sua API. Por causa disso, é importante detalhar todos os dados.

Observação: cada API pode ter particularidades diferentes, por isso, avalie o caso em específico.

Parta da premissa de que quanto menos tempo de pesquisa externa por parte do desenvolvedor, melhor. Neste sentido, boas dicas seria:

• Enumerar os endpoints e parâmetros;
• Informar todas as funcionalidades detalhadamente;
• Elaborar tutoriais e termos de uso, quando necessário.

2. Disponibilize muitos exemplos

É muito interessante que você utilize diversos  exemplos de código para que o desenvolvedor faça a ligação entre o conceito que você está passando e sua aplicação prática na API de forma rápida.

O ideal é que a sua documentação seja desenvolvida da forma mais acessível e no maior número de linguagens possível para o maior número de desenvolvedores, além do mais, não é possível conhecer todo o público que utilizará a documentação.

3. Centralize informações

Outro ponto que merece destaque é centralização das informações, ou seja, evite redundâncias, vá direto ao ponto. 

Evite dividir a documentação em várias páginas sobre o mesmo assunto, faça de forma que seja completa e concisa.

Uma boa prática nesse tema é tentar manter os tópicos que possuam relação mais próximos uns aos outros em uma mesma página, isso reduz o tempo de procura a respeito de um determinado assunto.

4. Fique atento às mensagens de erro

Erros durante e a após a documentação poderão acontecer, e isso fará com que você perca muito tempo tentando resolvê-los.

Portanto, para facilitar, uma boa dica é substituir as mensagens de erro genéricas por mensagens explicativas ou referenciadas por códigos que tenham explicação na sua documentação.

5. Invista em interatividade

Viabilizar que os usuários possam interagir com a API a partir da sua documentação e vice-versa fará com que o desenvolvedor passe a entender mais rápido a documentação e comece de pronto a utilizar as ferramentas.

Esse tipo de experiência é mais positiva pois traz maior dinâmica e deixa as integrações mais rápidas e com melhor qualidade.

6. Teste sua documentação

O óbvio precisa ser dito: sua documentação precisa ser coerente e possuir dados concretos.

Portanto, crie uma fase de testes. Avalie tudo que foi colocado sobre sua API e, se possível, conte com uma equipe de desenvolvedores que não participou do desenvolvimento dela, pois eles terão um olhar diferente de quem já estava trabalhando no projeto.

Quais os principais problemas ao documentar uma API?

Este de fato é um cenário abrangente, mas reunimos algumas dicas abordando os principais tópicos que costumam gerar dúvidas no momento de documentar uma API. Veja:

Estrutura abrangente

A estrutura abrangente da documentação pode ser a parte mais difícil de corrigir. Por isso, procure uma estrutura clara e intuitiva.

Isso proporcionará um grande alívio não apenas aos desenvolvedores iniciantes, mas também aos colaboradores internos que esperam manter a consistência à medida que adicionam novas informações à documentação. 

Para vencer essa barreira, siga as 3 dicas que trouxemos abaixo:

1. Invista em uma introdução sólida

Você provavelmente gastou centenas, senão milhares de horas desenvolvendo seu produto e suas plataformas. Mas lembre-se de que seus usuários não. Mesmo questões que parecem básicas para você podem não ser tão intuitivas para um novo cliente.

Portanto, use a introdução para familiarizar um novo usuário com os conceitos básicos de seu serviço e sua plataforma, seja um sistema operacional como o Android ou uma linguagem como Java ou Swift.

A documentação do Sendbird fornece um exemplo. A API da plataforma fornece uma seção de início rápido, onde são introduzidos alguns conceitos básicos que auxilia alguns programadores menos experientes, veja:

Observação: Neste caso, a documentação ignora os detalhes sobre a configuração da API com cartões de crédito, usuários, cobranças e assinaturas.

Ações como essa são interessantes pois permitem, por exemplo, que um desenvolvedor experimente uma implementação funcional.

3. Evite categorizações excessivas

Pode ser tentador subcategorizar tudo em grupos lógicos. Entretanto, evite o aninhamento excessivo.

Veja só o seguinte exemplo:

1. Mensagens

    1.1 Enviando mensagens

        a. Enviando mensagens de texto

        b. Enviando arquivos

            i. Enviando arquivos binários

                * Multipart requests

                * Usando multipart requests para enviar arquivos binários

O primeiro problema de escritas como essa é que elas tornam as seções difíceis de se localizar. 

Um menu de navegação lateral, por exemplo,  não seria capaz de exibir seções aninhadas com mais de 2 níveis, apesar de em alguns casos ser interessante estender um único nível.

O segundo problema está relacionado ao bom design. Como você distinguiria todos os cabeçalhos - h1 a h6 - para que os usuários pudessem saber intuitivamente onde eles estão na documentação?

Portanto, uma solução seria fazer da seguinte forma:

1. mensagens

    1.1 Enviando mensagens de texto

    1.2 Enviando arquivos

        a. Enviando arquivos binários

          (+ defina os multipart requests com um parágrafo sem título)

Desta forma, ao nivelar a estrutura do seu documento, você encontra um equilíbrio entre categorização e localização. 

Seria lógico agrupar "enviar mensagens de texto" e "enviar mensagens de arquivo", mas a simplicidade sai muito mais em conta para um desenvolvedor que procura encontrar uma solução para um problema no menor tempo possível.

Formatação

A documentação moderna traz grande importância ao design e formatação. Neste sentido, tome como exemplo os documentos da API do Gmail:

• As caixas coloridas incluem notas importantes.
• A documentação destaca os principais caminhos nos terminais.
• As tabelas apresentam informações de maneira concisa e legível.
• A referência da API do Stripe é bem projetada. 
• O layout de duas colunas maximiza o espaço na tela.

Sendo assim, ao planejar seus próprios documentos, imagine como os itens devem ser exibidos. Lembre-se de que os elementos projetados devem ser reutilizáveis e consistentes em diversos contextos.

Dentro desse contexto, confira 3 boas práticas que te ajudarão nesse processo:

1. Lightweight Markup Language (LML) é uma boa opção

Como a documentação, geralmente, é renderizada em um site, ela é baseada em HTML. No entanto, o uso de HTML bruto para escrever documentação é demorado e propenso a erros.

Um LML como o Markdown, por exemplo, torna a escrita para a Web mais rápida e eficiente.

Digamos que você tenha um cabeçalho, um parágrafo e um link dentro do parágrafo. Em HTML você teria algo parecido com isto:

<h1> Cabeçalho aqui </h1>

<p> Consulte este <a href="https://www.example.com/"> link </a> para obter uma descrição mais detalhada. </p>

Compare isso com o mesmo conteúdo escrito em Markdown:

#Cabeçalho aqui 

Consulte este [link] (https://www.example.com/) para obter uma descrição mais detalhada.

2. Faça tudo em uma página (a menos que você tenha uma boa razão para extrapolar)

O porquê disso é muito claro. Ninguém deseja clicar em três links aninhados para encontrar a resposta para uma pergunta simples. 

Desde que você tenha uma barra lateral listando todas as seções, uma única página de documentação permite obter uma visão panorâmica.

Um exemplo disso é a plataforma do Parse Android.

3. Use tabelas

A documentação do código contém muitas informações. O uso de tabelas transmite esses dados de forma sucinta, especialmente para parâmetros e variáveis de código.

Neste caso, o recomendado é usar uma estrutura de 4 colunas para documentar solicitações e respostas teste.