リポジトリリソース
基礎
Spring Data REST のコア機能は、Spring Data リポジトリのリソースをエクスポートすることです。エクスポートの動作方法を確認し、潜在的にカスタマイズするコアアーティファクトは、リポジトリインターフェースです。次のリポジトリインターフェースを検討してください。
public interface OrderRepository extends CrudRepository<Order, Long> { } このリポジトリの場合、Spring Data REST は /orders でコレクションリソースを公開します。パスは、管理対象のドメインクラスの、大文字を使わない複数形の単純なクラス名から派生します。また、URI テンプレート /orders/{id} でリポジトリによって管理される各アイテムのアイテムリソースも公開します。
デフォルトでは、これらのリソースと対話する HTTP メソッドは、CrudRepository の対応するメソッドにマップされます。詳細については、コレクションリソースとアイテムリソースに関するセクションを参照してください。
リポジトリメソッドの公開
特定のリポジトリに対してどの HTTP リソースが公開されるかは、主にリポジトリの構造によって決まります。つまり、リソースの公開は、リポジトリで公開したメソッドに従います。CrudRepository を継承する場合、通常、デフォルトで登録できるすべての HTTP リソースを公開するために必要なすべてのメソッドを公開します。以下にリストされている各リソースは、特定の HTTP メソッドを各リソースに対して公開できるようにするために、どのメソッドが存在する必要があるかを定義します。つまり、これらのメソッドをまったく宣言しないか、@RestResource(exported = false) を明示的に使用することによって、これらのメソッドを公開していないリポジトリは、これらのリソースでこれらの HTTP メソッドを公開しません。
デフォルトのメソッド公開または専用 HTTP メソッドを個別に微調整する方法の詳細については、サポートされている HTTP メソッドのカスタマイズを参照してください。
デフォルトのステータスコード
公開されているリソースには、一連のデフォルトのステータスコードを使用します。
200 OK: プレーンなGETリクエストの場合。201 Created: 新しいリソースを作成するPOSTおよびPUTリクエストの場合。204 No Content: 構成がリソース更新のレスポンス本文を返さないように設定されている場合のPUT、PATCH、DELETEリクエストの場合（RepositoryRestConfiguration.setReturnBodyOnUpdate(…)）。構成値がPUTのレスポンスを含むように設定されている場合、更新の場合は200 OKが返され、PUTを介して作成されたリソースの場合は201 Createdが返されます。
構成値（RepositoryRestConfiguration.returnBodyOnUpdate(…) および RepositoryRestConfiguration.returnBodyCreate(…)）が明示的に null に設定されている場合（デフォルトでは）、HTTPAccept ヘッダーの存在を使用してレスポンスコードが決定されます。これについて詳しくは、コレクションとアイテムのリソースの詳細な説明を参照してください。
リソースの発見可能性
HATEOAS [GitHub] (英語) の基本原則は、利用可能なリソースを指すリンクを公開することで、リソースを検出できるようにすることです。JSON でリンクを表現する方法については、いくつかの競合するデファクトスタンダードがあります。デフォルトでは、Spring Data REST は HAL [IETF] (英語) を使用してレスポンスをレンダリングします。HAL は、返されたドキュメントのプロパティに含まれるリンクを定義します。
リソースの検出は、アプリケーションのトップレベルから始まります。Spring Data REST アプリケーションがデプロイされているルート URL にリクエストを発行することにより、クライアントは返された JSON オブジェクトから、クライアントが使用できる次のレベルのリソースを表すリンクのセットを抽出できます。
例: アプリケーションのルートで利用可能なリソースを見つけるには、次のようにルート URL に HTTP GET を発行します。
curl -v http://localhost:8080/
< HTTP/1.1 200 OK
< Content-Type: application/hal+json
{ "_links" : {
"orders" : {
"href" : "http://localhost:8080/orders"
},
"profile" : {
"href" : "http://localhost:8080/api/alps"
}
}
}結果ドキュメントのプロパティは、HAL で指定されているように、ネストされたリンクオブジェクトとともに、リレーション型を表すキーで構成されるオブジェクトです。
profile リンクの詳細については、アプリケーションレベルのプロファイルセマンティクス (ALPS) を参照してください。 |
コレクションリソース
Spring Data REST は、エクスポートされたリポジトリが処理しているドメインクラスの大文字を使わない複数形のバージョンにちなんで名付けられたコレクションリソースを公開します。リポジトリインターフェースで @RepositoryRestResource を使用することで、リソースの名前とパスの両方をカスタマイズできます。
サポートされている HTTP メソッド
コレクションリソースは、GET と POST の両方をサポートします。他のすべての HTTP メソッドは 405 Method Not Allowed を引き起こします。
GET
findAll(…) メソッドを介してリポジトリサーバーのすべてのエンティティを返します。リポジトリがページングリポジトリの場合、必要に応じてページネーションリンクと追加のページメタデータを含めます。
呼び出しに使用されるメソッド
存在する場合は、次の方法が使用されます（降順）。
findAll(Pageable)findAll(Sort)findAll()
メソッドのデフォルトの公開の詳細については、リポジトリメソッドの公開を参照してください。
パラメーター
リポジトリにページネーション機能がある場合、リソースは次のパラメーターを取ります。
page: アクセスするページ番号（インデックス付きの 0、デフォルトは 0）。size: リクエストされたページサイズ（デフォルトは 20）。sort:($propertyname,)+[asc|desc]？ 形式のソートディレクティブのコレクション。
HEAD
HEAD メソッドは、コレクションリソースが使用可能かどうかを返します。ステータスコード、メディア型、関連リソースはありません。
呼び出しに使用されるメソッド
存在する場合は、次の方法が使用されます（降順）。
findAll(Pageable)findAll(Sort)findAll()
メソッドのデフォルトの公開の詳細については、リポジトリメソッドの公開を参照してください。
POST
POST メソッドは、指定されたリクエスト本文から新しいエンティティを作成します。デフォルトでは、レスポンスに本文が含まれるかどうかは、リクエストとともに送信される Accept ヘッダーによって制御されます。送信されると、レスポンス本文が作成されます。そうでない場合、レスポンス本文は空であり、作成されたリソースの表現は、Location レスポンスヘッダーに含まれているリンクをたどることによって取得できます。この動作は、RepositoryRestConfiguration.setReturnBodyOnCreate(…) を適切に構成することでオーバーライドできます。
アイテムリソース
Spring Data REST は、コレクションリソースのサブリソースとして個々のコレクションアイテムのリソースを公開します。
サポートされている HTTP メソッド
明示的な構成でそれが妨げられない限り、アイテムリソースは通常 GET、PUT、PATCH、DELETE をサポートします（詳細については "関連付けリソース" を参照）。
GET
GET メソッドは単一のエンティティを返します。
カスタムステータスコード
GET メソッドには、カスタムステータスコードが 1 つだけあります。
405 Method Not Allowed:findOne(…)メソッドが（@RestResource(exported = false)を介して）エクスポートされなかった場合、またはリポジトリに存在しない場合。
関連リソース
ドメイン型のすべての関連付けについて、関連付けプロパティにちなんで名付けられたリンクを公開します。プロパティで @RestResource を使用して、この動作をカスタマイズできます。関連するリソースは、関連付けリソース型です。
PUT
PUT メソッドは、ターゲットリソースの状態を指定されたリクエスト本文に置き換えます。デフォルトでは、レスポンスに本文が含まれるかどうかは、リクエストとともに送信される Accept ヘッダーによって制御されます。リクエストヘッダーが存在する場合、レスポンス本文と 200 OK の状況コードが返されます。ヘッダーが存在しない場合、レスポンス本文は空になり、リクエストが成功すると 204 No Content のステータスが返されます。この動作は、RepositoryRestConfiguration.setReturnBodyOnUpdate(…) を適切に構成することでオーバーライドできます。
PATCH
PATCH メソッドは PUT メソッドに似ていますが、リソースの状態を部分的に更新します。
カスタムステータスコード
PATCH メソッドには、カスタムステータスコードが 1 つだけあります。
405 Method Not Allowed:save(…)メソッドが（@RestResource(exported = false)を介して）エクスポートされなかった場合、またはリポジトリに存在しない場合。
DELETE
DELETE メソッドは、公開されたリソースを削除します。デフォルトでは、レスポンスに本文が含まれるかどうかは、リクエストとともに送信される Accept ヘッダーによって制御されます。リクエストヘッダーが存在する場合は、レスポンスボディとステータスコード 200 OK が返されます。ヘッダーが存在しない場合、レスポンス本文は空で、リクエストが成功すると 204 No Content のステータスが返されます。この動作は、それに応じて RepositoryRestConfiguration.setReturnBodyOnDelete(…) を構成することでオーバーライドできます。
呼び出しに使用されるメソッド
存在する場合は、次の方法が使用されます（降順）。
delete(T)delete(ID)delete(Iterable)
メソッドのデフォルトの公開の詳細については、リポジトリメソッドの公開を参照してください。
関連付けリソース
Spring Data REST は、アイテムリソースが持つ各関連付けのすべてのアイテムリソースのサブリソースを公開します。リソースの名前とパスは、デフォルトで関連付けプロパティの名前になり、関連付けプロパティで @RestResource を使用してカスタマイズできます。
検索リソース
検索リソースは、リポジトリによって公開されているすべてのクエリメソッドへのリンクを返します。クエリメソッドリソースのパスと名前は、メソッド宣言で @RestResource を使用して変更できます。
サポートされている HTTP メソッド
検索リソースは読み取り専用リソースであるため、GET メソッドのみをサポートします。
GET
GET メソッドは、個々のクエリメソッドリソースを指すリンクのリストを返します。
関連リソース
リポジトリで宣言されたすべてのクエリメソッドについて、クエリメソッドリソースを公開します。リソースがページ付けをサポートしている場合、そのリソースを指す URI は、ページ付けパラメーターを含む URI テンプレートです。
クエリメソッドリソース
クエリメソッドリソースは、リポジトリインターフェースの個々のクエリメソッドを介して公開されたクエリを実行します。
