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 の仕様に準拠しています。
この動作を変更するには、値が true の wink.searchPolicyContinuedSearch プロパティーを使用します。その結果、要求に合ったサブリソース・メソッドがない場合には、サブリソース・ロケーターが使用されます。
プロパティーを有効にするには、モジュールの WEB-INF ディレクトリーに、wink.searchPolicyContinuedSearch プロパティーと値が指定されたプロパティー・ファイルを組み込みます。アプリケーション・モジュールの web.xml ファイルに、param-name エレメントに対して propertiesLocation 値を指定して init-param エレメントを組み込みます。param-value エレメントは、プロパティーのロケーションを、例えば WEB-INF/my_wink.properties のように指定します。
<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() { ...
手順
タスクの結果
リソースに対する有効なオペレーションの定義が完了しました。