E EmDash CMS Everything Guides, use cases, plugins, templates
Deutsch

API-Routen

Auf dieser Seite

Plugins können API-Routen für ihre Admin-UI und externe Integrationen bereitstellen. Routen werden unter /_emdash/api/plugins/<slug>/<route-name> gemountet (der <slug> ist das slug-Feld des Plugins aus emdash-plugin.jsonc — zur Laufzeit als ctx.plugin.id verfügbar) und laufen innerhalb der Sandbox-Laufzeitumgebung mit demselben PluginContext, den auch Hooks erhalten.

Diese Seite behandelt Sandbox-Plugins. Die API-Oberfläche für native Plugins ist identisch; der einzige Unterschied ist die Handler-Signatur — siehe den Hinweis in Native Plugins für Details.

Routen definieren

Deklariere Routen im Standardexport von src/plugin.ts:

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;

satisfies SandboxedPlugin inferiert routeCtx und ctx — keine Parameter-Annotationen nötig. Sandbox-Routen-Handler nehmen zwei Argumente: (routeCtx, ctx).

  • routeCtx enthält request-bezogene Daten: { input, request, requestMeta }.
  • ctx ist derselbe PluginContext, den du in Hooks erhältst — ctx.storage, ctx.kv, ctx.content, ctx.http, ctx.log, etc.

Routen-URLs

Routen werden unter /_emdash/api/plugins/<slug>/<route-name> gemountet. Routennamen können Schrägstriche für verschachtelte Pfade enthalten.

Plugin-IDRoutennameURL
formsstatus/_emdash/api/plugins/forms/status
formssubmissions/_emdash/api/plugins/forms/submissions
seosettings/save/_emdash/api/plugins/seo/settings/save
analyticsevents/recent/_emdash/api/plugins/analytics/events/recent

Authentifizierung und CSRF

Plugin-Routen sind standardmäßig authentifiziert. Der Dispatcher erfordert eine Session (oder ein Token mit dem admin-Scope), bevor er deinen Handler aufruft. Private Routen verwenden standardmäßig die plugins:manage-Berechtigung für Abwärtskompatibilität. Setze permission auf eine engere EmDash-RBAC-Berechtigung, wenn die Operation zu einer vorhandenen Inhalts-, Medien-, Schema- oder Einstellungsfähigkeit gehört:

routes: {
	create: {
		permission: "content:create",
		input: z.object({ title: z.string() }),
		handler: async (routeCtx, ctx) => {
			// ...
		},
	},
},

Private Routen erfordern den X-EmDash-Request: 1 CSRF-Header für cookie-authentifizierte Anfragen. Die Admin-UI sendet ihn automatisch; token-authentifizierte Anfragen sind ausgenommen.

Um eine Route von Auth und CSRF auszunehmen, markiere sie mit public: true:

routes: {
	track: {
		public: true,
		input: z.object({ event: z.string() }),
		handler: async (routeCtx, ctx) => {
			ctx.log.info("Tracked", { event: routeCtx.input.event });
			return { ok: true };
		},
	},
},

Caching öffentlicher Antworten

API-Antworten verwenden standardmäßig Cache-Control: private, no-store. Für öffentliche Routen, die jedem dieselben Daten liefern — ein Produktkatalog, ein öffentlicher Suchindex — bedeutet das, dass jeder Seitenaufruf einen vollständigen Roundtrip zum Origin zahlt. Öffentliche Routen können sich mit cacheControl für CDN/Browser-Caching entscheiden:

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

Der Header wird nur auf erfolgreiche GET-Antworten öffentlicher Routen angewendet. Fehler werden nie gecacht, andere Methoden behalten den Standard, und das Setzen von cacheControl auf einer privaten Route hat keine Wirkung — authentifizierte Antworten bleiben immer private, no-store.

Eine Route als MCP-Tool bereitstellen

Plugins können ausgewählte private Routen explizit über den MCP-Server von EmDash bereitstellen. MCP-Bereitstellung wird nie aus der Routenliste abgeleitet:

const createEventInput = z.object({
	title: z.string().min(1),
	startsAt: z.string().datetime(),
});

export default {
	routes: {
		"events/create": {
			permission: "content:create",
			input: createEventInput,
			handler: async (routeCtx, ctx) => {
				return { id: await createEvent(routeCtx.input, ctx) };
			},
		},
	},
	mcp: {
		tools: {
			createEvent: {
				description: "Create a calendar event when the user asks to add one.",
				route: "events/create",
				input: createEventInput,
				output: z.object({ id: z.string() }),
				destructive: false,
			},
		},
	},
} satisfies SandboxedPlugin;

EmDash stellt dies als <pluginId>__createEvent bereit. Die referenzierte Route muss privat sein und permission deklarieren. Input-Schemas sind erforderlich; Output-Schemas sind optional. Setze destructive: true für Tools, die löschen, überschreiben, veröffentlichen, belasten oder anderweitig schwer rückgängig zu machende Aktionen durchführen.

