Um Guia de como documentar uma API, com boas práticas! Um Guia de como documentar uma API, com boas práticas!
Um Guia de como documentar uma API, com boas práticas!
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:
tipos de retorno;
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.
Outro fator importante é detalhar as últimas atualizações e as implicações no uso, pois isso ajuda a entender a estabilidade da API no momento da integração.
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.
Como exemplo, observe como funciona o código de erros da API do eNotas Gateway:
Neste caso, a API retorna Códigos de Status HTTP para indicar sucesso ou falha da chamada.
Em geral, os códigos iniciados com:
2xx indicam sucesso;
4xx indicam erro (Ex: Falta de parâmetro obrigatório ou Falha ao autenticar);
5xx indicam erro interno nos serviços do Gateway.
Outros possíveis retornos são:
Observação: Se quiser ter acesso a mais tipos de respostas (informativa, de sucesso, erros) basta consultar a documentação do Mozilla para uma referência mais completa.
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:
E neste momento você pode se perguntar: "Quem não sabe sobre segurança de URL?" Mas garanto que ficaria surpreso com quantos relatórios de erros poderiam ser cortados pela raiz com adições tão simples!
Claro, sempre existe o perigo de explicar coisas que realmente não precisam de explicação. Mas é melhor prevenir do que remediar, não?
Entretanto, procure mais por instruções do que redundância, seja direto e claro. Explicações desnecessárias devem ser evitadas tanto quanto excluir conceitos básicos.
Se ajudar, imagine que você é um instrutor em uma sala de aula ensinando os alunos nessa disciplina. O que ajudaria o aluno a desenvolver esse processo?
2. Deixe seu leitor experimentar o recurso principal o mais rápido possível
Ao disponibilizar áreas de testes, você entrega confiança e permite que o usuário tenha uma breve experiência com a ferramenta, o que gera um ponto positivo à sua documentação.
O Firebase Database, por exemplo, disponibiliza um banco de dados em tempo real. Caso tenha interesse, basta você acessar o guia de instruções na página oficial do aplicativo.
Por lá, você conseguirá diversos passo a passos para executar as principais atividades, inclusive consultar a biblioteca disponível, veja:
Dica: Você não deseja que os usuários aprendam sobre o envio de arquivos criptografados antes de aprenderem sobre a configuração da API. Então, dê a eles um ponto de partida para que eles possam tentar os recursos avançados por conta própria.
Dentro desse cenário, o Stripe fornece um exemplo brilhante, veja só:
- Vá para a página de documentos: https://stripe.com/docs e crie uma conta.
- Você verá imediatamente uma seção interativa "Experimente agora", que permite testar a API de pagamento em alguns minutos.
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.1 Enviando mensagens
a. Enviando mensagens de texto
b. Enviando arquivos
i. Enviando arquivos binários
* 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.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.
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.
Você pode ver que o Parse contém componentes como "Usuários", "Objetos" e "Sessões" fáceis de encontrar e sem a necessidade de consultar um "índice" separado, ou ter de usar o "ctrl+F".
Mas digamos que você tenha uma API extensa. A compactação de todas essas informações em uma única página seria inconveniente e levaria a um carregamento lento da página.
Neste caso, um ótimo exemplo a seguir são os documentos de API do GitHub. Eles mantêm uma barra lateral persistente, mas carregam cada documento em uma única página.
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.
Marcação1
O horário em que o usuário recebeu sua primeira mensagem
Em milissegundos
O Sendbird segue uma estrutura semelhante, mas usa 3 colunas, optando por mesclar "descrição" e "marcação".
Vale lembrar que tabelas com muitas colunas não costumam ser bem exibidas em sites. Portanto, você deve encontrar um equilíbrio entre adicionar colunas e escrever coisas em uma coluna geral de "descrição".
Para isso, você deve escolher entre uma uma coluna de "parâmetro obrigatório", Uma coluna de "valor padrão", ou apenas adicionar uma de "descrições". A melhor opção irá depender do design da sua API.
Você pode achar que a gramática envolvida na redação técnica é um pouco entediante e, bem, excessivamente técnica. Bom, para isso trouxemos mais 3 boas práticas para te auxiliar nesse processo:
1. Dirija-se ao leitor usando "você" e use a voz ativa
Agora é convencional abordar o leitor com "você". Olhe para o gigante da internet local, o Google. "Você" é abundante em sua documentação e também o incentiva a escrever na voz ativa.
Como sua documentação é um manual de instruções para um desenvolvedor individual fazer algo, sua escrita deve enfatizar o agente e suas ações.
Portanto não use algo como: "O código é escrito por um desenvolvedor".
Em vez disso, escreva: "Um desenvolvedor escreve o código".
2. Use o pronome "eles" para ser mais abrangente
É complicado escrever sempre "ele ou ela". No entanto, é importante incluir homens, mulheres e outros gêneros entre seus leitores.
Por ser tecnicamente incorreto usar o pronome plural para se referir a um substantivo singular, vamos tentar levar o substantivo sempre para o plural.
Portanto, use "Eles" em vez de "ele ou ela". Vamos usar um exemplo. Muitos documentos da API falam sobre "usuários".
NÃO faça o seguinte:
"Um usuário pode encontrar o X. Nesse caso, você pode fornecer a ele o recurso Y."
Neste caso, basta usar "eles". Ficaria assim:
"Os usuários podem encontrar o X. Nesse caso, você pode fornecer a eles o recurso Y."
3. Mantenha a escrita do título consistente.
Existem dois tipos principais de letras maiúsculas usadas nos títulos:
"Cozinhar uma Ótima Torta de Maçã";
"Cozinhar uma ótima torta de maçã".
O primeiro coloca em maiúscula as principais palavras de acordo com um padrão. Já o segundo caso é chamado de sentença de exemplo.
Para títulos longos, a caixa de sentenças tende a ser mais legível, mas esse é um critério que depende exclusivamente de você. Apenas certifique-se de que você e seus futuros colaboradores sejam consistentes, beleza?
Como você pôde perceber, existem vários aspectos que precisam de atenção na fase de documentação de uma API, além do mais, o objetivo é que seus parceiros e clientes tenham uma boa experiência e integrem seus serviços com eficiência.
A API pode ser a interface entre um aplicativo e o código de back-end, mas a documentação conecta você a seus usuários.
Escrever uma boa documentação não é uma tarefa fácil e provavelmente será um processo iterativo de feedback e revisão.
Agora que você já teve acesso a nossas dicas e sabe como documentar uma API, que tal aproveitar e descobrir sobre o Postman, uma ferramenta que pode te ajudar bastante com a documentação das solicitações feitas pela API!