Search - Laravel Rest Api

Usage

Here is a quick look at what you can do:

// (POST) api/posts/search
{
  "search": {
    "text": {
      "value": "my full text search"
    },
    "scopes": [
      {"name": "withTrashed", "parameters": [true]}
    ],
    "filters": [
      {
        "field": "id", "operator": ">", "value": 1, "type": "or"
      },
      {
        "nested": [
          {"field": "user.id", "operator": "<", "value": 2},
          {"field": "id", "operator": ">", "value": 100, "type": "or"}
        ]
      }
    ],
    "sorts": [
      {"field": "user_id", "direction": "desc"},
      {"field": "id", "direction": "asc"}
    ],
    "selects": [
      {"field": "id"}
    ],
    "includes": [
      {
        "relation": "posts",
        "filters": [
          {"field": "id", "operator": "in", "value": [1, 3]}
          ],
        "limit": 2
      },
      {
        "relation": "user",
        "filters": [
          {
            "field": "languages.pivot.boolean",
            "operator": "=",
            "value": true
          }
        ]
      }
    ],
    "aggregates": [
      {
        "relation": "stars",
        "type": "max",
        "field": "rate",
        "filters": [
          {"field": "approved", "value": true}
        ]
      }
    ],
    "instructions": [
      {
        "name": "odd-even-id",
        "fields": [
          { "name": "type", "value": "odd" }
        ]
      }
    ],
    "gates": ["create", "view"],
    "page": 2,
    "limit": 10
  }
}

Specifications

Key	Type	Required	Default	Description
Text
`text.value`	`string`	X		The text you want to search
Scopes
`scopes.name`	`string`	X		The name of the scope
`scopes.parameters`	`array`			The parameters associated with the scope
Filters
`filters.field`	`string`	when not nested		The name of the field
`filters.operator`	`string`		`=`	The field operator
`filters.value`	`mixed`	when not nested		The value you want to filter with
`filters.type`	`string`		`and`	The filter condition type
`filters.nested`	`array`			The nested parameters
Sorts
`sorts.field`	`string`	X		The name of the field
`sorts.direction`	`string`		`asc`	The direction in which results should be sorted
Selects
`selects.field`	`string`	X		The name of the field
Includes
`includes.relation`	`string`	X		The relation you are querying
`includes.other`	`mixed`		`50`	You can specify all the arguments in the current page such as `filters`, `limit`, `scopes`, etc except include
Aggregates
`aggregates.relation`	`string`	X		The relation you are querying
`aggregates.type`	`string`	X		The type of the aggregates you want to use in: `min`, `max`, `avg`, `sum`, `count` and `exists`
`aggregates.field`	`string`	when type is not `exists` or `count`	`*`	The field you want to execute your aggregate on
`aggregates.filters`	`array`			You can specify all the arguments for the `filters` section
Instructions
`instructions.name`	`string`	X		The instruction `uriKey`
`instructions.fields`	`array`			The fields provided with the instruction. Use instruction listing to see which ones can be provided.
Pagination
`page`	`number`		1	The actual page
`limit`	`number`		50	The maximum number of results
Gates
`gates`	`array`			The gates you want to get in: `create`, `view`, `update`, `delete`, `restore` and `forceDelete`

Response

As a response you'll receive the filtered records and related metadata:

{
  "current_page": 1,
  "data": [
    {
      "id": 1,
      "name": "Lou West",
      "gates": {
        "authorized_to_view": true,
        "authorized_to_update": true,
        "authorized_to_delete": true,
        "authorized_to_restore": true,
        "authorized_to_force_delete": true
      }
    },
    {
      "id": 2,
      "name": "Bridget Wilderman",
      "gates": {
        "authorized_to_view": true,
        "authorized_to_update": true,
        "authorized_to_delete": true,
        "authorized_to_restore": true,
        "authorized_to_force_delete": true
      }
    }
  ],
  "from": 1,
  "last_page": 1,
  "per_page": 50,
  "to": 2,
  "total": 2,
  "meta": {
    "gates": {
      "authorized_to_create": true
    }
  }
}

Scopes

Scopes corresponds to Laravel's scopes. You'll need to specify them in your resource first to allow their usage.

Use it as the following:

// (POST) api/posts/search
{
  "search": {
    "scopes": [
      {"name": "withTrashed", "parameters": [true]}
    ]
  }
}

Filters in Laravel Rest Api are the means by which you specify the data you want to retrieve, based on specified fields. All fields specified here must be defined in the fields method of your resource first.

Use it as the following:

// (POST) api/posts/search
{
  "search": {
    "filters": [
      {
        "field": "id", "operator": ">", "value": 1
      }
    ]
  }
}

Field is the column you want to interact with.

Operator must be one of these:

=
!=
>
>=
<
<=
like
not like
in
not in

Distant Field

You may specify fields related to relationships by specifying the relationship(s):

// (POST) api/posts/search
{
  "search": {
    "filters": [
      {
        "field": "languages.label",
        "operator": "=",
        "value": "fr"
      }
    ]
  }
}

Type

In many cases you want to condition your multiple filters using an "OR" operation instead of an "AND" one.

You can achieve this by specifying the type of the filter:

// (POST) api/posts/search
{
  "search": {
    "filters": [
      {"field": "user.id", "operator": "<", "value": 2},
      {"field": "id", "operator": ">", "value": 100, "type": "or"}
    ]
  }
}

Here the query will look if the user related id is less than 2 or if the id of the post is greater than 100.

Pivot Filtering

When you deal with a relation that has a pivot such as the BelongsToMany relation, you might want to filter in the pivot table.