Ein Administrator muss die MCP-Tools eines Plugins separat aktivieren, nachdem er deren Namen, Beschreibungen, Routen, Berechtigungen und destructive-Flags überprüft hat. Das Aufrufen des Tools erfordert dann sowohl die Routenberechtigung als auch entweder den mcp:tools-Token-Scope oder mcp:tools:<pluginId>.

Eingabevalidierung

input akzeptiert ein Zod-Schema. Der Dispatcher parst den Request-Body (POST/PUT/PATCH) oder den Query-String (GET/DELETE), validiert ihn und übergibt das typisierte Ergebnis als routeCtx.input an deinen Handler. Ungültige Eingabe gibt einen 400-Fehler zurück, bevor dein Handler ausgeführt wird.

routes: {
	create: {
		input: z.object({
			title: z.string().min(1).max(200),
			email: z.string().email(),
			priority: z.enum(["low", "medium", "high"]).default("medium"),
			tags: z.array(z.string()).optional(),
		}),
		handler: async (routeCtx, ctx) => {
			const { title, email, priority, tags } = routeCtx.input;

			await ctx.storage.items.put(`item_${Date.now()}`, {
				title,
				email,
				priority,
				tags: tags ?? [],
				createdAt: new Date().toISOString(),
			});

			return { success: true };
		},
	},
},

Rückgabewerte

Gib einen beliebigen JSON-serialisierbaren Wert zurück. Der Dispatcher verpackt ihn in EmDashs Standard-Envelope ({ success: true, data: <dein Wert> }) und liefert ihn als application/json.

return { id: "abc", count: 42 };  // verpackt zu { success: true, data: { id, count } }
return [1, 2, 3];                 // verpackt zu { success: true, data: [1, 2, 3] }

Fehler

Wirf eine Exception, um eine Fehlerantwort zurückzugeben. Alles, was kein bekannter Plugin-Fehler ist, gibt eine generische Nachricht zurück — interne Exceptions werden maskiert, anstatt Stack-Traces oder Datenbankfehler preiszugeben:

handler: async (routeCtx, ctx) => {
	const item = await ctx.storage.items.get(routeCtx.input.id);
	if (!item) {
		throw new Error("Item not found");
	}
	return item;
},

Für einen bestimmten Statuscode wirf eine Response:

handler: async (routeCtx, ctx) => {
	const item = await ctx.storage.items.get(routeCtx.input.id);
	if (!item) {
		throw new Response(JSON.stringify({ error: "Not found" }), {
			status: 404,
			headers: { "Content-Type": "application/json" },
		});
	}
	return item;
},

HTTP-Methoden

Routen antworten auf alle Methoden. Verzweige auf routeCtx.request.method, wenn du methodenspezifisches Verhalten benötigst:

routes: {
	item: {
		input: z.object({ id: z.string() }),
		handler: async (routeCtx, ctx) => {
			const { id } = routeCtx.input;

			switch (routeCtx.request.method) {
				case "GET":
					return await ctx.storage.items.get(id);
				case "DELETE":
					await ctx.storage.items.delete(id);
					return { deleted: true };
				default:
					throw new Response("Method not allowed", { status: 405 });
			}
		},
	},
},

Auf den Request zugreifen

routeCtx.request ist ein SandboxedRequest: ein portables { url, method, headers }-Objekt, das im Prozess und innerhalb eines Isolates identisch funktioniert. headers ist ein Record<string, string> mit Kleinbuchstaben-Schlüsseln — indexiere nach dem kleingeschriebenen Namen oder iteriere mit Object.entries. url ist ein String, daher parst new URL(request.url) die Query-Parameter. routeCtx.requestMeta enthält IP, User-Agent und Geo-Daten, wenn verfügbar plattformübergreifend normalisiert.

handler: async (routeCtx, ctx) => {
	const { request, requestMeta } = routeCtx;

	const auth = request.headers["authorization"]; // kleingeschriebener Schlüssel, kein .get()
	const url = new URL(request.url);
	const page = url.searchParams.get("page");

	ctx.log.info("Request", { meta: requestMeta });

	if (request.method !== "POST") {
		throw new Response("POST required", { status: 405 });
	}
},

Gängige Muster

Einstellungen über KV

Sandbox-Plugins lesen und schreiben Einstellungen über den KV-Store, konventionell unter einem settings:-Präfix. Das automatisch generierte settingsSchema-Formular ist nur für native Plugins — für Sandbox-Plugins stelle die Lese-/Schreibfunktionalität über Routen bereit und rendere das Formular in Block Kit.

routes: {
	settings: {
		handler: async (_routeCtx, ctx) => {
			const settings = await ctx.kv.list("settings:");
			const result: Record<string, unknown> = {};
			for (const entry of settings) {
				result[entry.key.replace("settings:", "")] = entry.value;
			}
			return result;
		},
	},

	"settings/save": {
		input: z.object({
			enabled: z.boolean().optional(),
			apiKey: z.string().optional(),
			maxItems: z.number().optional(),
		}),
		handler: async (routeCtx, ctx) => {
			for (const [key, value] of Object.entries(routeCtx.input)) {
				if (value !== undefined) {
					await ctx.kv.set(`settings:${key}`, value);
				}
			}
			return { success: true };
		},
	},
},

Paginierte Liste

