Query Parameters

Orion allows consumers of your API to use query parameters for interaction with soft deletable resources, including other related resources (defined as relations on a particular model) together in the response, aggregating relations and/or fields, and specifying how many resources to return in the response (pagination limit).

Soft Deletes

Returning Trashed Resources

The with_trashed query parameter allows you to return all resources, even the deleted ones.

The only_trashed query parameter instructs the API to return only soft deleted resources.

These parameters are accepted on index, search, and show endpoints of both standard and relation resources.

(GET) https://myapp.com/api/posts?with_trashed=true

Force Deleting

Last but not least, the force query parameter allows you to permanently delete a resource. The parameter is accepted on the destroy endpoint of both standard and relation resources.

(DELETE) https://myapp.com/api/posts/5?force=true

Pagination Limit

By default, 15 entities are returned per page from the index or search endpoints. To customize that, use the limit method:

<?php

namespace App\Http\Controllers\Api;

use Orion\Http\Controllers\Controller;

class PostsController extends Controller
{
    ...

    /**
    * Default pagination limit.
    *
    * @return int
    */
    public function limit() : int
    {
        return 20;
    }

    ...
}

To instruct the API to return a specific number of entities per page, the URL needs to contain the limit query parameter.

(GET) https://myapp.com/api/posts?limit=30

Max Pagination Limit

By default, there is no limit on how many entities could be requested from the API. To customize that, use the maxLimit method:

<?php

namespace App\Http\Controllers\Api;

use Orion\Http\Controllers\Controller;

class PostsController extends Controller
{
    ...

    /**
    * Max pagination limit.
    *
    * @return int
    */
    public function maxLimit() : int
    {
        return 100;
    }

    ...
}

Aggregating

First, relations and fields used for aggregation need to be whitelisted.

To instruct the API to return aggregates, the URL needs to contain a specific query parameter with a comma-separated list of relations or fields.

(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

Including Relations

First, relations need to be whitelisted.

To instruct the API to return relations, the URL needs to contain the include query parameter with a comma-separated list of relations.

(GET) https://myapp.com/api/posts?include=user,meta