Melhorando a documentação da API do Discourse para criar uma comunidade frontend totalmente personalizada

Dev
1

Olá a todos :waving_hand:

Tenho desenvolvido um frontend personalizado usando o Discourse como backend headless (arquitetura baseada em Next.js) e gostaria de compartilhar algumas lacunas práticas que encontrei no design atual da API, sob uma perspectiva de integração do mundo real.

Isso não é uma crítica ao próprio Discourse (ele é poderoso e flexível), mas sim um feedback para melhorar a DX (Experiência do Desenvolvedor) para arquiteturas modernas de frontend + orientadas a API.

1. Paginação e Estrutura de Posts do Tópico

Problema atual:

  • A paginação nem sempre é consistente entre os endpoints

  • Os posts do tópico (/t/{id}.json) misturam:

    • o post original

    • as respostas

    • metadados internos

Isso dificulta a criação de scroll infinito limpo ou estado normalizado (Redux/Zustand/React Query).

Sugestão:

  • Fornecer uma separação mais clara ou flags de consulta opcionais como:

    • ?include_first_post=true|false

    • ?posts_only=replies

    • Suporte a paginação baseada em cursor (em vez de apenas baseada em página)

2. Respostas vs. Estrutura do Tópico

Atualmente:

  • As respostas estão embutidas dentro da resposta do tópico

  • Não há separação clara entre:

    • “metadados do tópico”

    • “fluxo de posts”

Isso causa:

  • lógica de parsing extra no frontend

  • duplicação ao normalizar o estado

Sugestão:

  • Oferecer endpoints dedicados como:

    • /t/{id}/posts

    • /t/{id}/replies

    • ou suporte a filtragem dentro de /t/{id}.json

3. Falta de Documentação em Nível de Campo na Resposta da API

Por exemplo, na resposta do tópico:

  • created_at

  • bumped_at

  • last_posted_at

  • updated_at

Esses campos nem sempre são claramente diferenciados.

Problema:

  • Desenvolvedores frequentemente interpretam mal:

    • bumped_at vs updated_at

    • o que dispara a “atividade do tópico”

Sugestão:

  • Adicionar documentação de esquema inline ou metadados no estilo OpenAPI:

    • significado de cada campo

    • explicação do ciclo de vida

4. Inconsistências em Estatísticas e Cache

Problemas:

  • posts_count, reply_count, participants_count às vezes ficam defasados em relação aos dados em tempo real

  • forte dependência de contadores em cache

Impacto:

  • UI imprecisa (especialmente para dashboards/páginas de análise)

  • requer chamadas de API extras para validar o estado

Sugestão:

  • Adicionar um indicador de “tempo real vs. cache” ou variante de endpoint

  • Ou fornecer atualizações baseadas em webhooks/eventos para contagens

5. Lacunas em Sitemap + SEO + Integração com Frameworks

Ao integrar com frameworks modernos (Next.js, Nuxt, etc.):

Problemas:

  • Não há uma API unificada para:

    • tópicos atualizados para geração de sitemap

    • rastreamento de última alteração no nível da categoria

    • suporte completo à indexação de posts

Desenvolvedores acabam fazendo:

  • múltiplas chamadas de API por categoria

  • comparação manual de updated_at

  • varredura de paginação para detectar atualizações

Sugestão:

  • Adicionar endpoints dedicados:

    • /categories/updated

    • /topics/changes?since=timestamp

    • /sitemap.json (feed de sitemap orientado a API)

6. Métricas de Usuário e Agregações em Falta

Dados comumente necessários:

  • total de curtidas recebidas por usuário

  • total de curtidas dadas

  • detalhamento de reações por post/usuário

  • estatísticas de engajamento por categoria

Problema atual:

  • requer múltiplos endpoints + agregação no frontend

Sugestão:

  • Adicionar endpoints agregados como:

    • /users/{id}/stats

    • /topics/{id}/stats

7. Flexibilidade de Avatares de Usuário

Limitação atual:

  • avatares estão fortemente acoplados ao sistema de upload do Discourse

Solicitação:

  • permitir URLs de avatar externos (S3 / CDN / provedores de autenticação externos)

  • suportar:

    • external_avatar_url

Isso ajudaria com:

  • sistemas SSO

  • provedores de identidade headless

8. Chaves de API: Admin vs. Chaves de Usuário

Necessidade de esclarecimento na documentação:

Diferença entre:

  • chave de API de admin

  • chave de API de usuário (criada via /admin/api/keys ou endpoints de API de usuário)

Perguntas:

  • regras de ciclo de vida e expiração

  • regras de revogação por usuário vs. global

  • limitações de escopo de segurança por tipo

Isso é crítico ao construir integrações de nível de produção.

Considerações Finais

A API do Discourse já é poderosa, mas parece otimizada para “uso de fórum renderizado no servidor” mais do que para “arquitetura headless/orientada a frontend”.

Frameworks modernos (Next.js, Remix, etc.) se beneficiam muito de:

  • menos idas e vindas (round trips)

  • limites de dados mais claros

  • regras de cache previsíveis

  • melhores endpoints de agregação

Adoraria receber feedback dos mantenedores ou de outros que estão construindo configurações headless do Discourse.

Obrigado :folded_hands:

2

Outra coisa que notei e que me irrita é que algumas endpoints são ‘protegidas’ usando formencoding em vez de JSON, talvez para desencorajar pessoas de mexer com a API? O melhor exemplo disso é a API de rastreamento de cliques em links, o que, supõe-se, faz sentido como proteção, mas qualquer pessoa ainda pode abusar dela se realmente quiser. Então, no final das contas, isso apenas torna mais difícil para os desenvolvedores fazerem o que precisam.