リポジトリリソース
基礎
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 テンプレートです。
クエリメソッドリソース
クエリメソッドリソースは、リポジトリインターフェースの個々のクエリメソッドを介して公開されたクエリを実行します。