Forma programática de obter todos os endpoints de API para a minha instância?

[RGJ (Richard - Communiteq)]

@mcwumbly

Então, que garantias de estabilidade podemos fazer sobre nossa API de backend?

Acho que essa é uma responsabilidade que a documentação da API deveria abordar.

Garantias de estabilidade devem ser abordadas por versionamento de API direto.

@mcwumbly

Primeiro, como uma espécie de modelo mental de nível superior, eu descreveria as coisas assim:

• Nosso ponto de entrada principal para documentação está aqui, como você apontou: Documentação - Discourse Meta
• Para documentação do desenvolvedor, está aqui, ou talvez melhor ainda, aqui: Introdução ao Desenvolvimento do Discourse
• A documentação da API é um subconjunto da documentação do desenvolvedor e está localizada aqui: https://docs.discourse.org/

Eu chamaria a documentação da API de docs em vez de specs, mas concordo que ainda é um subconjunto da nossa documentação do desenvolvedor. O URL para essa documentação é estranho… faria mais sentido que nossa documentação completa vivesse lá ou que fosse um redirecionamento para Documentation - Discourse Meta, e que houvesse um sinalizador claro de Introdução ao Desenvolvimento do Discourse para a documentação da API.

Este tópico não é sobre onde a documentação reside — é sobre como a API é documentada. O que está faltando é um formato padronizado e legível por máquina como o OpenAPI.

Essa ausência, juntamente com a falta de versionamento, torna o trabalho de integração mais difícil e frágil do que deveria ser. Mesmo um esquema OpenAPI básico para os endpoints documentados seria muito útil.