# Improving Discourse API documentation for building fully custom frontend community

**URL:** https://meta.discourse.org/t/improving-discourse-api-documentation-for-building-fully-custom-frontend-community/401236
**Category:** Development
**Tags:** rest-api
**Created:** [22 באפריל,‏ 2026,‏ 11:48am UTC](https://meta.discourse.org/t/improving-discourse-api-documentation-for-building-fully-custom-frontend-community/401236 "2026-04-22T11:48:13Z")
**Posts on this page:** 1
**Showing post:** 1

<div class="post-metadata">

### Author: ![Mohamed\_Ahmed2](https://sea3.discourse-cdn.com/meta/user_avatar/meta.discourse.org/mohamed_ahmed2/32/485262_2.png) [@Mohamed\_Ahmed2](https://meta.discourse.org/u/Mohamed_Ahmed2)
#### Post date: [22 באפריל,‏ 2026,‏ 11:48am UTC](https://meta.discourse.org/t/improving-discourse-api-documentation-for-building-fully-custom-frontend-community/401236/1 "2026-04-22T11:48:13Z")

</div>

Hi everyone 👋

I’ve been building a custom frontend using Discourse as a headless backend (Next.js-based architecture), and I’d like to share some practical gaps I’ve encountered in the current API design from a real-world integration perspective.

This is not a critique of Discourse itself (it’s powerful and flexible), but rather feedback to improve DX for modern frontend + API-driven architectures..

* * *

## 1. Pagination & Topic Posts Structure

Current issue:

- Pagination is not always consistent across endpoints

- Topic posts (`/t/{id}.json`) mixes:

- This makes it harder to build clean infinite scroll / normalized state (Redux/Zustand/React Query)

Suggestion:

- Provide clearer separation or optional query flags like:

* * *

## 2. Replies vs Topic Structure

Right now:

- Replies are embedded inside topic response

- No clear separation between:

This causes:

- extra parsing logic in frontend

- duplication when normalizing state

Suggestion:

- Offer dedicated endpoints like:

* * *

## 3. Lack of Field-Level Documentation in API Response

For example in topic response:

- `created_at`

- `bumped_at`

- `last_posted_at`

- `updated_at`

These are not always clearly differentiated.

Problem:

- Developers often misinterpret:

Suggestion:

- Add inline schema documentation or OpenAPI-style metadata:

* * *

## 4. Statistics & Caching Inconsistencies

Issues:

- `posts_count`, `reply_count`, `participants_count` sometimes lag behind real-time data

- heavy reliance on cached counters

Impact:

- inaccurate UI (especially for dashboards / analytics pages)

- requires extra API calls to validate state

Suggestion:

- Add “real-time vs cached” indicator or endpoint variant

- Or provide webhook/event-driven updates for counts

* * *

## 5. Sitemap + SEO + Framework Integration Gaps

When integrating with modern frameworks (Next.js, Nuxt, etc.):

Problems:

- No unified API for:

Developers end up doing:

- multiple API calls per category

- manual diffing for `updated_at`

- pagination crawling to detect updates

Suggestion:

- Add dedicated endpoints:

* * *

## 6. User Metrics & Aggregations Missing

Common needed data:

- total likes received per user

- total likes given

- reaction breakdown per post/user

- engagement stats per category

Current issue:

- requires multiple endpoints + aggregation on frontend

Suggestion:

- Add aggregated endpoints like:

* * *

## 7. User Avatars Flexibility

Current limitation:

- avatars are tightly coupled with Discourse upload system

Request:

- allow external avatar URLs (S3 / CDN / external auth providers)

- support:

This would help with:

- SSO systems

- headless identity providers

* * *

## 8. API Keys: Admin vs User Keys

Clarification needed in docs:

Difference between:

- admin API key

- user API key (created via `/admin/api/keys` or user API endpoints)

Questions:

- lifecycle & expiration rules

- revocation rules per user vs global

- security scope limitations per type

This is critical when building production-grade integrations.

* * *

## Final Thoughts

Discourse API is already powerful, but it feels optimized for “server-rendered forum usage” more than “headless / frontend-driven architecture”.

Modern frameworks (Next.js, Remix, etc.) benefit a lot from:

- fewer round trips

- clearer data boundaries

- predictable caching rules

- better aggregation endpoints

Would love feedback from maintainers or others building headless Discourse setups.

Thanks 🙏

---

_[View the full topic](https://meta.discourse.org/t/improving-discourse-api-documentation-for-building-fully-custom-frontend-community/401236)._