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 です。

手順

  1. アプリケーション内のリソース・タイプを識別します。 2 つのタイプのリソース、BooksCollection および 個別 Book オブジェクトがあり、クラス定義は次のようになっているとします。
    public class BooksCollection {
            public BooksCollection() {
                    /* no argument constructor */
        }
    
    }
    
    public class Book {
            public Book(String ISBN) {
                    /* This constructor has an argument that will be annotated with a JAX-RS annotation.           See the JAX-RS specification for information on valid constructors. */
        }
    }
    JAX-RS 仕様に規定されているように、デフォルトでは、 要求ごとにリソース・インスタンスが作成されます。JAX-RS ランタイム環境で リソース・インスタンスが作成されるためには、引数なしのコンストラクター、 または JAX-RS アノテーション付きのパラメーターのみがあるコンストラクター が必要です。
  2. 各リソース・クラスに @javax.ws.rs.Path アノテーションを追加します。  各 @javax.ws.rs.Path アノテーションごとに、アプリケーションのベース URL の後の URL 部分として 値を設定します。
    /*
     * BooksCollection.java
      * This Java class represents the books collection URL at /bookstore/books.
     */
    @javax.ws.rs.Path("/bookstore/books/")
    public class BooksCollection {
    
    }
    アプリケーションの完成後、 http://<host_name>:<port>/<context_root>/<servlet_path>/bookstore/books にアクセスしてリソースを使用できます。 この URL では、コンテキスト・モジュールの後に URL 部分としてコンテキスト・ルート値を 指定します。あれば、web.xml ファイル内の任意の URL パターンとして、サーブレット・パスを指定 します。
  3. (オプション) URL の一部をパラメーターとして使用する必要のある リソースがあるかどうかを判定します。 ID など、URL の一部をパラメーターとして使用する必要のある リソースがある場合、 正規表現と共に @javax.ws.rs.Path アノテーションを使用することができます。そうすると、 リソース・コンストラクターまたはリソース・メソッド内のいずれかで @javax.ws.rs.PathParam アノテーション を追加できます。
    /*
      * Book.java represents individual books.
      */
    @javax.ws.rs.Path(“/bookstore/books/{bookID}”)
    public class Book {
       public Book(@javax.ws.rs.PathParam("bookID") String ISBN) {
    
       }
    }
    http://<host_name>:<port>/<context_root>/<servlet_path>/bookstore/books/ISBN_number に対して HTTP 要求 が行われると、ISBN_number がコンストラクターに ISBN パラメーターとして 渡されて、Book インスタンスが作成されます。

    使用できる他のパラメーターについて詳しくは、 RESTful アプリケーションでのリソースへの要求に対するパラメーターの定義についての 説明をお読みください。

  4. クラスが JAX-RS アプリケーションの一部である、javax.ws.rs.core.Application サブクラスを作成して、 JAX-RS ランタイム環境に定義します。 次の例のように、リソース・クラスは getClasses() メソッドで戻されます。
    public class BookApplication extends javax.ws.rs.core.Application {
        public Set<Class<?>> getClasses() {
            Set<Class<?>> classes = new HashSet<Class<?>>();
            classes.add(BooksCollection.class);
            classes.add(Book.class);
            return classes;
        }
    }

    javax.ws.rs.core.Application サブクラスを定義することによって、 このサブクラスのメソッドから戻されるクラスが JAX-RS ランタイム環境 に登録されます。web.xml ファイルを構成する際、javax.ws.rs.core.Application サブクラス を、サーブレットまたはフィルターへのパラメーターとして指定する必要があります。詳しくは、 JAX-RS アプリケーション用の web.xml ファイルの構成に関する説明を参照してください。

タスクの結果

これで、RESTful サービス用にリソースを特定するための URL の 作成が完了しました。アプリケーション設計の初期で URL パターンに関する 問題を検討することによって、RESTful サービスの長期間にわたるユーザビリティーおよび価値が 増します。

次のタスク

リソースは定義された URL に存在します。しかし、 リソースには、HTTP メソッドのアクション (GET、POST、PUT、または DELETE など) を処理するための メソッドがまだありません。サポートされる HTTP メソッドを使用してリソースの機能を定義することについて詳しくは、 RESTful アプリケーションでのリソース・メソッドの定義に 関する説明を参照してください。


トピックのタイプを示すアイコン タスク・トピック



タイム・スタンプ・アイコン 最終更新: last_date
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=cord&product=was-nd-mp&topic=twbs_jaxrs_defresource_uri
ファイル名:twbs_jaxrs_defresource_uri.html