Route API

I plugin possono esporre route API per la loro UI admin e integrazioni esterne. Le route sono montate sotto /_emdash/api/plugins/<slug>/<nome-route> e vengono eseguite nel runtime sandbox con lo stesso PluginContext che ricevono gli hook.

Questa pagina copre i plugin sandboxed. La superficie API per i plugin nativi è identica; l’unica differenza è la firma dell’handler — vedi Plugin nativi.

Definire le route

Gli handler delle route sandboxed prendono due argomenti: (routeCtx, ctx).

Filtrare campi di contenuto indicizzati

URL delle route

Autenticazione e CSRF

Le route dei plugin sono autenticate per impostazione predefinita. Usa public: true per le route pubbliche.

Il chiamante autenticato

Sulle route private, routeCtx.user è l’utente autenticato.

Esporre una route come strumento MCP

Validazione dell’input

input accetta uno schema Zod.

Valori di ritorno

Restituisci qualsiasi valore serializzabile in JSON.

Errori

Lancia un errore per una risposta di errore.

Metodi HTTP

Le route rispondono a tutti i metodi. Ramifica su routeCtx.request.method.

Pattern comuni

Impostazioni tramite KV

Lista paginata

Proxy API esterno

Chiamare route dall’UI admin

import { usePluginAPI } from "@emdash-cms/admin";

Chiamare route da handler di coda e pianificati

Usa withEmDashRuntime() da emdash/middleware.

Chiamare route esternamente

Le route pubbliche sono chiamabili direttamente. Le route private richiedono credenziali di sessione o un token API.

Riferimento contesto route

interface SandboxedRouteContext {
	input: unknown;
	request: SandboxedRequest;
	requestMeta?: unknown;
	user?: UserInfo;
}

interface PluginContext {
	plugin: { id: string; version: string };
	storage: PluginStorage;
	kv: KVAccess;
	log: LogAccess;
	site: SiteInfo;
	content?: ContentAccess;
	taxonomies?: TaxonomyAccess;
	media?: MediaAccess;
	http?: HttpAccess;
	users?: UserAccess;
	email?: EmailAccess;
}