Filters 

You can perform the GET and DELETE methods on a subset of resource records. A subset of records can be received by applying filters to some of the resource fields.

Available filters are listed in the Documentation tab of the method’s expanded area, in the Filters section.

To filter, perform the GET request and put your filters parameters in the query string.

Ex 1. Filter in a Query String

Retrieve all users of organization ‘1’.

Request

GET /api/users?filter[organization]=1 HTTP/1.1

Similar to a field, a filter declares a data type and only takes specific values in the input.

Below are examples of requests and errors.

Ex 2. Wrong Input Type

A string value is passed as an input to a filter which can contain only integer values.

GET /api/users?filter[id]=aaa HTTP/1.1

{ "errors": [{
  "status": "400",
  "title": "unexpected value exception",
  "detail": "Expected integer value. Given \"aaa\".",
  "source": {
    "parameter": "filter[id]"
  }
}] }

Ex 3. Unknown Filter

Unknown, mistyped or unsupported filter.

GET /api/users?filter[unknown]=aaa HTTP/1.1

{ "errors": [{
  "status": "400",
  "title": "filter constraint",
  "detail": "Filter \"filter[unknown]\" is not supported.",
  "source": {
    "parameter": "filter[unknown]"
  }
}] }

The API enables you to use several types of filters. Filter types are briefly described in the table below.

Filter

Usage Example

Description

fields

fields[owner]=id,name

Used for limiting the response data only to specified fields. Depends on the include filter if the filter is applied to a relation.

filter

filter[id]=1 or filter[id]=5,7 or filter[id][gt]=8&filter[name]=a or filter[id][neq]=8 or filter[id]=5..7

Used for filtering the response data by specific values of a specific field.

A filter is specified using the syntax “key[operator_name]=value”. The full list of supported operators is described in the Data Filter (filter) section. The equality operator (eq) is optional and can be omitted, so the following filters are the same: filter[id]=1 and filter[id][eq]=1.

May accept several values separated by comma. In such case, they will be considered connected by the logical OR operator, e.g. filter[id]=5,7 represents the following expression: id = 5 OR id = 7.

May accept a data range. The syntax is “from_value..to_value”. The range is inclusive (i.e. it includes the interval boundaries, and the same range can be obtained by executing the following expression: field >= from_value AND field <= to_value). E.g. filter[id]=5..7 represents the following expression: id >= 5 AND id <= 7.

And in case of several filters in request, all of them will be perceived as connected using a logical AND operator. E.g. filter[id][gt]=8&filter[name]=a represents the following expression: id > 8 AND name = ‘a’.

include

include=[owner,organization]

Used for inclusion into response the related resources data.

page

page[size]=10&page[number]=1

Used for pagination purposes.

sort

sort=id or sort=id,-name

Used for data sorting. By default the ASC sorting applies.

To perform DESC sorting specify - before field name.

meta

meta=property1,property2

Used for requesting additional meta properties for API resources.

Fields Filter (fields) 

All objects are composed of fields. By default, all fields are returned in API response.

To request particular fields, use the fields filter and specify the fields you need in the response as its values.

Important

We recommend you always to use the fields filter and retrieve only the fields you will use in your application.

Example of Retrieving Only Required Fields

Select the username and the email fields of the users resource.

Request

GET api/users?fields[users]=username,email HTTP/1.1
Accept: application/vnd.api+json

Response

{
  "data": [
    {
      "type": "users",
      "id": "1",
      "attributes": {
        "username": "admin",
        "email": "admin@local.com"
      }
    },
    {
      "type": "users",
      "id": "2",
      "attributes": {
        "username": "sale",
        "email": "sale@example.com"
      }
    }
  ]
}

Data Filter (filter) 

Depending on the type of the filter, certain operators are allowed. For example, by default for integer filter type it is allowed to use eight operators: eq, neq, lt, lte, gt, gte, exists, neq_or_null, for string filter type - only four: eq, neq, exists, neq_or_null. The operators contains, not_contains, starts_with, not_starts_with, ends_with, not_ends_with, empty are not allowed by default and should be enabled by a developer who creates API resources.

Operator

Description

Request Example

eq

Equality for fields and to-one associations

Contains any of specified element for to-many associations

GET /api/users?filter[id]=1 HTTP/1.1
GET /api/users?filter[id][eq]=1 HTTP/1.1

neq

Inequality for fields and to-one associations

Not contains any of specified element for to-many associations

GET /api/users?filter[id][neq]=2 HTTP/1.1

lt

Less than

GET /api/users?filter[id][lt]=3 HTTP/1.1

lte

Less than or equal

GET /api/users?filter[id][lte]=4 HTTP/1.1

gt

Greater than

GET /api/users?filter[id][gt]=5 HTTP/1.1

gte

Greater than or equal

GET /api/users?filter[id][gte]=6 HTTP/1.1

exists

Is not null for fields and to-one associations and is not empty for to-many associations if filter value is true, 1 or yes

Is null for fields and to-one associations and is empty for to-many associations if filter value is false, 0 or no

GET /api/users?filter[id][exists]=yes HTTP/1.1
GET /api/users?filter[id][exists]=no HTTP/1.1

neq_or_null

Inequal or is null for fields and to-one associations

Inequal or empty for to-many associations

GET /api/users?filter[id][neq_or_null]=test HTTP/1.1

contains

Contains a text for string fields

Contains all specified elements for to-many associations

GET /api/users?filter[id][contains]=test HTTP/1.1

not_contains

Not contains a text for string fields

Not contains all specified elements for to-many associations

GET /api/users?filter[id][not_contains]=test HTTP/1.1

