Skip to main content

Module api

Module api 

Source
Expand description

REST API v2 — public reads plus member login.

Lets headless frontends (Next.js / Nuxt / Astro / SvelteKit) read pages, images, and documents over JSON — pagination, sparse-field selection, tree filters (child_of / descendant_of / ancestor_of), translation siblings, locale, search, ordering.

§Mounting

Host apps build the API router alongside the public CMS router:

ⓘ
use std::sync::Arc;
use axum::Router;

let api = rustango_cms::api::router();
let public = rustango_cms::router_at("/p", tera);
let app = Router::new().merge(api).merge(public);

All routes live under /api/v2/….

§Endpoints

The core routes are below; ROUTE_PATHS and GET /api/v2/openapi.json are the complete list (tree, menus, locales, search, changes).

PathReturns
GET /api/v2/pages/paginated page list (published only)
GET /api/v2/pages/find/?html_path=…resolve a URL path → 302 to its detail
GET /api/v2/pages/{id}/single page + extension fields
GET /api/v2/images/paginated image list
GET /api/v2/images/{id}/single image metadata
GET /api/v2/documents/paginated document list
GET /api/v2/documents/{id}/single document metadata
GET /api/v2/snippets/paginated snippet list (?type= to filter)
GET /api/v2/snippets/{id}/single snippet
POST /api/v2/auth/loginmember bearer token (see auth)

§Response shape

Every list response carries { meta: { total_count, limit, offset }, items: [...] }. Per-row shape: a meta sub-object with type, detail_url, plus the content fields hoisted to the top level. Sparse selection (?fields=) filters which content fields appear; meta is always present.

View-restricted pages are gated by the same view_restriction_guard the public renderer uses; a member authenticates with the session cookie or the bearer token from auth/login.

§Not provided

  • Write API (POST/PUT/PATCH on content)
  • GraphQL
  • Browsable HTML renderer

Modules§

auth
POST /api/v2/auth/login — a member session a browser SPA can hold.
changes
GET /api/v2/changes/ — has anything moved?
documents
GET /api/v2/documents/ + GET /api/v2/documents/{id}/.
error
A machine-readable error body for the v2 API.
http_cache
Conditional requests and cache directives for the v2 API.
images
GET /api/v2/images/ + GET /api/v2/images/{id}/.
locales
GET /api/v2/locales/ — which content locales this tenant serves.
menus
GET /api/v2/menus/ + GET /api/v2/menus/{slug}/.
openapi
GET /api/v2/openapi.json — the API describing itself.
pages
GET /api/v2/pages/ + GET /api/v2/pages/{id}/.
query
Shared query helpers for the v2 API.
search
GET /api/v2/search/?q= — one search box, every content type.
snippets
GET /api/v2/snippets/ + GET /api/v2/snippets/{id}/.
tree
GET /api/v2/pages/tree/ — the site’s page structure, nested.

Enums§

Cors
Cross-origin policy for router_with.

Constants§

PREFIX
Path prefix every v2 endpoint lives under.
ROUTE_PATHS
Every path this router serves, in one list.

Functions§

router
Build the public JSON API router rooted at /api/v2, with no CORS.
router_with
router, with a cross-origin policy.