RESTful アプリケーションでのリソースの URI パターンの定義
REST (Representational State Transfer) サービス は、リソースの取り扱いをベースにしています。RESTful サービスのリソースはアドレス可能であり、 REST でのアドレス可能性は主として URL によって実現されます。
始める前に
RESTful サービスとして公開するアプリケーション内で リソースを特定します。
このタスクについて
リソースの場所を指定するために URL が使用されます。 サーバーとクライアントの間の対話のベースとなるのは、HTTP オペレーションを URL に 発行することです。最初のディスカバーから長い時間が過ぎた後でも リソースをクライアントが直接アドレス指定できるように URL は長く存続することが 多いため、URL パターンの定義は重要です。
通常、URL が使用されるのは、ユーザーが Web ブラウザーに、例えば http://www.ibm.com/ または http://www.example.com/bookstore/books/ISBN123 のように、アドレスを入力したときです。URL はユーザーが理解しやすいものである必要はありませんが、 RESTful サービスが提供する URL が理解しやすいパターンの論理的なものであると、クライアント・アプリケーション開発者 の作業効率が上がります。
RESTful クライアント は、URL を使用してリソースを取り扱います。各リソースごとに それぞれ固有の URL がなければなりません。コレクション・パスに固有 ID が 付加されている形式の URL パターンもあります。例えば、http://www.example.com/bookstore/books をコレクション・リソース URL と して、http://www.example.com/bookstore/books/ISBN123 を固有の書籍リソース URL として使用できます。 また、http://www.example.com/bookstore/books/ISBN123/authors を 使用して、ISBN123 の著者を記述するコレクション・リソースを取得できます。
URL の細分度 はアプリケーションの使用法とパフォーマンスに影響を与える可能性があるため、 アプリケーション開発者は細分度を慎重に検討する必要があります。例えば、 書籍リソースの一部として著者情報を組み込むようにしたり、 あるいは、独自の URL を持つ固有のリソースとして著者情報を 定義し、その URL を書籍リソース内で参照するようにしたりできます。 リソースの再利用状況によりますが、著者情報に関して別にリソースを定義し、 書籍リソースのハイパーリンク内でそれを参照できるように するほうが、著者に複数の著書がある場合は効率的になると考えられます。
最初に URL がクライアントに 渡された後、それ以降の関連要求は、現在のリソースを解析して 見つけることが可能です。book の例では、http://www.example.com/bookstore/books/ への GET 要求 は、書籍 URL のリストを取得し、それには http://www.example.com/bookstore/books/ISBN123 が含まれている可能性があります。
システム はリソースが使用可能であることに依存しているので、URL の存続期間は長いのが標準的です。 HTTP には転送用の組み込み状況コード (301 永続的移動コード、307 一時転送コードなど) があるため、 キャッシュを使用するユーザーおよびクライアントは、以前に検出された URL を まず最初に再使用することが頻繁にあります。さらに、URL パターンにバージョン ID を組み込む ことを検討できます (例えば http://www.example.com/bookstore/v2/books/ISBN123)。 Java™ コードを使用するインターフェースの定義を計画する際と同様に、 URL パターンは長期間存続すると予期されるので、慎重にパターンを選択してください。
JAX-RS (Java API for RESTful Web Services) では、 リソースの相対 URL を定義するために、@Path アノテーションを Java クラス・ファイル または Java メソッドに追加 する必要があります。JAX-RS サブリソース・ロケーター およびサブリソース・メソッドを使用して、リソースを定義できます。パス・パラメーターやマトリックス・パラメーターなどの パラメーターを URL 内で使用して、リソースを 特定します。
@Path アノテーション中の値は、 リソースへの完全 URL の相対部分を定義します。ベース URL は、 ドメイン、ポート、アプリケーション・モジュール・コンテキスト・ルート、および、 アプリケーション・モジュールの web.xml ファイル内の任意の URL パターン・マッピングから派生します。例えば、 ドメインが www.example.com、 ポートが 9060、モジュール・コンテキスト・ルートが example、 サーブレット URL パターンが store/*、 @Path アノテーションの値が /bookstore/books であるとします。この場合、 完全 URL は http://www.example.com:9060/example/store/bookstore/books です。
手順
タスクの結果
これで、RESTful サービス用にリソースを特定するための URL の 作成が完了しました。アプリケーション設計の初期で URL パターンに関する 問題を検討することによって、RESTful サービスの長期間にわたるユーザビリティーおよび価値が 増します。
次のタスク
リソースは定義された URL に存在します。しかし、 リソースには、HTTP メソッドのアクション (GET、POST、PUT、または DELETE など) を処理するための メソッドがまだありません。サポートされる HTTP メソッドを使用してリソースの機能を定義することについて詳しくは、 RESTful アプリケーションでのリソース・メソッドの定義に 関する説明を参照してください。