starts_with

Starts with a text

GET /api/users?filter[id][starts_with]=test HTTP/1.1

not_starts_with

Not starts with a text

GET /api/users?filter[id][not_starts_with]=test HTTP/1.1

ends_with

Ends with a text

GET /api/users?filter[id][ends_with]=test HTTP/1.1

not_ends_with

Not ends with a text

GET /api/users?filter[id][not_ends_with]=test HTTP/1.1

empty

Empty or is null, e.g. an empty string or null, an empty array or null

GET /api/users?filter[id][empty]=yes HTTP/1.1
GET /api/users?filter[id][empty]=no HTTP/1.1

Example of Using Operators to Filter Data

Request

GET /api/users?filter[id][gt]=5$page[number]=1&page[size]=2&fields[users]=username,email HTTP/1.1
Accept: application/vnd.api+json

Response

{
  "data": [
    {
      "type": "users",
      "id": "6",
      "attributes": {
        "username": "jimmy.henderson_c4261",
        "email": "jimmy.henderson_c428e@example.com"
      }
    },
    {
      "type": "users",
      "id": "7",
      "attributes": {
        "username": "gene.cardenas_c760d",
        "email": "gene.cardenas_c7620@yahoo.com"
      }
    }
  ]
}

Inclusion Filter (include) 

As mentioned above, the include filter allows you to extend the response data with the related resources information. It is usually used to reduce the number of requests to the server or, in other words, to retrieve all the necessary data in a single request.

All included resources will be represented in included section at the end of the response body.

An included section at the end of the response body

Important

Please note, in case of using fields filter for the main resource (e.g. users), it must contain the field(s) used in the include filter.

Example of Including Related Resources Information

Include the roles relation with the fields filter.

Request

GET api/users?fields[users]=username,email,roles&include=roles&page[number]=1&page[size]=1 HTTP/1.1
Accept: application/vnd.api+json

Response

{
  "data": [
    {
      "type": "users",
      "id": "1",
      "attributes": {
        "username": "admin",
        "email": "admin@local.com"
      },
      "relationships": {
        "userRoles": {
          "data": [
            {
              "type": "userroles",
              "id": "3"
            }
          ]
        }
      }
    }
  ],
  "included": [
    {
      "type": "userroles",
      "id": "3",
      "attributes": {
        "extend_description": null,
        "role": "ROLE_ADMINISTRATOR",
        "label": "Administrator"
      },
      "relationships": {
        "organization": {
          "data": null
        }
      }
    }
  ]
}

Also, it is possible to limit fields that will be retrieved from the relation. For such purposes, the fields filter should be used.

Example of Retrieving Only Required Fields of a Related Resource

Request

GET api/users?fields[userroles]=label&fields[users]=username,email,roles&include=roles&page[number]=1&page[size]=1 HTTP/1.1
Accept: application/vnd.api+json

Response

{
  "data": [
    {
      "type": "users",
      "id": "1",
      "attributes": {
        "username": "admin",
        "email": "admin@local.com"
      },
      "relationships": {
        "userRoles": {
          "data": [
            {
              "type": "userroles",
              "id": "3"
            }
          ]
        }
      }
    }
  ],
  "included": [
    {
      "type": "userroles",
      "id": "3",
      "attributes": {
        "label": "Administrator"
      }
    }
  ]
}

Pagination Filter (page) 

By default, the page size is limited to 10 records and the page number is 1. However, it is possible to ask the server to change the page size or page number to get the records that will fit your needs. Pagination parameters should be passed as the parameters of the query string.

Parameter name

Type

Default value

Description

page[size]

integer

10

Set a positive integer number. To disable the pagination, set it as -1. In this case page[number] will not be taken into account and can be omitted.

page[number]

integer

1

The number of the page.

Example of Retrieving a Particular Page of a Paged Response

Get the 2nd page of the retrieved records for the users resource with 20 records per page.

Request

GET /api/users?page[number]=2&page[size]=20 HTTP/1.1
Accept: application/vnd.api+json

Sorting Filter (sort) 

When the response to your call is a list of objects, you can also sort this list by using the sort filter with any of the available values listed in the API reference.

Example of Sorting by a Field Value

Sort by username in descending order.

Request

GET /api/users?filter[id][gt]=5$page[number]=1&page[size]=2&fields[users]=username,email&sort=-username HTTP/1.1
Accept: application/vnd.api+json

Response

{
  "data": [
    {
      "type": "users",
      "id": "24",
      "attributes": {
        "username": "william.morrison_247fe",
        "email": "william.morrison_2482c@msn.com"
      }
    },
    {
      "type": "users",
      "id": "31",
      "attributes": {
        "username": "victor.nixon_54050",
        "email": "victor.nixon_5406f@gmail.com"
      }
    }
  ]
}

Meta Property Filter (meta) 

The meta filter allows you to request additional meta properties for the resource. Meta properties will be generated for every item and will be returned in the item’s meta object in the response data.

The following table contains a list of supported meta properties that may be requested using ?meta=meta_property_name filter:

Name

Description

title

A text representation of the resource.

Example of Retrieving Text Representation of the Resource

Request

GET api/users?meta=title HTTP/1.1
Accept: application/vnd.api+json

Response

{
  "data": [
    {
      "type": "users",
      "id": "1",
      "meta": {
        "title": "John Doe",
      },
      "attributes": {
        "username": "john.doe",
      }
    },
    {
      "type": "users",
      "id": "2",
      "meta": {
        "title": "Ellen Rowell",
      },
      "attributes": {
        "username": "ellen.rowell"
      }
    }
  ]
}