Não entendo por que não existe documentação completa para todos os endpoints da API. A documentação original foi lançada ao público em dezembro de 2014, e aqui estamos, seis anos depois, e a documentação ainda está inacabada.
Por que isso acontece? A falta de boa documentação e a sugestão de fazer engenharia reversa na API são barreiras significativas para desenvolvedores que desejam usar a API.
Atenciosamente,
Um desenvolvedor frustrado
Você pode dar alguns exemplos do que está tendo dificuldade ou do que está achando insuficiente?
Este é um tópico oportuno, pois tenho um aviso no meu fórum: “Detectamos uma solicitação de API usando um método de autenticação obsoleto.”
Gostaria de saber qual é o método atual que devo usar e obter um guia passo a passo para implementá-lo, do ponto de vista do administrador do fórum.
O que encontrei são discussões desatualizadas que linkam para o GitHub e, como pessoa não técnica, referências a códigos não são úteis para mim. Alguém poderia fornecer orientações em linguagem simples?
A autenticação adequada da API é abordada na documentação, bem no topo. Em resumo, você precisa usar cabeçalhos HTTP para fornecer a chave da API e o nome de usuário, em vez de parâmetros de URL.
@justin Meu exemplo específico é que estou lentamente trabalhando na implementação de um wrapper em Python para a API do Discourse, e a falta de documentação adequada é esmagadora. Já tenho que testar manualmente cada endpoint individualmente, mas muitos desses endpoints não estão documentados ou estão documentados de forma incorreta.
É dito explicitamente no topo da documentação que a API não está totalmente documentada. Quero saber: Por quê?
Veja Reverse engineer the Discourse API
Por que cada grão de areia na praia não está “totalmente documentado”? 
Por curiosidade, por que vocês não simplesmente suportam o que é necessário até encontrar um novo requisito não suportado, momento em que fazem engenharia reversa? Isso é muito mais fácil do que mirar em 100% e não faz sentido envolver chamadas que nunca serão usadas? Especialmente porque vocês estarão lidando com um alvo em constante mudança. Facilita a vida de vocês!
Entendo que isso possa ser engenharia reversa. É apenas um pouco frustrante ter que fazer isso. A API foi criada por humanos que devem saber como funciona; por que esses humanos não podem escrevê-la para que outros sejam informados?
Não acho que isso seja um grande pedido. Uma boa documentação é crucial em qualquer projeto.
Esse é o plano no momento: tenho todos os endpoints documentados espelhados no meu repositório, na branch develop, e cheguei ao ponto em que terei que começar a fazer engenharia reversa.
Já estou começando a contribuir com GitHub - discourse/discourse_api_docs: Discourse API Documentation · GitHub, mas realmente questiono por que isso é necessário em um projeto tão consolidado.
Como em qualquer coisa, trata-se de recursos e prioridades. A superfície da API é enorme. Tecnicamente, é tudo — tudo é acessado via API, razão pela qual a engenharia reversa funciona. Optamos por focar nosso tempo limitado de engenharia em correções, recursos, desempenho etc., em vez de documentação. Nossa direção de produto é amplamente impulsionada por nossos clientes e nossa comunidade. Até onde sei, nenhum cliente jamais solicitou cobertura de 100% da documentação da API. Quando os clientes perguntam sobre algo que está faltando ou pouco claro, nós adicionamos. Portanto, a cobertura de 100% não tem sido uma prioridade.
No momento, a documentação da API é curada manualmente. Obviamente, esse não é um método sustentável, mas por enquanto é o que temos. Refatorar o sistema de documentação da API para que seja gerado programaticamente é um item “a fazer”, mas não está previsto para nenhuma versão específica atualmente, portanto, não há cronograma para conclusão.