API とサーバー

server/ を足すと API が有効になる。ApiContext・HttpError・HTTP メソッドの規約。

Vantage のサーバーはオプションです。プロジェクトに server/ ディレクトリを追加すると API が有効になり、ビルドは fullstack モードに切り替わります。無ければアプリはクライアントのみ（SPA）で、/api/* は単なるクライアントルートとして扱われます（本番と一致）。

API ルートの規約

API は server/api/** から、ページと同じファイル名規約で導出されます。

ファイル	エンドポイント
`server/api/customers.ts`	`/api/customers`
`server/api/customers/[id].ts`	`/api/customers/:id`
`server/api/monthly-analysis.ts`	`/api/monthly-analysis`

各ファイルは HTTP メソッド名の関数をエクスポートします。使えるメソッドは GET / POST / PUT / PATCH / DELETE / OPTIONS。

// server/api/customers/[id].ts  →  /api/customers/:id
import type { ApiContext } from "@squadbase/vantage/server";
import { HttpError } from "@squadbase/vantage/server";

export async function GET({ params, env }: ApiContext) {
  const customer = await findCustomer(params.id!);
  if (!customer) throw new HttpError(404, "Customer not found");
  return Response.json(customer);
}

ApiContext

ハンドラは Web 標準の型で話します。引数の ApiContext は次を持ちます。

プロパティ	内容
`request`	標準の `Request`
`params`	動的パラメータ（`params.id` など）
`env`	サーバー側の環境変数・シークレット
`waitUntil`	レスポンス後のバックグラウンド処理（撃ちっぱなし）

戻り値は標準の Response。Response.json(...) か、ヘルパーの json() を使えます。

import { json } from "@squadbase/vantage/server";

export async function GET() {
  return json({ ok: true });
}

エラーの扱い

クライアントに見せたいエラーは HttpError(status, message) を throw します。これはステータスとメッセージがそのままクライアントへ届きます。

if (!authorized) throw new HttpError(403, "Forbidden");

それ以外の throw されたエラーはサーバーにログされ、クライアントには汎用の 500 として返されます（内部情報は漏れません）。

dev と prod は同一に振る舞う

リクエストのディスパッチ（ルートのマッチ・405 処理・request-id 付与）は dev と prod で 共有された 1 つのコアを通ります。開発時に見えた挙動が、本番でもそのまま再現されます。

シークレットはサーバーだけ

ApiContext.env はサーバー側でのみ読めます。クライアントには決して届きません。API キーや DB 接続情報などはここから読みます。クライアントに露出させたい値の扱いは環境変数を参照してください。

次に読む

環境変数 — シークレットと公開値の境界