T
rfc6570 uri-template api-design rest web-standards

URIテンプレート徹底解説：API設計のためのRFC 6570マスターガイド

RFC 6570を使用したURIテンプレートの定義と展開方法を学びます。堅牢で柔軟なRESTful APIを構築するために不可欠な標準です。

2026-04-11

URIテンプレート徹底解説：RFC 6570をマスターする

RESTful APIを構築する際、最も重要な概念の1つは、URIを使用してリソースをどのように表現するかです。URLをハードコーディングすることは脆弱であり、メンテナンスの負担を増大させます。RFC 6570 (URI Template) は、最終的なURIに展開できるプレースホルダーを使用してURIを記述するための標準化された方法を提供します。

このガイドでは、URIテンプレートの仕組み、さまざまな式のタイプ、およびそれらが現代のWeb開発において不可欠である理由について深く掘り下げます。

URIテンプレートとは？

URIテンプレートは、中括弧 {} で囲まれた変数を含む文字列です。これらの変数は、Expansion (展開) と呼ばれるプロセス中に実際の値に置き換えられます。

基本的な例:

テンプレート: http://api.example.com/users/{id} 変数: { "id": "123" } 展開後: http://api.example.com/users/123

URIテンプレートの8つのレベル

RFC 6570は、展開の複雑さに応じていくつかのレベルを定義しています。ここでは最も一般的なものを紹介します。

1. 単純な文字列展開 {var}

単純なパスセグメントに使用されます。

  • テンプレート: /{var}
  • 値: {"var": "value"}
  • 結果: /value

2. 予約文字の展開 {+var}

単純な展開に似ていますが、予約文字（/、?、# など）をパーセントエンコーディングせずにそのまま使用できます。

  • テンプレート: /{+path}/index.html
  • 値: {"path": "foo/bar"}
  • 結果: /foo/bar/index.html

3. フラグメント展開 {#var}

URIフラグメント（アンカー）に使用されます。

  • テンプレート: {#var}
  • 値: {"var": "section1"}
  • 結果: #section1

4. ドット付きラベル展開 {.var}

ファイル拡張子によく使用されます。

  • テンプレート: /config{.format}
  • 値: {"format": "json"}
  • 結果: /config.json

5. パスセグメント展開 {/var}

先頭にスラッシュを自動的に追加します。

  • テンプレート: {/var}
  • 値: {"var": "user"}
  • 結果: /user

6. クエリパラメータ展開 {?var}

APIの検索やフィルタリングで最も一般的なタイプです。

  • テンプレート: /search{?q,lang}
  • 値: {"q": "test", "lang": "en"}
  • 結果: /search?q=test&lang=en

変数修飾子

URIテンプレートは、変数の展開方法を制御するための修飾子もサポートしています。

  • 展開 (*): 配列やオブジェクトに使用されます。
    • テンプレート: /users{?id*}
    • 値: {"id": [1, 2, 3]}
    • 結果: /users?id=1&id=2&id=3
  • プレフィックス (:n): 最初の n 文字のみを取得します。
    • テンプレート: /{var:3}
    • 値: {"var": "abcdef"}
    • 結果: /abc

なぜURIテンプレートを使用するのか？

  1. 疎結合: クライアントはURLの構築方法を知る必要がなく、テンプレートと変数だけを知っていれば済みます。
  2. HATEOAS: アプリケーション状態のエンジンとしてのハイパーメディアに不可欠です。サーバーはレスポンス内にテンプレートを提供できます。
  3. 一貫性: さまざまなプログラミング言語やライブラリにわたって、クエリパラメータやパスセグメントを処理するための標準的な方法を提供します。

よくある質問 FAQ

Q: {var} は多くのルーターで使用されている :var と同じですか？ A: 概念的には同じですが、RFC 6570はドキュメントやハイパーメディアでこれらをどのように表現すべきかについての公式な標準です。多くのルーター（ExpressやReact Routerなど）は、簡略化された独自の構文を使用しています。

Q: 予約文字はどう扱えばいいですか？ A: デフォルトの単純な展開 {var} は予約文字をパーセントエンコーディングします。そのまま保持したい場合は {+var} を使用してください。

Q: URIテンプレートはケースセンシティブ（大文字小文字を区別）ですか？ A: 仕様によると変数名はケースセンシティブです。{var} と {VAR} は異なる変数として扱われます。

関連ツール

ブログに戻る