クエリパラメータ
Orionでは、APIの利用者がクエリパラメータを使用して、ソフトデリート可能なリソースの操作、関連する他のリソース(特定のモデルにリレーションとして定義されたもの)をレスポンスに含めること、リレーションやフィールドの集計、そしてレスポンスで返すリソース数の指定(ペジネーション件数(limit))を行えます。
ソフトデリート
ソフトデリート済みリソースの取得
with_trashedクエリパラメータを使用すると、削除済みのものを含むすべてのリソースを返せます。
only_trashedクエリパラメータは、ソフトデリート済みリソースのみを返すようAPIに指示します。
これらのパラメータは、標準リソースとリレーションリソースの両方のindex、search、showエンドポイントで受け付けられます。
(GET) https://myapp.com/api/posts?with_trashed=true
完全削除(force delete)
最後に、forceクエリパラメータを使用すると、リソースを完全に削除できます。このパラメータは、標準リソースとリレーションリソースの両方のdestroyエンドポイントで受け付けられます。
(DELETE) https://myapp.com/api/posts/5?force=true
ペジネーション件数(limit)
デフォルトでは、indexまたはsearchエンドポイントから1ページあたり15件のエンティティが返されます。これをカスタマイズするには、limitメソッドを使用します。
<?php
namespace App\Http\Controllers\Api;
use Orion\Http\Controllers\Controller;
class PostsController extends Controller
{
...
/**
* デフォルトのページネーション上限。
*
* @return int
*/
public function limit() : int
{
return 20;
}
...
}
1ページあたり特定の件数のエンティティを返すようAPIに指示するには、URLにlimitクエリパラメータを含める必要があります。
(GET) https://myapp.com/api/posts?limit=30
limitクエリパラメータで指定した値は、コントローラーのlimitメソッドで指定した値を常に上書きしますが、maxLimitメソッドで指定した値を超えることはできません。ペジネーション件数(limit)の上限
デフォルトでは、APIにリクエストできるエンティティの件数に上限はありません。これをカスタマイズするには、maxLimitメソッドを使用します。
<?php
namespace App\Http\Controllers\Api;
use Orion\Http\Controllers\Controller;
class PostsController extends Controller
{
...
/**
* ページネーションの最大上限。
*
* @return int
*/
public function maxLimit() : int
{
return 100;
}
...
}
集計
まず、集計に使用するリレーションとフィールドをホワイトリストに登録する必要があります。
集計結果を返すようAPIに指示するには、URLに特定のクエリパラメータを含め、その値としてリレーションまたはフィールドをカンマ区切りで指定する必要があります。
(GET) https://myapp.com/api/posts?with_count=user,meta
(GET) https://myapp.com/api/posts?with_exists=user,meta
(GET) https://myapp.com/api/users?with_avg=posts.stars
(GET) https://myapp.com/api/users?with_sum=posts.stars
(GET) https://myapp.com/api/users?with_min=posts.stars
(GET) https://myapp.com/api/users?with_max=posts.stars
リレーションのインクルード
まず、リレーションをホワイトリストに登録する必要があります。
リレーションを返すようAPIに指示するには、URLにincludeクエリパラメータを含め、その値としてリレーションをカンマ区切りで指定する必要があります。
(GET) https://myapp.com/api/posts?include=user,meta