API Routes

src/api/<path>/route.ts ファイルは HTTP メソッドごとに1つの関数をエクスポートし、/api/<path> として提供されます:

// GET /api/hello
import type { RouteHandler } from 'murasaki'

export const GET: RouteHandler = async (request) => {
  return Response.json({ message: `Hello from Node ${process.version}` })
}

export const POST: RouteHandler = async (request) => {
  const body = await request.json()
  return Response.json({ received: body })
}

RouteHandler は Web の Request と、params を含む context を受け取り、Web の Response を返します — Response.json(...)、new Response(...)、ステータスコード、ヘッダーなど、すべて標準的なものです。

GET、POST、PUT、PATCH、DELETE、HEAD、OPTIONS のうち、ルートに必要なものをいくつでもエクスポートできます。モジュールがエクスポートしていないメソッドへのリクエストは 405 になり、/api/ 配下でどのルートにもマッチしないリクエストは、アプリの HTML にフォールバックするのではなく 404 になります。

動的セグメント

[name] フォルダはセグメントをキャプチャし、context.params に公開されます:

// GET /api/greet/:name
import type { RouteHandler } from 'murasaki'

export const GET: RouteHandler = async (_request, { params }) => {
  return Response.json({ greeting: `Hello, ${params.name}!` })
}

キャッチオール([...path])とオプショナルキャッチオール([[...path]])フォルダにも対応しています。値はデコード済みのパスセグメント配列になり、省略されたオプショナルキャッチオールは undefined です:

import type { RouteHandler } from 'murasaki'

export const GET: RouteHandler = async (_request, { params }) => {
  return Response.json({ path: params.path ?? [] })
}

ルートを呼び出す

const res = await fetch('/api/hello')
const data = await res.json()

ハンドラは開発時（Vite ミドルウェア）・本番時（バンドルされた Node サーバー）のいずれでもサーバー上で実行されるため、ファイルシステムやデータベース、シークレットなどにアクセスできます。

API ルート vs. サーバーアクション

どちらもサーバー上で実行されます — 使い分けの基準は形です:

• API ルートは、レンダラーと Node Main 向けのアプリ内 HTTP エンドポイントです。開発時・パッケージ済みアプリのいずれでも、呼び出し元のネイティブウィンドウから導出された識別情報と一致する api:METHOD:/path の backendCapabilities 許可が必要なため、一般公開の Webhook エンドポイントとしては使えません。
• サーバーアクション（ガイド）は、React 19 のフォーム / useAction フローに組み込まれた、型付きの RPC です — URL も fetch の定型コードも不要です。

両者は同じアプリの中で共存できます。

次へ