【ルーティングの概要】

はじめに

このページでは、REST-API サーバーにおける ルーティングの基本思想 と、 URI とイベント処理の対応付けの仕組み について解説します。

ここで扱う内容は、ルーティングの「概念」や「設計思想」を理解するためのものであり、設定ファイルの詳細仕様やスキャフォールディングについては扱いません。

詳細な設定方法は ▶ルート設定（Setting）を参照してください。

ルーティングの役割

REST-API サーバーにおけるルーティングは、
HTTP メソッド + URI → イベントハンドラのメソッド（またはステートマシンのメソッド）
という対応関係を定義する仕組みです。

例として、次のような対応を管理します。

GET /api/v1/users → getUsers
POST /api/v1/users → postUser
GET /api/v1/files/:id → getFile

ルーティングは API の入口であり、どの処理が呼び出されるかを決定する重要な役割を持ちます。

設定ファイルとしての位置付け

ルーティング設定は、プロジェクト内の設定ファイルとして管理されます。
ファイル名は固定ではなく、メイン処理クラスの設定により任意の名称を使用できます。

メイン処理クラスの設定方法については ▶メイン処理クラス実装（設定ファイル指定）を参照してください。

ルーティングの基本構造（概念）

ルーティングは大きく次の 2 種類の形式で定義されます。

1. 単独ルート

単一の URI とイベント処理を対応付ける最も基本的な形式です。

method: get
uri: /api/v1/status
event: getStatus

2. グループ化されたルート

共通の URI プレフィックスを持つ複数のルートをまとめて管理する形式です。

prefix: /api/v1/users
    GET /:id
    POST /
    DELETE /:id

グループ化により、URI の階層構造を整理しやすくなります。

URI パラメータの概要

ルーティングでは、URI 内にパラメータを含めることができます。

代表的な形式は次のとおりです。

/:id … 通常のパラメータ
/:id([0-9]+) … 正規表現を含むパラメータ
:/...: … URI 全体を正規表現として扱う形式
* … ワイルドカード（柔軟なパス構造に対応）

これらの詳細仕様は ▶ルート設定（Setting）で解説しています。

イベント処理クラスとの関係

ルーティングで指定する event は、イベントハンドラ型またはステートマシン型のイベント処理クラス内のメソッド名を指します。

どのクラスがイベント処理クラスとして使用されるかは、メイン処理クラスの設定によって決定されます。

詳細は ▶メイン処理クラス実装（クラス名指定）を参照してください。

Expect / ミスマッチ処理の概要

ルーティング設定には、次のような特別な処理先を指定できます。

Expect ヘッダ受信時の処理
未定義ルート（ミスマッチ）時の処理

これらはルーティングの拡張的な仕組みであり、API の堅牢性を高めるために利用されます。

詳細な動作仕様は ▶ルート設定（Setting）にて説明しています。

おわりに

このページでは、REST-API サーバーにおけるルーティングの 思想・役割・基本構造 を中心に解説しました。

実際の設定ファイルの書式や詳細仕様、URI パラメータの完全ルール、Expect / mismatch の動作などは「設定ファイル（Setting）」カテゴリにまとめています。

ルーティングの概念を理解した上で詳細仕様ページを参照することで、より正確な実装が行えるようになります。