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 Process 向けのアプリローカル HTTP エンド ポイントです。パッケージ版ではアプリ実行時セッションで保護されるため、公開 Webhook エンドポイントではありません。
• サーバーアクション(ガイド)は、React 19 のフォー ム / useAction フローに組み込まれた、型付きの RPC です — URL も fetch の定型コー ドも不要です。

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

次へ