You can achieve this by doing:

// (POST) api/posts/search
{
  "search": {
    "filters": [
      {
        "field": "languages.pivot.boolean",
        "operator": "=",
        "value": true
      }
    ]
  }
}

Nested Filtering

You may want to prioritize your condition depending on the filter type because an "AND" operation takes advantage of an "OR" operation.

You can achieve this by doing:

// (POST) api/posts/search
{
  "search": {
    "filters": [
      {
        "field": "id", "operator": "=", "value": 159, "type": "or"
      },
      {
        "field": "name", "operator": "like", "value": "%super post%", "type": "or"
      },
      {
        "nested": [
          {"field": "user.id", "operator": "<", "value": 2},
          {"field": "id", "operator": ">", "value": 100, "type": "or"}
        ]
      }
    ]
  }
}

Here, Laravel Rest Api will look if the id of the posts is 159 OR the name like "%super post%" OR (the user id is less than 2 and the id of the post is greater than 100)

Sorts

Sorts allows you to specify in which order you want to sort your results.

All fields specified here must be defined in the fields method of your resource first.

// (POST) api/posts/search
{
  "search": {
    "sorts": [
      {"field": "user_id", "direction": "desc"},
      {"field": "id", "direction": "asc"}
    ]
  }
}

Default sort

By default, Laravel Rest Api provides a default sort based on id descending. If you want to change this, please see the configuration

Selects

In some cases, you may want to specify the columns you want to select because it makes your API faster to not query unnecessary data. By default, Laravel Rest Api will query all your fields. You cannot query columns that are not present in the fields method.

You can achieve this by doing:

// (POST) api/posts/search
{
  "search": {
    "selects": [
      {"field": "id"},
      {"field": "title"}
    ]
  }
}

Includes

In order to limit the number of queries made to the API, Laravel Rest Api allows you to query distant relationships through a single endpoint.

You can achieve this by doing:

// (POST) api/posts/search
{
  "search": {
    "includes": [
      {
        "relation": "posts"
      }
    ]
  }
}

More powerful include

In order to make the include operation much more powerful, Laravel Rest Api allows to specify each argument on this page except include to avoid caveats.

This allows you to do the following:

// (POST) api/posts/search
{
  "search": {
    "includes": [
      {
        "relation": "posts",
        "filters": [
          {"field": "id", "operator": "in", "value": [1, 3]}
        ],
        "limit": 2
      }
    ]
  }
}

Aggregates

If you don't know what an aggregate is, please have a look at the Laravel documentation first.

Laravel Rest Api supports all Laravel's aggregates, here is a quick look at how to specify your aggregate:

// (POST) api/posts/search
{
  "search": {
    "aggregates": [
      {
        "relation": "comments",
        "type": "avg",
        "field": "stars"
      }
    ]
  }
}

Here we are getting the average stars for the comments linked to the posts.

The type could be one of these:

min
max
avg
sum
count
exists

For the exists and count operation you must not specify the field since these aggregates don't base themselves on a column.

Aggregates filtering

For more complex aggregates, Laravel Rest Api allows you to specify filters. These filters are the same as the basic ones.

// (POST) api/posts/search
{
  "search": {
    "aggregates": [
      {
        "relation": "comments",
        "type": "avg",
        "field": "stars",
        "filters": [
          {"field": "approved", "value": true}
        ]
      }
    ]
  }
}

Instructions

Instructions is a way for api builder to define strong query operations. They'll be defined in the resource details when exposed.

Here is how to specify an instruction:

// (POST) api/posts/search
{
  "search": {
    "instructions": [
      {
        "name": "odd-even-id"
      }
    ]
  }
}

Here we are getting the posts that have an even id.

The specified name is the uriKey of the instruction.

Instructions fields

For more complex instructions, Laravel Rest Api allows you to specify fields. You can have full access to the fields and validation in the resource details.

// (POST) api/posts/search
{
  "search": {
    "instructions": [
      {
        "name": "odd-even-id",
        "fields": [
          {"field": "type", "value": "odd"}
        ]
      }
    ]
  }
}

Pagination

You might either want to limit the data you are querying or to specify a page to load data by sequence. All limits specified here must be defined in the limits method of your resource first.

You can achieve this by doing:

// (POST) api/posts/search
{
  "search": {
    "page": 2,
    "limit": 10
  }
}

Gates

If you want to retrieve permissions on the models you are getting, you need to specify the gates you want to get. Use this with care this can slow down you application queries.

Be aware before that Gates needs to be enabled in order to be retrieved. Have a look at Automatic Gates if you need detail.

The gates could be one of these:

create
view
update
delete
restore
forceDelete

// (POST) api/posts/search
{
  "search": {
    "gates": ["create", "view"]
  }
}

Text

If you want to specify a full text search you'll need to use the text argument. First be sure you activated full text search for the resource.

// (POST) api/posts/search
{
  "search": {
    "text": {
      "value": "my text search"
    }
  }
}

Impacts

When using full text search, some restrictions happens to the query:

Key	Changes
Scopes
`scopes.name`	Not allowed
`scopes.parameters`	Not allowed
Filters
`filters.field`	take scout fields instead of fields in resource detail
`filters.operator`	`=`/`in`/`not in`
`filters.type`	Not allowed
`filters.nested`	Not allowed
Sorts
`sorts.field`	take scout fields instead of fields in resource detail

Details

Details is a way to get all information needed to perform actions on a resource. It will give you the current state of the resource depending on the user.

Mutate

Laravel Rest Api exposes the mutate endpoint which is dedicated to modify/create data for your frontend users.