リポジトリリソース

基礎

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: 構成がリソース更新のレスポンス本文を返さないように設定されている場合の PUTPATCHDELETE リクエストの場合(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] ? 形式のソートディレクティブのコレクション。

カスタムステータスコード

GET メソッドには、カスタムステータスコードが 1 つだけあります。

  • 405 Method Not AllowedfindAll(…) メソッドが(@RestResource(exported = false) を介して)エクスポートされなかった場合、またはリポジトリに存在しない場合。

サポートされているメディア型

GET メソッドは、次のメディア型をサポートします。

  • application/hal+json

  • application/json

GET メソッドは、関連するリソースを検出するための単一のリンクをサポートします。

HEAD

HEAD メソッドは、コレクションリソースが使用可能かどうかを返します。ステータスコード、メディア型、関連リソースはありません。

呼び出しに使用されるメソッド

存在する場合は、次の方法が使用されます(降順)。

  • findAll(Pageable)

  • findAll(Sort)

  • findAll()

メソッドのデフォルトの公開の詳細については、リポジトリメソッドの公開を参照してください。

POST

POST メソッドは、指定されたリクエスト本文から新しいエンティティを作成します。デフォルトでは、レスポンスに本文が含まれるかどうかは、リクエストとともに送信される Accept ヘッダーによって制御されます。送信されると、レスポンス本文が作成されます。そうでない場合、レスポンス本文は空であり、作成されたリソースの表現は、Location レスポンスヘッダーに含まれているリンクをたどることによって取得できます。この動作は、RepositoryRestConfiguration.setReturnBodyOnCreate(…) を適切に構成することでオーバーライドできます。

呼び出しに使用されるメソッド

存在する場合は、次の方法が使用されます(降順)。

  • save(…)

メソッドのデフォルトの公開の詳細については、リポジトリメソッドの公開を参照してください。

カスタムステータスコード

POST メソッドには、カスタムステータスコードが 1 つだけあります。

  • 405 Method Not Allowedsave(…) メソッドが(@RestResource(exported = false) を介して)エクスポートされなかった場合、またはリポジトリにまったく存在しない場合。

サポートされているメディア型

POST メソッドは、次のメディア型をサポートします。

  • application/hal+json

  • application/json

アイテムリソース

Spring Data REST は、コレクションリソースのサブリソースとして個々のコレクションアイテムのリソースを公開します。

サポートされている HTTP メソッド

明示的な構成でそれが妨げられない限り、アイテムリソースは通常 GETPUTPATCHDELETE をサポートします(詳細については "関連付けリソース" を参照)。

GET

GET メソッドは単一のエンティティを返します。

呼び出しに使用されるメソッド

存在する場合は、次の方法が使用されます(降順)。

  • findById(…)

メソッドのデフォルトの公開の詳細については、リポジトリメソッドの公開を参照してください。

カスタムステータスコード

GET メソッドには、カスタムステータスコードが 1 つだけあります。

  • 405 Method Not AllowedfindOne(…) メソッドが(@RestResource(exported = false) を介して)エクスポートされなかった場合、またはリポジトリに存在しない場合。

サポートされているメディア型

GET メソッドは、次のメディア型をサポートします。

  • application/hal+json

  • application/json

ドメイン型のすべての関連付けについて、関連付けプロパティにちなんで名付けられたリンクを公開します。プロパティで @RestResource を使用して、この動作をカスタマイズできます。関連するリソースは、関連付けリソース型です。

HEAD

HEAD メソッドは、アイテムリソースが使用可能かどうかを返します。ステータスコード、メディア型、関連リソースはありません。

呼び出しに使用されるメソッド

存在する場合は、次の方法が使用されます(降順)。

  • findById(…)

メソッドのデフォルトの公開の詳細については、リポジトリメソッドの公開を参照してください。

PUT

PUT メソッドは、ターゲットリソースの状態を指定されたリクエスト本文に置き換えます。デフォルトでは、レスポンスに本文が含まれるかどうかは、リクエストとともに送信される Accept ヘッダーによって制御されます。リクエストヘッダーが存在する場合、レスポンス本文と 200 OK の状況コードが返されます。ヘッダーが存在しない場合、レスポンス本文は空になり、リクエストが成功すると 204 No Content のステータスが返されます。この動作は、RepositoryRestConfiguration.setReturnBodyOnUpdate(…) を適切に構成することでオーバーライドできます。

呼び出しに使用されるメソッド

存在する場合は、次の方法が使用されます(降順)。

  • save(…)

メソッドのデフォルトの公開の詳細については、リポジトリメソッドの公開を参照してください。

カスタムステータスコード

PUT メソッドには、カスタムステータスコードが 1 つだけあります。

  • 405 Method Not Allowedsave(…) メソッドが(@RestResource(exported = false) を介して)エクスポートされなかった場合、またはリポジトリにまったく存在しない場合。

サポートされているメディア型

PUT メソッドは、次のメディア型をサポートします。

  • application/hal+json

  • application/json

PATCH

PATCH メソッドは PUT メソッドに似ていますが、リソースの状態を部分的に更新します。

呼び出しに使用されるメソッド

