A documentação é a interface humana de uma API. Quando ela é boa, a primeira cobrança acontece em minutos; quando é ruim, o time gasta dias tentando descobrir o formato de um campo.
O que não pode faltar
- Base URL e autenticação explicadas na primeira tela.
- Referência por endpoint com parâmetros, exemplo de requisição e de resposta.
- Catálogo de erros com código, causa provável e solução.
- Eventos de webhook com payload real e instrução de validação de assinatura.
- Regras de idempotência, paginação e limites de requisição.
- Ambiente de testes separado do de produção.
- Especificação OpenAPI para importar no Postman ou gerar cliente.
Exemplos que funcionam de verdade
Exemplo bom é aquele que pode ser copiado, colado e executado trocando apenas a chave. Exemplo com pseudocódigo ou campo inventado custa suporte. A documentação da Pitra gera os exemplos a partir da mesma fonte que alimenta o SDK e a especificação OpenAPI, o que impede divergência entre o que está escrito e o que a API aceita.
Documentação viva
Changelog público, versão da API visível e página de status são parte da documentação. Sem eles, o desenvolvedor descobre mudanças pelo erro em produção.
Perguntas frequentes
- Documentação e referência são a mesma coisa?
- Não. A referência lista endpoints e campos; a documentação inclui guias, conceitos, exemplos e tratamento de erro.