Sua documentação de API lista 47 endpoints. Cada um tem o método HTTP, o caminho, o corpo da requisição e o esquema da resposta. Está completa, precisa e totalmente inútil.
Por quê? Porque quando chego na sua documentação, geralmente não quero um inventário de endpoints.
Quero concluir uma tarefa.
Quero saber como criar o cliente, anexar o método de pagamento, iniciar a assinatura, lidar com o webhook, me recuperar de falhas e testar tudo com segurança.
A referência de endpoints é necessária. Ela não é o produto.
Referência não é integração
Uma página de referência responde:
- qual caminho existe
- qual método ele aceita
- quais campos são permitidos
- como é a resposta
A integração responde:
- o que devo fazer primeiro?
- em que ordem essas chamadas acontecem?
- o que pode falhar?
- o que devo armazenar?
- como testar isso sem quebrar a produção?
Se sua documentação só tem páginas de referência, o desenvolvedor precisa engenhar reversamente o fluxo de trabalho a partir de partes brutas.
É por isso que documentações "completas" ainda podem parecer inutilizáveis.
Comece pelos trabalhos que os desenvolvedores realmente têm
Para a maioria das APIs, a documentação real deve começar com caminhos de tarefas:
- autenticar uma requisição
- criar o primeiro recurso
- atualizar o recurso com segurança
- escutar um webhook
- repetir uma operação com falha
- sair do modo de teste para produção
Em seguida, cada tarefa pode linkar para a referência do endpoint.
O guia começa com o objetivo do desenvolvedor, mostra um caminho funcional, inclui exemplos e então linka para os detalhes exatos do endpoint.
A ordem importa. Se a primeira página é uma tabela de referência gigante, você está pedindo para o leitor construir o modelo mental sozinho.
Mostre um caminho completo, não chamadas isoladas
Documentações ruins mostram uma requisição perfeita:
POST /customersDocumentações melhores mostram a sequência:
- Crie o cliente.
- Crie a assinatura.
- Armazene os ids retornados.
- Escute o webhook de confirmação.
- Lide com estados de falha e cancelamento.
A sequência é o que os desenvolvedores precisam para entregar a integração.
Ainda melhor, inclua a forma da máquina de estados:
