RESTful アプリケーションのためのリソース・メソッドの定義

個々のリソースは、サポートされる HTTP メソッドを使用して、そのリソースの機能を 定義できます。REST (Representational State Transfer) サービス では、サポートされるメソッドは GET、PUT、DELETE、および POST です。すべての オペレーションは、ある 1 つのリソースに対して、事前定義された HTTP メソッドの 1 つを使用して実行される のが一般的です。

始める前に

事前定義された HTTP メソッドおよび既知のメソッドの属性を理解しておいてください。HTTP メソッドには、 安全である (要求の発行でリソースが変更されない) とされているものや、 べき等 (オペレーションを複数回起動しても結果が変わらない) の性質を持つものがあります。 HTTP メソッドは特定の属性を持つよう定義されていて、 サービス実装はそれらの定義に従います。HTTP の一般的な一連のメソッドについて詳しくは、HTTP メソッド定義に関する資料を参照してください。

このタスクについて

クライアントは HTTP メソッドを使用して特定の操作を実行します。 固有のインターフェースがシステムごとに定義されている他の分散システムとは異なり、HTTP に基づいた RESTful システムは主に事前定義されたメソッドに依存します。最も一般的な 4 つのメソッドが、GET、PUT、DELETE、および POST です。 リソースでは、すべてのクライアントに対してすべての HTTP メソッドを許可する必要はありません。

HTTP GET メソッドは、リソースの表示を取り出します。これは安全で、べき等です。GET 要求を繰り返しても、リソースは変更されません。

HTTP PUT メソッド は、通常、リソースを更新するため、または、新しいエンティティーを既知の URL に作成 するために使用されます。リソースを更新または作成する必要がある場合、新しいリソース・データを要求エンティティー (メッセージ本体としても知られる) として含む HTTP PUT メソッドがリソース URL で発行されます。HTTP PUT メソッド は、べき等なので、同じエンティティー、同じ URL への同一の PUT 要求が複数あっても、 1 つだけの PUT 要求が発行された場合と同じ結果に なります。このメソッドは、関連する要求が他に何も行われなかったことを 想定しています。

HTTP DELETE メソッドは、特定の URL にあるリソースを除去します。

HTTP POST メソッドは、最終的なリソース URL が不明な場合にコレクション内にリソースを作成している間に頻繁に使用されます。例えば管理者が、/users コレクション・リソースに対して、1234567890 などの固有 ID を持つユーザーを作成する POST 要求を発行したとします。この場合、固有 ID が、新規ユーザー・リソースを 記述するための URL パスの一部として使用されます (例:/users/1234567790)。これは安全 ではなく、べき等でもありません。この場合、ユーザーが同じ情報を持っていても、/users コレクションに対する複数の POST 要求によって、新規の固有 ID が継続して作成され、この新規 ID がユーザー・コレクションに追加され続けます。

ほとんどの RESTful サービス は予期された結果が得られる既知の HTTP メソッドを使用するので、 より簡単にクライアントを作成できます。RESTful サービス開発者は、 HTTP メソッドの予期される動作を利用できます。リソース・メソッドは、 パラメーター (パス・パラメーター、照会パラメーター、マトリックス・パラメーターなど) を 使用して、リソースを特定することもできます。詳細については、リソースへの要求表示のためのパラメーター使用の定義に関する項を参照してください。

(オプション) 所有するサブリソース・メソッドおよびサブリソース・ロケーター・メソッドに @Path アノテーションがあり、それらの同一のリソース・クラスが同一の値に指定されている場合、デフォルトでは、呼び出すメソッドを決めるときに、サブリソース・ロケーターは考慮されません。これは、JAX-RS の仕様に準拠しています。

この動作を変更するには、値が truewink.searchPolicyContinuedSearch プロパティーを使用します。その結果、要求に合ったサブリソース・メソッドがない場合には、サブリソース・ロケーターが使用されます。

プロパティーを有効にするには、モジュールの WEB-INF ディレクトリーに、wink.searchPolicyContinuedSearch プロパティーと値が指定されたプロパティー・ファイルを組み込みます。アプリケーション・モジュールの web.xml ファイルに、param-name エレメントに対して propertiesLocation 値を指定して init-param エレメントを組み込みます。param-value エレメントは、プロパティーのロケーションを、例えば WEB-INF/my_wink.properties のように指定します。

以下に、web.xml ファイルの例を示します。
<servlet>
    ...
    ...
    <init-param>
        <param-name>propertiesLocation</param-name>
        <param-value>/WEB-INF/my_wink.properties</param-value>
    </init-param>
  </servlet>
次に、WEB-INF/my_wink.properties プロパティー・ファイルの例を示します。
wink.searchPolicyContinuedSearch=true

次のコード例では、要求 URL がsayhello で終了しますが、要求に GET の代わりに POST が含まれているため、HTTP 405 Method Not Allowed のエラー・メッセージが戻されます。405 を回避するために、送信された HTTP メソッドがメソッド・アノテーションと一致するようにしてください。

@javax.ws.rs.Path("helloworld")
public class SampleResource {

...

@javax.ws.rs.Path("sayhello")
@javax.ws.rs.GET
public String getHello() { ...

手順

  1. アプリケーション内のリソース・タイプを識別します。
    各リソース・クラスごとに、サポートされる各 HTTP メソッドについて、起動する既存のメソッドを識別するか、 メソッドを作成します。HTTP 要求に応答するメソッドは、リソース・メソッドとしても知られています。 リソース・クラス内の各リソース・メソッドについて、 @javax.ws.rs.GET、@javax.ws.rs.POST、@javax.ws.rs.DELETE、または @javax.ws.rs.PUT などの JAX-RS HTTP メソッド・アノテーション を 1 つ Java™ メソッドに付けます。例えば、BooksCollection クラスによって HTTP GET メソッド がサポートされている場合、以下のスニペットのようなメソッドを作成し、アノテーションを付けることが できます。
    @javax.ws.rs.Path("/bookstore/books/")
    public class BooksCollection {
        @javax.ws.rs.GET
            public String getBooksCollection() {
                    String str = /* Construct a String representation of the resource. */
            		return str;
        }
    }
    Web ブラウザーまたは別の HTTP クライアントを使用して、http://<host_name>:<port>/<context_root>/<servlet_path>/bookstore/books URL に HTTP GET 要求を発行すると、前の getBooksCollection() メソッドが起動されます。
  2. 必要な HTTP メソッドをリソースがサポートしていることを確認します。
    各リソースには通常、複数のリソース・メソッドがあります。例:
    @javax.ws.rs.Path(“/bookstore/books/{bookID}”)
    public class Book {
            /* This is a database key. */
            private String ISBN;
    
        public Book(@javax.ws.rs.PathParam("bookID") String ISBN) {
                    this.ISBN = ISBN;
        }
    
        @javax.ws.rs.GET
            public String retrieveSpecificBookInformation() {
                    /* This code retrieves a book resource based on the ISBN key. */
        }
    
        @javax.ws.rs.PUT
            public String updateBookInformation(String updatedBookInfo) {
                    /* This code updates the book resource based on ISBN key and the entity (message body) sent in the request that is stored in updatedBookInfo. */
        }
    
        @javax.ws.rs.DELETE
        public void removeBook() {
                    /* This code deletes a book resource based on ISBN key. */
        }
    }
    Web ブラウザーまたは別の HTTP クライアントを使用して、http://<host_name>:<port>/<context_root>/<servlet_path>/bookstore/books/<isbn_number> URL に HTTP GET 要求を発行すると、retrieveSpecificBookInformation() メソッドが起動されます。HTTP PUT 要求を同じ URL に送信すると、updateBookInformation メソッドが呼び出され、要求メッセージ本体のすべてのコンテンツは updatedBookInfo オブジェクトの値として渡されます。最後に、同じ URL に HTTP DELETE 要求を送信すると、 removeBook() メソッドが起動されます。
    トラブルの回避 (Avoid trouble) トラブルの回避 (Avoid trouble): JAX-RS 仕様によると、複数の HTTP メソッド・アノテーション、例えば @javax.ws.rs.POST または @javax.ws.rs.PUT を同じリソース・メソッドに付けることはできません。HTTP メソッドには一意的に定義された意味構造があるため、1 つのリソース・メソッドを複数の HTTP メソッド用に使用しないでください。gotcha

タスクの結果

リソースに対する有効なオペレーションの定義が完了しました。


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



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