As mudanças que as organizações estão fazendo em digital estão diretamente relacionadas com APIs. De acordo com o 2021 State of API Report, feito pelo Postman, 49% dos pesquisados afirmaram que mais da metade dos esforços de desenvolvimento são gastos com APIs. Não resta dúvidas de que elas são o mainstream, com mais empresas compreendendo o valor de cria-las. Com isso, a necessidade de ter uma documentação de APIs clara vem à tona.
A documentação de uma API é toda a informação, entre orientações técnicas, tutoriais e exemplos, disponibilizada para que seu consumo seja bem-sucedido. É o que vai permitir que alguém aprenda a usar sua API. Como a experiência de usuário em um produto, quanto melhor a interface usada para consumir uma API, maiores as chances de o usuário conseguir o que quer com ela.
Como chegar a uma documentação de API de primeira? É o que veremos neste artigo.
Por que a documentação de APIs é tão importante
A documentação de APIs pode ser considerada uma parte menor do desenvolvimento de APIs. Enquanto boa parte do tempo do ciclo de vida de APIs é dedicado ao design, desenvolvimento, testes e gestão, apenas cerca de 6% de todo o trabalho é dedicado à documentação.
Ainda assim a documentação não é um trabalho menor. Ela está diretamente relaciona ao consumo de uma API, além de à rapidez de adoção por quem deseja consumi-la. Por isso, os desenvolvedores acreditam que o tempo dedicado à sua construção e manutenção deveria ser maior.
De acordo com a pesquisa da Postman, depois de segurança, performance e confiabilidade, é a documentação o quarto fator mais considerado ao adotar uma API. Ele aparece acima de itens como escalabilidade, usabilidade, preço, versões, suporte e reputação do provedor.
Mas não é só esse o dado que merece o maior destaque. Segundo o levantamento, a falta de documentação é o principal obstáculo ao consumo de APIs, citado 55% das vezes. Complexidade, falta de conhecimento, falta de tempo, falta de orçamento e de pessoas são outros motivos.
Ainda assim, ao perguntar quão bem as APIs estão documentadas, 26% dá nota 5 (de 10) para a documentação, enquanto apenas 3% dão 10.
Ainda de acordo com a pesquisa, a boa documentação de APIs é realmente uma disciplina que está em falta e deve ser estimulada. Mas por que documentar é desafiador?
Leia também: Segurança de APIs: quais os controles do iPaaS APIPASS?
Desafios da documentação
Assim como outros produtos, as APIs mudam rápido. Em média, as equipes de desenvolvimento fazem releases mensais relacionados a APIs. Manter e atualizar documentos para o time de desenvolvimento e para os usuários pode ser difícil, principalmente sem uma ferramenta adequada para isso.
Como melhorar a documentação de APIs
Há certas similaridades entre as boas documentações de API. Por exemplo, uma boa documentação de API é precisa, educativa e estimula o uso. Ela é relevante e útil tanto para quem é totalmente sem familiaridade com suas APIs quanto para quem já as usa.
Como os desenvolvedores pensam que a documentação de uma API pode ser melhorada? Veja 8 pontos:
1. Ter technical writers
Seja desenvolvendo um framework interno de documentação, seja usando um provedor ou framework open source, você precisa ter alguém responsável pela documentação.
Grandes empresas têm times completos para construir e manter sua documentação e outros recursos para desenvolvedores.
Garanta o apoio de technical writers para a equipe de desenvolvimento. Nada pior do que encontrar um texto que mais confunde do que esclarece, com erros gramaticais e sem uma arquitetura de informação amigável.
2. Oferecer um ponto de partida
O que os desenvolvedores devem saber e fazer, em primeiro lugar, para se familiarizar com suas APIs?
Ter uma seção “Comece por aqui”, com informações gerais fundamentais sobre estrutura e outros direcionamentos (como autenticação) para quem vai mergulhar na sua documentação facilita.
3. Ter uma estrutura compreensível
Você precisa criar uma estrutura de documentação lógica, compreensível à primeira vista (e sem muito auxílio) pelos usuários.
Essa será a cola que manterá a documentação coesa e uniforme para os usuários, mas também que facilitará a manutenção da consistência de criação durante a ampliação dessa documentação, com a criação de novas features.
Esse trabalho começa já no desenvolvimento, que deve considerar como o código parecerá ao ser documentado. Muitos problemas na documentação vêm de problemas no desenho e escrita da API.
4. Incluir bons exemplos comuns
Uma boa documentação é mais do que referência. Ela é vasta de exemplos e casos de uso reais.
Então, pensando que o desenvolvedor que acessa a sua documentação já tem um objetivo em mente com a sua API, facilite para ele. Mapeie os principais objetivos e os explore em exemplos e toda a informação necessária para acelerar a adoção.
Há cenários que mostram o que é possível fazer com a API, exemplos de requisições e respostas para que os usuários compreendam o endpoint e diagnostiquem problemas mais rápido.
5. Trazer tutoriais, FAQs e estudos de casos
A documentação é uma plataforma de aprendizado sobre a sua API. Proporcione material para que os desenvolvedores vejam tudo o que podem fazer com a sua API.
Tudo o que possa facilitar o aprendizado será valioso para os usuários. Isso inclui tutoriais, FAQs e estudos de casos, o que ajudará a cobrir todas as etapas de uso, desde o conhecimento inicial, uso da API, resolução de problemas e – por que não? – inspirações para novos usos.
6. Pedir feedback dos usuários
Você deve acompanhar diferentes métricas de APIs, como número de chamados e volume de dados transferidos, mas, para saber se a documentação está sendo efetiva, nada como ouvir os usuários.
Boas documentações de API têm canais de comunicação abertos com os usuários para feedbacks constantes.
Isso pode ser feito de maneira simples com a pergunta “Essa informação foi útil?” dentro da página ou com um esforço maior, por meio da aplicação de pesquisas. Com a primeira, você saberá se falta alguma coisa, com a segunda você poderá saber o que falta.
7. Estandardizar o desenho de APIs
A OpenAPI Specification é o formato standard de descrição de REST APIs, usado por boa parte dos profissionais na definição de APIs. Ele é pensado para ser fácil de ler e de entender, tanto por humanos quanto por máquinas. Será que vale a pena fugir dele?
8. Manter as atualizações
Que mensagem uma documentação desatualizada passa para os usuários? Esse é um dos problemas que mais leva desenvolvedores a não usar APIs.
Sabemos que não é fácil manter documentações atualizadas. Justificativas não faltam, como: falta de tempo, velocidade de delivery e falta de ferramentas para isso.
Documentação tem que fazer parte do processo. Isso inclui não apenas a inclusão de novas informações, mas a revisão do que já foi publicado.
O tech writer não tem que esperar o time de desenvolvimento terminar o trabalho para começar a documentar. Além disso, pode estar na hora de confiar em ferramentas que acelerem o trabalho.
O que não pode é sacrificar o usuário por dificuldades internas.
Entre a mera documentação e as boas documentações de APIs
A documentação da API é o ponto que conecta o desenvolvimento com os usuários da API. Não subestime o tempo para a criação e revisão desse material.
Levantamos, sem a pretensão de exaurir essa lista, alguns pontos que vemos em toda documentação boa de usar.
Você adicionaria mais itens a essa lista?