Routes API

Les plugins peuvent exposer des routes API pour leur UI admin et les intégrations externes. Les routes sont montées sous /_emdash/api/plugins/<slug>/<nom-route> et s’exécutent dans le runtime sandbox avec le même PluginContext que les hooks.

Cette page couvre les plugins sandboxés. La surface API pour les plugins natifs est identique ; la seule différence est la signature du handler — voir Plugins natifs.

Définir des routes

import type { SandboxedPlugin } from "emdash/plugin";
import { z } from "astro/zod";

export default {
	routes: {
		status: {
			handler: async (_routeCtx, ctx) => {
				return { ok: true, plugin: ctx.plugin.id };
			},
		},
		submissions: {
			input: z.object({
				formId: z.string().optional(),
				limit: z.number().default(50),
				cursor: z.string().optional(),
			}),
			handler: async (routeCtx, ctx) => {
				const { formId, limit, cursor } = routeCtx.input;
				const result = await ctx.storage.submissions.query({
					where: formId ? { formId } : undefined,
					orderBy: { createdAt: "desc" },
					limit, cursor,
				});
				return result;
			},
		},
	},
} satisfies SandboxedPlugin;

Les handlers sandboxés prennent deux arguments : (routeCtx, ctx).

Filtrer les champs de contenu indexés

URLs des routes

Authentification et CSRF

Les routes de plugin sont authentifiées par défaut. Utilisez public: true pour les routes publiques.

L’appelant authentifié

Sur les routes privées, routeCtx.user est l’utilisateur authentifié.

Mise en cache des réponses publiques

routes: {
	catalog: {
		public: true,
		cacheControl: "public, max-age=60, stale-while-revalidate=300",
		handler: async (ctx) => listProducts(ctx),
	},
},

Exposer une route comme outil MCP

Validation des entrées

input accepte un schéma Zod.

Valeurs de retour

Retournez toute valeur sérialisable en JSON.

Erreurs

Lancez une exception pour une réponse d’erreur.

Méthodes HTTP

Les routes répondent à toutes les méthodes. Branchez sur routeCtx.request.method.

Patterns courants

Paramètres via KV

Liste paginée

Proxy d’API externe

Appeler des routes depuis l’UI admin

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

Appeler des routes depuis des handlers de file et planifiés

Utilisez withEmDashRuntime() de emdash/middleware.

Appeler des routes en externe

Les routes publiques sont appelables directement. Les routes privées nécessitent des credentials de session ou un token API.

Référence du contexte de 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;
}