存在する場合は、次の方法が使用されます(降順)。

  • save(…)

メソッドのデフォルトの公開の詳細については、リポジトリメソッドの公開を参照してください。

カスタムステータスコード

PATCH メソッドには、カスタムステータスコードが 1 つだけあります。

  • 405 Method Not Allowedsave(…) メソッドが(@RestResource(exported = false) を介して)エクスポートされなかった場合、またはリポジトリに存在しない場合。

サポートされているメディア型

PATCH メソッドは、次のメディア型をサポートします。

DELETE

DELETE メソッドは、公開されたリソースを削除します。デフォルトでは、レスポンスに本文が含まれるかどうかは、リクエストとともに送信される Accept ヘッダーによって制御されます。リクエストヘッダーが存在する場合は、レスポンスボディとステータスコード 200 OK が返されます。ヘッダーが存在しない場合、レスポンス本文は空で、リクエストが成功すると 204 No Content のステータスが返されます。この動作は、それに応じて RepositoryRestConfiguration.setReturnBodyOnDelete(…) を構成することでオーバーライドできます。

呼び出しに使用されるメソッド

存在する場合は、次の方法が使用されます(降順)。

  • delete(T)

  • delete(ID)

  • delete(Iterable)

メソッドのデフォルトの公開の詳細については、リポジトリメソッドの公開を参照してください。

カスタムステータスコード

DELETE メソッドには、カスタムステータスコードが 1 つだけあります。

  • 405 Method Not Alloweddelete(…) メソッドが(@RestResource(exported = false) を介して)エクスポートされなかった場合、またはリポジトリに存在しない場合。

関連付けリソース

Spring Data REST は、アイテムリソースが持つ各関連付けのすべてのアイテムリソースのサブリソースを公開します。リソースの名前とパスは、デフォルトで関連付けプロパティの名前になり、関連付けプロパティで @RestResource を使用してカスタマイズできます。

サポートされている HTTP メソッド

関連付けリソースは、次のメディア型をサポートします。

  • GET

  • PUT

  • POST

  • DELETE

GET

GET メソッドは、関連付けリソースの状態を返します。

サポートされているメディア型

GET メソッドは、次のメディア型をサポートします。

  • application/hal+json

  • application/json

PUT

PUT メソッドは、指定された URI が指すリソースを関連付けリソースにバインドします(サポートされているメディア型を参照)。

カスタムステータスコード

PUT メソッドには、カスタムステータスコードが 1 つだけあります。

  • 400 Bad Request: 1 対 1 の関連付けに複数の URI が指定された場合。

サポートされているメディア型

PUT メソッドは、次の 1 つのメディア型のみをサポートします。

  • text/uri-list: 関連付けにバインドするリソースを指す URI。

POST

POST メソッドは、コレクションの関連付けに対してのみサポートされます。コレクションに新しい要素を追加します。

サポートされているメディア型

POST メソッドは、次の 1 つのメディア型のみをサポートします。

  • text/uri-list: 関連付けに追加するリソースを指す URI。

DELETE

DELETE メソッドは、関連付けをアンバインドします。

カスタムステータスコード

POST メソッドには、カスタムステータスコードが 1 つだけあります。

  • 405 Method Not Allowed: 関連付けがオプションではない場合。

検索リソース

検索リソースは、リポジトリによって公開されているすべてのクエリメソッドへのリンクを返します。クエリメソッドリソースのパスと名前は、メソッド宣言で @RestResource を使用して変更できます。

サポートされている HTTP メソッド

検索リソースは読み取り専用リソースであるため、GET メソッドのみをサポートします。

GET

GET メソッドは、個々のクエリメソッドリソースを指すリンクのリストを返します。

サポートされているメディア型

GET メソッドは、次のメディア型をサポートします。

  • application/hal+json

  • application/json

リポジトリで宣言されたすべてのクエリメソッドについて、クエリメソッドリソースを公開します。リソースがページ付けをサポートしている場合、そのリソースを指す URI は、ページ付けパラメーターを含む URI テンプレートです。

HEAD

HEAD メソッドは、検索リソースが使用可能かどうかを返します。404 戻りコードは、使用可能なクエリメソッドリソースがないことを示します。

クエリメソッドリソース

クエリメソッドリソースは、リポジトリインターフェースの個々のクエリメソッドを介して公開されたクエリを実行します。

サポートされている HTTP メソッド

クエリメソッドリソースは読み取り専用リソースであるため、GET のみをサポートします。

GET

GET メソッドは、クエリの結果を返します。

パラメーター

クエリメソッドにページネーション機能(リソースを指す URI テンプレートに示されている)がある場合、リソースは次のパラメーターを取ります。

  • page: アクセスするページ番号(インデックス付きの 0、デフォルトは 0)。

  • size: リクエストされたページサイズ(デフォルトは 20)。

  • sort($propertyname,)+[asc|desc] ? 形式のソートディレクティブのコレクション。

サポートされているメディア型

GET メソッドは、次のメディア型をサポートします。

  • application/hal+json

  • application/json

HEAD

HEAD メソッドは、クエリメソッドリソースが使用可能かどうかを返します。