Gib cursor-basierte Paginierung aus einer Storage-Abfrage zurück — die Antwortstruktur entspricht dem, was der Rest von EmDash verwendet:

routes: {
	list: {
		input: z.object({
			limit: z.number().min(1).max(100).default(50),
			cursor: z.string().optional(),
			status: z.string().optional(),
		}),
		handler: async (routeCtx, ctx) => {
			const { limit, cursor, status } = routeCtx.input;

			const result = await ctx.storage.items.query({
				where: status ? { status } : undefined,
				orderBy: { createdAt: "desc" },
				limit,
				cursor,
			});

			return {
				items: result.items.map((item) => ({ id: item.id, ...item.data })),
				cursor: result.cursor,
				hasMore: result.hasMore,
			};
		},
	},
},

Externer API-Proxy

Leite eine Anfrage an einen externen Dienst über ctx.http weiter (erfordert die network:request-Fähigkeit und einen Eintrag in allowedHosts):

routes: {
	forecast: {
		input: z.object({ city: z.string() }),
		handler: async (routeCtx, ctx) => {
			if (!ctx.http) throw new Error("Network capability not granted");

			const apiKey = await ctx.kv.get<string>("settings:apiKey");
			if (!apiKey) throw new Error("API key not configured");

			const response = await ctx.http.fetch(
				`https://api.weather.example.com/forecast?city=${routeCtx.input.city}`,
				{ headers: { "X-API-Key": apiKey } },
			);

			if (!response.ok) {
				throw new Error(`Weather API error: ${response.status}`);
			}
			return response.json();
		},
	},
},

Routen aus der Admin-UI aufrufen

Verwende usePluginAPI() aus dem Admin-Paket — es fügt den X-EmDash-Request CSRF-Header und das Plugin-ID-Präfix automatisch hinzu:

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

function SettingsPage() {
	const api = usePluginAPI();

	const handleSave = async (settings) => {
		await api.post("settings/save", settings);
	};

	const loadSettings = async () => {
		return api.get("settings");
	};
}

Routen aus Queue- und Scheduled-Handlern aufrufen

Plattform-Event-Handler (ein Cloudflare Queue Consumer, ein benutzerdefinierter scheduled()-Handler) haben keinen HTTP-Request und daher kein locals.emdash. Verwende withEmDashRuntime() aus emdash/middleware, um die Laufzeitumgebung direkt zu erhalten und eine Plugin-Route ohne Request aufzurufen:

import { withEmDashRuntime } from "emdash/middleware";

export default {
	// ... fetch/scheduled von @emdash-cms/cloudflare/worker

	async queue(batch: MessageBatch) {
		await withEmDashRuntime(async (runtime) => {
			for (const message of batch.messages) {
				const result = await runtime.handlePluginApiRoute(
					"my-plugin",
					"POST",
					"/finishJob",
					new Request("https://internal/", {
						method: "POST",
						body: JSON.stringify(message.body),
					}),
				);
				if (result.success) message.ack();
				else message.retry();
			}
		});
	},
};

Dies löst dieselbe gecachte Laufzeitumgebung auf, die Request-Handler verwenden, sodass Plugin-Storage, Hooks und Medienzugriff genau so funktionieren wie während eines Requests. Bei verbindungsbasierten Datenbankadaptern (z.B. Postgres über Hyperdrive) läuft der Callback unter einer Event-scoped Verbindung, die beim Rückgeben committed und geschlossen wird.

Routen extern aufrufen

Öffentliche Routen sind direkt aufrufbar:

curl -X POST https://your-site.com/_emdash/api/plugins/forms/track \
  -H "Content-Type: application/json" \
  -d '{"event": "pageview"}'

Private Routen benötigen Session-Credentials oder ein API-Token mit dem admin-Scope:

curl -X POST https://your-site.com/_emdash/api/plugins/forms/create \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"title": "Hello", "email": "user@example.com"}'

Routen-Kontext-Referenz

// Was Sandbox-Routen-Handler als ihre zwei Argumente erhalten

interface SandboxedRequest {
	url: string;
	method: string;
	headers: Record<string, string>; // Kleinbuchstaben-Schlüssel
}

interface SandboxedRouteContext {
	input: unknown; // einengen mit dem `input`-Zod-Schema auf Routenebene
	request: SandboxedRequest;
	requestMeta?: unknown;
}

interface PluginContext {
	plugin: { id: string; version: string };
	storage: PluginStorage;
	kv: KVAccess;
	log: LogAccess;
	site: SiteInfo;
	url(path: string): string;
	cron?: CronAccess;
	content?: ContentAccess;       // wenn content:read oder content:write deklariert
	taxonomies?: TaxonomyAccess;   // wenn taxonomies:read deklariert
	media?: MediaAccess;           // wenn media:read oder media:write deklariert
	http?: HttpAccess;             // wenn network:request deklariert
	users?: UserAccess;            // wenn users:read deklariert
	email?: EmailAccess;           // wenn email:send deklariert und Provider konfiguriert
}

Native Plugins erhalten ein einzelnes RouteContext-Argument, das die beiden kombiniert — siehe Native Plugins erstellen, wenn du diesen Weg gehst.