API 라우트

플러그인은 관리 UI와 외부 연동을 위한 API 라우트를 노출할 수 있습니다. 라우트는 /_emdash/api/plugins/<slug>/<라우트명>에 마운트되며 훅이 받는 것과 동일한 PluginContext로 샌드박스 런타임 내에서 실행됩니다.

이 페이지는 샌드박스 플러그인을 다룹니다. 네이티브 플러그인의 API 표면은 동일하며 핸들러 시그니처만 다릅니다 — 네이티브 플러그인을 참조하세요.

라우트 정의

샌드박스 라우트 핸들러는 두 개의 인수를 받습니다: (routeCtx, ctx).

인덱싱된 콘텐츠 필드 필터링

라우트 URL

인증과 CSRF

플러그인 라우트는 기본적으로 인증됩니다. 공개 라우트에는 public: true를 사용합니다.

인증된 호출자

비공개 라우트에서 routeCtx.user는 인증된 사용자입니다.

라우트를 MCP 도구로 노출

입력 유효성 검사

input은 Zod 스키마를 받습니다.

반환값

JSON 직렬화 가능한 값을 반환합니다.

오류

오류 응답을 위해 throw합니다.

HTTP 메서드

라우트는 모든 메서드에 응답합니다. routeCtx.request.method로 분기합니다.

일반적인 패턴

KV를 통한 설정

페이지네이션 목록

외부 API 프록시

관리 UI에서 라우트 호출

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

큐 및 예약 핸들러에서 라우트 호출

emdash/middleware의 withEmDashRuntime()을 사용합니다.

외부에서 라우트 호출

공개 라우트는 직접 호출 가능합니다. 비공개 라우트는 세션 자격 증명 또는 API 토큰이 필요합니다.

라우트 컨텍스트 참조

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;
}