Sua API está bem documentada? Detalhes que precisamos observar
Fornecer a documentação de uma API é fundamental para sua adoção. A documentação expõe todas as informações necessárias para que a API seja facilmente utilizada, e para que sejam detalhados os serviços que ela oferece. É este artefato que gera a “primeira impressão” sobre a API.
Entretanto, a baixa qualidade da documentação de APIs é o principal obstáculo no consumo e nos testes das mesmas. Ao longo deste artigo, irei descrever, com base em pesquisas, os principais problemas encontrados nestes artefatos, e quais as estratégias para fornecer uma boa documentação.
A importância da documentação
Ao ler a documentação de uma API esperamos que ela nos revele:
- O que ela faz;
- Como deve ser usada;
- O que esperar quando ocorre um erro;
- Quais credenciais de segurança usar;
- Como e onde obter as credenciais de segurança para utilizá-la.
A documentação da API é uma espécie de “acordo” ou “contrato” entre quem disponibiliza e quem consome a API. Por exemplo, se o endpoint de autenticação de apps através da API do Twitter adicionar um parâmetro novo, e essa mudança não for devidamente documentada, apps que utilizam o Twitter para autenticação irão falhar. Frustrados, desenvolvedores podem acabar migrando para soluções de concorrentes. Quantas vezes já nos deparamos com documentação de APIs que parecem tornar ainda mais difícil o seu consumo?
O que a comunidade tem a dizer a respeito
Neste ano de 2020, foi realizada a pesquisa “State of the API”, com mais de 13.500 desenvolvedores, testadores e outros papéis. A pesquisa identificou que:
- Para quase 60% dos entrevistados, o conhecimento sobre as APIs foram obtidos através da documentação;
- Para 70% dos entrevistados, a documentação é um fator considerado antes de escolher uma API para integrar;
- Numa escala de 0 (para “mal documentada”) a 10 (para “bem documentada”), a nota média das APIs com as quais os entrevistados trabalham foi de 5.06;
- A falta de documentação é o principal obstáculo ao consumir APIs (vide imagem abaixo).
Como a documentação da API falha
No artigo How API Documentation Fails pesquisadores identificaram os principais problemas de documentação de APIs. Os principais são:
- Incompletude: a descrição de um elemento ou tópico da API não está onde era esperado, ou falta alguma informação. É um problema comum quando a documentação foi gerada automaticamente a partir de classes e métodos da API;
- Ambiguidade: a descrição de um elemento da API pode possuir múltiplos sentidos, ocasionando confusão e falta de compreensão;
- Exemplos faltando explicação: um exemplo de código é fornecido, porém não é acompanhado de um texto explicativo para torná-lo claro;
- Desatualização: ocorre quando a documentação atual reflete a uma versão anterior da API, e não a versão atual;
- Inconsistência: as documentações das APIs que se relacionam, diferem entre si, gerando inconsistências. Suponha serem três produtos: duas APIs e um software intermediário que “liga” as duas. Cada API possui uma documentação feita por times de desenvolvimento distintos, o que possivelmente acarreta em inconsistências entre as documentações, e menor interoperabilidade entre os produtos;
- Incorreção: algumas informações estavam incorretas. Por exemplo, os parâmetros de entrada e o tipo de saída de um método de API, conforme implementado no código-fonte, diferem daqueles na documentação;
- Inchaço: a descrição de um elemento ou tópico da API é excessivamente detalhado, ou extenso. Para leitores, pode acabar sendo cansativo de ler, e até mesmo dificultar a compreensão;
- Fragmentação: as informações relacionadas a um elemento ou tópico estão fragmentadas, ou espalhadas por muitas páginas ou seções. Isto obriga o leitor a clicar em várias páginas da documentação da API para aprender a funcionalidade e o uso de um elemento de API. Separar as descrições até níveis tão “micro” é desnecessário.
Porque a documentação da API é importante para o QA?
Se seu time irá consumir uma API externa, a documentação será um insumo para testes de contrato. Ao conhecer a API externa, facilita-se o trabalho de identificar quando a origem de determinado bug: se está na API ou no software que a está consumindo.
Se seu time for fornecer uma API, a documentação será um dos artefatos mais importantes para explicar como a API funciona. Sendo um artefato, é também responsabilidade do QA verificar se as informações da documentação da API estão corretas e avaliar a qualidade dela, e até mesmo propor melhorias e correções.
Boas práticas no desenvolvimento da documentação da API
Nesta parte, serão discutidas abordagens ao desenvolver a API de fato.
Adaptar a linguagem ao público-alvo
A documentação da API é usada por diferentes pessoas, desde desenvolvedores juniores a seniores, até product owners. Por isso, a documentação deve funcionar como um “manual do usuário” de um produto. Adicionalmente, pode-se adotar um glossário, como o PayPal, tornando ainda mais claro o conteúdo da documentação.
Adote terminologia padrão e convenções de nomenclatura
Ao desenvolver uma API, uma boa prática consiste em adotar as terminologias e convenções de nomenclatura aceitas na comunidade. Isto tornará a documentação e a API mais atrativas, além de causar a sensação de ser uma API mais confiável do que uma que possua documentação “ruim”, fora das convenções e padrões.
Ou seja, usar verbos, nomes de itens, códigos de status diferentemente das convenções pode gerar confusão por parte do consumidor da API. Um código 403, por exemplo, deve sempre significar “Forbidden”. O verbo HTTP ‘GET’ deve sempre ser usado para consultar um recurso. Para consultar tais convenções, sugiro os sites: HTTP Statuses e RFC 7231.
Adote o “Spec Driven Development”
Tratar a documentação da API como uma tarefa tardia ou separada levará à negligência, descuidos e desconexão dos usuários da API. É preciso tempo e esforço para criar uma documentação API abrangente, mas o investimento vale a pena. A documentação da API ausente, incompleta ou imprecisa pode tornar o gerenciamento da API impossível.
Para resolver esta questão, temos o “Spec-Driven Development” (ou SDD) que significa desenvolvimento orientado a especificações. No SDD, a abordagem é documentar a API paralelamente à sua construção. Para cada nova release, a documentação deve ser atualizada e alterada de acordo.
No SDD, a documentação geralmente segue um determinado formato de descrição de API. Este formato é denominado especificação. Uma especificação de API é como um “template” para documentos, é uma linguagem unificada que descreve o design da API, explica como ela funciona e o que esperar dela. As especificações mais comuns são RAML (RESTful API Modeling Language), OpenAPI (evolução do Swagger) e API Blueprint. Através de editores de texto, é possível visualizar como está ficando a especificação em tempo real. De modo a exemplificar, e até mesmo gerar especificações, há o Swagger Editor e o API Console, ambos online.
Neste ponto, é preciso definir de quem será a responsabilidade de criar e manter esta documentação. Todos podem participar destas duas etapas, mas uma boa prática é atribuir a uma pessoa esta responsabilidade, e ela ir conduzindo a escrita enquanto consulta outras pessoas quando necessário. Outra sugestão é que esta pessoa responsável seja alguém que esteja próximo a pessoas de variados papéis e departamentos para tornar a documentação acessível a diferentes públicos.
Aprenda com os bons exemplos
Nada melhor para aprender do que ter bons exemplos. Alguns exemplos de APIs que aplicam boas práticas de documentação são:
Layout e navegação
Como mencionado anteriormente, a navegabilidade e layout são fatores importantes para ajudar os usuários a interagir com a documentação da API. Algumas opções e práticas são sugeridas por Diana Lakatos, especialista em documentação de APIs:
- Dinâmico: é o layout mais difundido dentre bons exemplos de documentação de APIs. Torna a navegação mais fácil e mais flexível para os usuários do que os layouts estáticos ao procurar tópicos específicos em uma documentação extensa;
- One Single Page: é a melhor solução para documentações mais enxutas. Trata-se de manter toda a documentação em uma única página;
- Navegação persistente: mantém a navegação sempre visível. Os usuários não querem rolar à procura de uma barra de navegação que desapareceu;
- Multi-colunas: layout com duas ou três colunas fixas, com navegação à esquerda, e informações e exemplos à direita;
- Syntax Highlighter: melhora a legibilidade dos códigos de exemplo ao mudar a cor do termo de acordo com sua categoria.
Tópicos mais desejados
Na pesquisa realizada pela SmartBear, os entrevistados foram questionados quanto à estrutura da documentação. A imagem abaixo apresenta os resultados obtidos e pode servir como um guia ao selecionar quais tópicos incluir na documentação da sua API, e que serão indispensáveis para sua correta compreensão.
Distribuição e Discovery
Agora que você já tem a primeira versão da sua documentação, precisa pensar em como irá distribuí-la junto a API e como será o discovery. A distribuição diz respeito a como será dado acesso à documentação e à API, e o discovery está relacionado a como irão descobrir a existência da API.
Para APIs públicas, algumas dicas são:
- Adotar Search Engine Optimization (SEO);
- Utilizar anúncios voltados ao público-alvo;
- Apresentar em eventos da comunidade;
- Enviar a API para ferramentas utilizadas pela comunidade para descobrir e pesquisar APIs. Algumas dessas ferramentas são Postman API Network e ProgrammableWeb.
Versionamento
A cada nova versão da API, a documentação deve passar por adequações. Para versões menores, as diferenças podem ser mencionadas na mesma documentação. Para diferenças de versão maiores, recomenda-se manter a documentação de ambas as versões até que a versão anterior seja obsoleta.
Além disso, deve existir o compromisso de informar àqueles que consomem a API, de que há uma versão mais recente da API e da documentação.
Concluindo
Pesquisando sobre esse tema, nos deparamos com a vastidão de considerações e práticas presentes na comunidade. Não existe o certo e o errado: existe a documentação que irá proporcionar a melhor experiência ao seu público-alvo.
Na sua vivência, já se deparou com os problemas listados neste artigo? Já participou ativamente da escrita de documentações? Me conte nos comentários quais tem sido suas experiências ;)
Referências
Current practices in web API documentation — Gianni Angelini
Undisturbed REST: A guide to designing the perfect API — Michael Stowe
How API Documentation Fails — Gias Uddin e Martin P. Robillard
How to Write API Documentation: Best Practices and Examples — AltexSoft
The Ultimate API Publisher’s Guide — Joyce Lin
The Ten Essentials for Good API Documentation — Diana Lakatos
6 Practices to Achieve Consistency across API Specifications — Shariq Nazr
Agradecimentos
