Estou procurando uma maneira de obter uma lista definitiva dos endpoints da API disponíveis na minha instância do Discourse. Às vezes, pode ser difícil saber quais APIs estão disponíveis para mim ao procurar construir uma integração na plataforma.
5 curtidas
Não acho que isso seja tecnicamente possível. O Discourse não tem uma rota de descoberta de API (por exemplo, algo semelhante à rota /wp-json do WordPress). A coisa mais próxima que conheço é a documentação em https://docs.discourse.org/.
Para integrações que não são cobertas pela documentação, provavelmente a maneira mais rápida de descobrir se elas são viáveis é perguntar aqui sobre como atingir algum objetivo específico. A regra geral com a API é que tudo o que pode ser feito através da interface do usuário do Discourse também pode ser feito via API.
9 curtidas
Agradeço a resposta, Simon! Conheço o docs.discourse.org (que, curiosamente, não são os docs oficiais, mas as especificações da API).
Também estou familiarizado com o uso do console do meu navegador para capturar requisições, bem como com a análise de arquivos routes.rb.
Como você pode imaginar, no entanto, as duas opções acima são bastante tediosas e nada amigáveis. Para aqueles de nós que buscam construir integrações profundas rapidamente – especialmente se tivermos outras equipes em nosso negócio ou fornecedores terceirizados que desejam integrar… dizer a eles para fazerem as coisas acima teve uma resposta terrivelmente ruim.
Embora eu esteja ciente da flexibilidade nas capacidades do Discourse, desenvolver ou integrar com a plataforma é uma batalha árdua, para dizer o mínimo. Como último recurso, eu esperava que houvesse uma maneira programática de agregar as APIs públicas.
7 curtidas
A fonte definitiva, além da fonte, é Engenharia reversa da API do Discourse.
Tudo o que você pode fazer no front-end, você pode fazer com a API. Há pouquíssimas coisas que você pode fazer apenas com a API.
3 curtidas
Você pode esclarecer um pouco mais o que você quer dizer com isso?
Embora o ponto do Simon sobre estes não cobrirem APIs implementadas por extensões do Discourse (por exemplo, plugins), estes docs são oficiais no sentido de que nós os mantemos.
Isso não quer dizer que não tenhamos bastante espaço para melhorar quando se trata da documentação da API do lado do servidor e da própria API, mas eu queria entender um pouco melhor seu feedback sobre a documentação que já existe lá.
1 curtida
Com certeza! Isso provavelmente é mais do que você pediu 
Acho que você mantém sua documentação oficial de produto aqui, correto?
Eu diria que a nuance é que as especificações da API são um subconjunto da documentação. Então, eu sempre esqueço e isso me pega de surpresa por um segundo quando indico alguém para docs.discourse.org e esqueço que esse link não leva à documentação do Discourse… ele leva a um conjunto limitado de especificações de API.
Então eu digo algo como:
Obrigado por se reunir hoje, fico feliz que você esteja interessado em ver que tipo de experiência você pode construir para nossos usuários usando a nova Netwrix Community!
A documentação está na verdade em https://meta.discourse.org/c/documentation/10.
docs.discourse.org não é realmente a documentação deles, mas sim suas especificações de API. Sei que você perguntou sobre a integração com a nova comunidade que estamos construindo. Infelizmente, não tenho uma página que eu possa te indicar que mostre toda a funcionalidade que o Discourse oferece, mas você pode ir em docs.discourse.org para ter uma ideia de apenas parte do que é possível.
O que eu faço nesse cenário, porque não consigo dar uma lista definitiva dos endpoints que existem, é simplesmente dizer: “Assuma que tudo que você possa conceber é possível. Eu vou verificar o que o Discourse pode fazer, e nós vamos reduzir isso depois, se precisarmos.”
Mas seria ótimo se todas as APIs estivessem listadas nas especificações, né?
Mais contexto…
Seria estranho se eu comprasse um carro e eles me dessem uma folha de recursos e eu perguntasse: “Incrível! É tudo então?”
“Bem, não… mas se você apenas olhar debaixo do capô e rastrear a fiação de 12v e as braçadeiras de mangueira ao redor do motor, você poderá ver a que eles se conectam e fazer engenharia reversa do que mais ele faz.”
Claro, o mecânico/desenvolvedor/pessoas tecnicamente inclinadas nesse cenário podem fazer isso. Mas nem todo mundo 
Além disso, mesmo como desenvolvedor, eu não quero:
- Aprender Ruby para ver onde as rotas podem existir
- Fazer engenharia reversa de todos os arquivos routes.rb para ter uma ideia dos endpoints disponíveis
- Refinar ainda mais essa engenharia reversa para descobrir quais entradas eles exigem, qual a estrutura de objeto da saída
- Verificar quais plugins eu tenho também
- Repetir nos arquivos routes.rb deles (acho? Eu não sei Ruby, então não tenho certeza)
- …e 6 meses depois, entre meu trabalho diário e isso, eu tenho uma resposta.
Eu digo tudo isso com carinho — não há nenhuma plataforma hoje que se compare às capacidades da plataforma Discourse. Ponto final. É o produto mais forte, poderoso, flexível e econômico do mercado e está anos-luz acima da concorrência.
Suas deficiências não são sua robustez, poder e flexibilidade. Na verdade, essas são algumas das maiores vantagens do Discourse que produtos concorrentes terão dificuldade ou até falharão em emular.
- Não é que suas APIs não sejam ótimas — é que encontrá-las é difícil.
- Não são painéis de administração com muitas opções que tornam a adoção difícil, mas sim a falta de educação e nomes de configurações de administração como
First post only(Apenas a primeira postagem) que são, na melhor das hipóteses, ambíguos. - Não é sua implementação robusta, porém simples (e perfeitamente assim!) de uma estrutura de ferramenta de comunidade de categorias, tópicos e tags, mas sim que a informação não existe para educar e inspirar os usuários de que não precisa ser uma categoria, mas sim um blog, um quadro de anúncios de produtos ou um portal de ideias… e eles não precisam ser tópicos, mas podem ser blogs, anúncios de produtos e ideias.
Esta é a única coisa que o Discourse como produto me falta: o polimento — os detalhes de acabamento.
9/10, compraria novamente.
7 curtidas
Ok, acho que entendi melhor, obrigado.
O que se segue são minhas próprias opiniões – não as discuti com pessoas mais experientes do que eu, então posso ser corrigido em algumas coisas que estou errando aqui.
Nossa documentação de histórias também está evoluindo. Fizemos progressos significativos, mas ainda há um longo caminho a percorrer. Permita-me tentar recapitular um pouco.
Primeiro, como uma espécie de modelo mental de nível superior, eu descreveria as coisas assim:
- Nosso principal ponto de entrada para documentação está aqui, como você apontou: Documentation - Discourse Meta
- Para documentação do desenvolvedor, está aqui, ou talvez melhor ainda, aqui: Introduction to Discourse Development
- Documentos da API são um subconjunto dos documentos do desenvolvedor e estão localizados aqui: https://docs.discourse.org/
Eu chamaria os documentos da API de documentos em vez de especificações, mas concordo que eles ainda são um subconjunto de nossos documentos do desenvolvedor. O URL para esses documentos é estranho… faria mais sentido que nossa documentação completa estivesse lá ou que fosse um redirecionamento para https://meta.discourse.org/c/documentation/10, e que houvesse um sinal claro de Introduction to Discourse Development para os documentos da API.
Nossos documentos do desenvolvedor estão passando por melhorias. O histórico de commits aqui provavelmente conta a melhor história sobre onde o esforço foi até agora: Commits · discourse/discourse-developer-docs · GitHub
Os documentos da API poderiam ser descritos como incompletos, mas temos trabalho a fazer para organizar nossa história aqui. No passado, costumávamos apontar para “engenharia reversa da API”, mas concordo que essa não é uma boa história. É bom para hackear por sua conta e risco, mas pode haver casos em que os endpoints não listados lá é provavelmente melhor não depender deles.
A API do lado do servidor destina-se principalmente a ser consumida por nossa aplicação frontend. No frontend, fornecemos uma API JavaScript que seria uma interface melhor para consumir, pois pode ocultar alterações feitas no backend: Using the JS API
Então, que garantias de estabilidade podemos fazer sobre nossa API de backend?
Acho que essa é uma responsabilidade que os documentos da API deveriam abordar. Idealmente, o que está documentado lá é um subconjunto de todos os endpoints que suportamos, mas um subconjunto intencional que pretendemos suportar para outros que constroem integrações, enquanto as coisas não listadas lá são intencionalmente não documentadas como coisas apenas destinadas ao nosso frontend, que podem mudar sem aviso.
Idealmente (em minha opinião), teríamos a documentação embutida no código-fonte de uma forma que os próprios documentos estivessem sob teste, extensíveis com plugins, servidos pelo aplicativo em si para que estivessem em sincronia com a instância que está sendo documentada – dessa forma, você poderia ver os documentos da API para um determinado site e ver a documentação para a versão que ele está executando, com quaisquer plugins que estejam realmente instalados e habilitados.
Eu sei que outras pessoas internamente tiveram muitas discussões sobre outras ideias para melhorar nossa história de API do lado do servidor.
Ainda não conseguimos priorizar muito neste espaço, pois nosso foco principal quando se trata de experiência do desenvolvedor nos últimos dois anos tem sido na modernização de nosso frontend.
Não tenho certeza de quando isso provavelmente mudará, mas ficaremos atentos a pequenas coisas que podemos fazer ao longo do caminho para continuar a aprimorar a história da API do lado do servidor. Se surgirem perguntas específicas, talvez possamos usá-las como ímpeto para fazer melhorias mais direcionadas nesse ínterim.
5 curtidas
Garantias de estabilidade devem ser abordadas por versionamento de API direto.
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.
3 curtidas
Fundamentalmente, este não é um problema de documentação, é um problema de implementação.
@avdi levantou isso anos atrás e há um amplo consenso interno de que o caminho correto a seguir é uma API JSON/REST versionada adequadamente com parâmetros e formatos de dados consistentes.
Atualmente, a API que enviamos é nossa API interna. É 100% completa e exaustiva, mas é desajeitada e muda de formato. Os formatos que ela retorna e os endpoints são otimizados para impulsionar o aplicativo Ember do lado do cliente. Ela evolui e muda de formato à medida que os meses passam, o que a torna difícil de depender para tarefas de missão crítica. Construir sobre ela é mais complexo do que deveria ser.
Um novo conjunto de controladores e rotas resolveria o problema de estabilidade aqui e nos permitiria retornar formatos que façam mais sentido para uma API REST. Por exemplo:
/api/v0/topic/1234.json poderia retornar um formato muito mais “consistente com a prática geral de API”.
Existem muitas “preocupações exclusivas do cliente Ember” muito complicadas em nosso JSON de tópicos:
timeline_lookup, post_stream, tags_descriptions etc… etc…
Dito isso, este é um projeto enorme para embarcar, precisaríamos de muita reformulação interna para garantir que não duplicamos a lógica. Além disso, os plugins tornam isso extra complicado porque eles remodelam muito do comportamento interno, o que precisaria ser refletido na API. (o que assign faz com esses formatos?)
Eu certamente vejo nós embarcando nesta aventura, mas não em um futuro próximo.
10 curtidas
Acho completamente razoável que a mudança leve tempo. Eu gerenciei Relações com Desenvolvedores na minha última empresa e, meu Deus… levou mais de dois anos para que nossas APIs chegassem a um estado melhorado. Tantas coisas complexas a considerar (e a engenharia odiava a ideia de criar um endpoint estável que não pudesse mudar!)
Acho que mudanças menores podem acontecer ao longo do tempo e em um prazo mais curto também. Admito que não analisei como suas rotas (ou como rotas em Ruby) são definidas — mas presumo que algumas coisas fáceis de resolver poderiam ser tratadas com bastante facilidade. Por exemplo:
Não posso falar por todos, mas sinto que mesmo tendo os endpoints existindo na sua especificação de API atual — mesmo que você não tivesse descrições e exemplos, e mesmo que o modelo de resposta fosse fluido — seria uma grande vitória. Simplesmente saber que algo existe é metade da batalha às vezes.
5 curtidas
A documentação da API está no formato OpenAPI?
https://docs.discourse.org/openapi.json
{
"openapi": "3.1.0",
"info": {
"title": "Discourse API Documentation",
"x-logo": {
"url": "https://docs.discourse.org/logo.svg"
},
"version": "latest",
...
6 curtidas
Devo admitir vergonhosamente que nunca notei isso…
Obrigado @blake por apontar isso.
2 curtidas