restful-hateoas

コミュニティ向け RESTful HATEOAS ベストプラクティス

Ruby on Rails で REST の栄光（Richardson 成熟度モデルのレベル 3）に到達する REST API を構築するための包括的なガイドです。9 つのカテゴリにわたる 47 のルールを、リクエスト／レスポンスのライフサイクル順に掲載しています。リソース URI の設計から、ハイパーメディアのリンク関係、API の進化までを扱います。

適用する場面

以下の場合に、これらのガイドラインを参照してください。

• 新しい REST API エンドポイントとリソース URI を設計するとき
• API レスポンスにハイパーメディアコントロール（_links、アフォーダンス）を追加するとき
• HAL、JSON:API、またはベンダーメディアタイプを使ったコンテンツネゴシエーションを実装するとき
• ページネーション、フィルタリング、並べ替えに対応したコレクションエンドポイントを構築するとき
• 適切な HTTP メソッドのセマンティクスとステータスコードについて API をレビューするとき
• 既存のクライアントを壊さずに API を進化させるとき

優先度別のルールカテゴリ

優先度	カテゴリ	影響度	プレフィックス
1	リソースモデリング	CRITICAL	res-
2	HTTP メソッドのセマンティクス	CRITICAL	http-
3	ハイパーメディアとリンク関係	CRITICAL	link-
4	ステータスコードとレスポンスヘッダー	HIGH	status-
5	コンテンツネゴシエーションとメディアタイプ	HIGH	media-
6	コレクションパターン	MEDIUM-HIGH	coll-
7	エラーのセマンティクス	MEDIUM	err-
8	キャッシュと条件付きリクエスト	MEDIUM	cache-
9	API の進化	LOW-MEDIUM	evolve-

クイックリファレンス

1. リソースモデリング（CRITICAL）

• res-noun-based-uris - URI には動詞ではなく名詞を使用します
• res-plural-collection-uris - コレクションには必ず複数形の名詞を使用します
• res-limit-nesting-depth - リソースのネストは最大 2 階層までに制限します
• res-model-business-entities - データベーステーブルではなく、ビジネスエンティティをモデル化します
• res-use-consistent-identifiers - 不透明な識別子を使用し、自動採番 ID は使用しません
• res-sub-resources-for-relationships - 関係性はサブリソースとして表現します

2. HTTP メソッドのセマンティクス（CRITICAL）

• http-get-must-be-safe - GET リクエストに副作用が生じないようにします
• http-post-for-creation - POST から Location ヘッダーとともに 201 Created を返します
• http-put-for-full-replacement - PUT はリソース全体の置き換えにのみ使用します
• http-patch-for-partial-updates - マージセマンティクスによる部分更新には PATCH を使用します
• http-delete-is-idempotent - DELETE が冪等になるようにします
• http-head-for-metadata - ボディを転送せずにメタデータを取得するには HEAD を使用します
• http-idempotency-key - POST を安全に再試行するため、冪等性キーを使用します

3. ハイパーメディアとリンク関係（CRITICAL）

• link-self-link-every-resource - すべてのリソースに self リンクを含めます
• link-related-resource-links - 外部キーの代わりに、関連リソースへのリンクを使用します
• link-action-affordances - 利用可能なアクションを条件付きリンクとして公開します
• link-standard-relation-types - IANA に登録されたリンク関係タイプを使用します
• link-entry-point - API のルートエントリーポイントを提供します
• link-pagination-links - ページネーションにハイパーメディアリンクを使用します
• link-embedded-vs-linked - 埋め込みとリンクのどちらを使うか選択します

4. ステータスコードとレスポンスヘッダー（高）

• status-201-with-location - Location ヘッダーを付けて 201 Created を返します
• status-204-for-no-content - 空のレスポンスには 204 No Content を返します
• status-409-for-conflicts - 状態の競合には 409 Conflict を返します
• status-202-for-async - 非同期操作には 202 Accepted を返します
• status-allow-header-on-405 - 不適切なメソッドには Allow ヘッダーを付けて 405 を返します
• status-rate-limit-headers - API レスポンスにレート制限ヘッダーを含めます

5. コンテンツネゴシエーションとメディアタイプ（高）

• media-accept-header-negotiation - コンテンツネゴシエーションでは Accept ヘッダーに従います
• media-content-type-in-responses - すべてのレスポンスに正しい Content-Type を設定します
• media-vendor-media-types - API のバージョン管理にはベンダーメディアタイプを使用します
• media-406-for-unsupported-types - サポートされていないメディアタイプには 406 を返します

6. コレクションのパターン（中〜高）

• coll-cursor-pagination - オフセットではなく、カーソルベースのページネーションを使用します
• coll-link-header-pagination - ページネーションのリンクを本文と Link ヘッダーに含めます
• coll-filtering-via-query-params - 型付きクエリパラメーターによるフィルタリングをサポートします
• coll-sorting-convention - 標準化された sort パラメーターによる並べ替えをサポートします
• coll-field-selection - fields パラメーターによるスパースフィールドセットをサポートします

7. エラーの意味（中）

• err-problem-details - エラーには Problem Details（RFC 9457）を使用します
• err-validation-errors - 構造化されたバリデーションエラーを返します
• err-error-links - エラーレスポンスに復旧用リンクを含めます
• err-machine-readable-codes - 機械可読なエラーコードを使用します
• err-auth-error-codes - 401 Unauthorized と 403 Forbidden を区別します

8. キャッシュと条件付きリクエスト（中）

• cache-etag-conditional-get - 条件付き GET では stale? と ETag を使用します
• cache-last-modified - 時間ベースの検証には Last-Modified を設定します
• cache-cache-control-headers - Cache-Control ヘッダーを明示的に設定します
• cache-vary-header - コンテンツに応じたキャッシュには Vary ヘッダーを含めます

9. API の進化（低〜中）

• evolve-additive-changes-only - レスポンスには追加的な変更のみを行います
• evolve-deprecation-headers - Deprecation ヘッダーと Sunset ヘッダーを使用します
• evolve-hateoas-reduces-versioning - HATEOAS を活用して URL のバージョン管理をなくします

使い方

詳しい説明とコード例については、各リファレンスファイルをお読みください。

• セクションの定義 - カテゴリー構造と影響度
• ルールテンプレート - 新しいルールを追加するためのテンプレート

参照ファイル

ファイル	説明
references/_sections.md	カテゴリの定義と順序
assets/templates/_template.md	新しいルール用のテンプレート
metadata.json	バージョンと参照情報