REST API: Filtering, Locale, and Publication State

The REST API offers the ability to filter results found with its "Get entries" method. Using optional Strapi features can provide some more filters:

• If the Internationalization (i18n) plugin is enabled on a content-type, it's possible to filter by locale.
• If the Draft & Publish is enabled, it's possible to filter based on a live or preview state.

:::

Filtering

Queries can accept a filters parameter with the following syntax:

GET /api/:pluralApiId?filters[field][operator]=value

The following operators are available:

Operator	Description
$eq	Equal
$eqi	Equal (case-insensitive)
$ne	Not equal
$nei	Not equal (case-insensitive)
$lt	Less than
$lte	Less than or equal to
$gt	Greater than
$gte	Greater than or equal to
$in	Included in an array
$notIn	Not included in an array
$contains	Contains
$notContains	Does not contain
$containsi	Contains (case-insensitive)
$notContainsi	Does not contain (case-insensitive)
$null	Is null
$notNull	Is not null
$between	Is between
$startsWith	Starts with
$startsWithi	Starts with (case-insensitive)
$endsWith	Ends with
$endsWithi	Ends with (case-insensitive)
$or	Joins the filters in an "or" expression
$and	Joins the filters in an "and" expression
$not	Joins the filters in an "not" expression

caution

By default, the filters can only be used from find endpoints generated by the Content-type Builder and the CLI.

Example: Find users having 'John' as a first name

You can use the $eq filter operator to find an exact match.

[
  {
    "id": 1,
    "username": "John",
    "email": "john@test.com",
    "provider": "local",
    "confirmed": true,
    "blocked": false,
    "createdAt": "2021-12-03T20:08:17.740Z",
    "updatedAt": "2021-12-03T20:08:17.740Z"
  }
]

const qs = require('qs');
const query = qs.stringify({
  filters: {
    username: {
      $eq: 'John',
    },
  },
}, {
  encodeValuesOnly: true, // prettify URL
});

await request(`/api/users?${query}`);

Example: Find multiple restaurants with ids 3, 6,8

You can use the $in filter operator with an array of values to find multiple exact values.

{
  "data": [
    {
      "id": 3,
      "attributes": {
        "name": "test3",
        // ...
      }
    },
    {
      "id": 6,
      "attributes": {
        "name": "test6",
        // ...
      }
    },
    {
      "id": 8,
      "attributes": {
        "name": "test8",
        // ...
      }
    }
  ],
  "meta": {
    // ...
  }
}

const qs = require('qs');
const query = qs.stringify({
  filters: {
    id: {
      $in: [3, 6, 8],
    },
  },
}, {
  encodeValuesOnly: true, // prettify URL
});

Complex filtering

Complex filtering is combining multiple filters using advanced methods such as combining $and & $or. This allows for more flexibility to request exactly the data needed.

{
  "data": [
    {
      "id": 1,
      "attributes": {
        "name": "test1",
        "date": "2020-01-01",
        // ...
      }
    },
    {
      "id": 2,
      "attributes": {
        "name": "test2",
        "date": "2020-01-02",
        // ...
      }
    }
  ],
  "meta": {
    // ...
  }
}

const qs = require('qs');
const query = qs.stringify({
  filters: {
    $or: [
      {
        date: {
          $eq: '2020-01-01',
        },
      },
      {
        date: {
          $eq: '2020-01-02',
        },
      },
    ],
    author: {
      name: {
        $eq: 'Kai doe',
      },
    },
  },
}, {
  encodeValuesOnly: true, // prettify URL
});

await request(`/api/books?${query}`);

Deep filtering

Deep filtering is filtering on a relation's fields.

caution

• Querying your API with deep filters may cause performance issues. If one of your deep filtering queries is too slow, we recommend building a custom route with an optimized version of the query.
• Deep filtering isn't available for polymorphic relations (eg: Dynamic Zones & Media Fields).

note

• Relations, media fields, components, and dynamic zones are not populated by default. Use the populate parameter to populate these data structures (see populate documentation)
• It is not possible to filter on dynamic zones or media fields.

{
  "data": [
    {
      "id": 1,
      "attributes": {
        "name": "GORDON RAMSAY STEAK",
        "stars": 5
        // ...
      }
    },
    {
      "id": 2,
      "attributes": {
        "name": "GORDON RAMSAY BURGER",
        "stars": 5
        // ...
      }
    }
  ],
  "meta": {
    // ...
  }
}

const qs = require('qs');
const query = qs.stringify({
  filters: {
    chef: {
      restaurants: {
        stars: {
          $eq: 5,
        },
      },
    },
  },
}, {
  encodeValuesOnly: true, // prettify URL
});

Locale

• The Internationalization (i18n) plugin should be installed.
• Localization should be enabled for the content-type.

The locale API parameter can be used to get entries from a specific locale (see i18n plugin documentation).

Publication State

The Draft & Publish feature should be enabled.

Queries can accept a publicationState parameter to fetch entries based on their publication state:

• live: returns only published entries (default)
• preview: returns both draft entries & published entries

{
  "data": [
    {
      "id": 1,
      "attributes": {
        "title": "This a Draft",
        "publishedAt": null
        // ...
      }
    },
    {
      "id": 2,
      "attributes": {
        "title": "This is Live",
        "publishedAt": "2021-12-03T20:08:17.740Z"
        // ...
      }
    }
  ],
  "meta": {
    // ...
  }
}

const qs = require('qs');
const query = qs.stringify({
  publicationState: 'preview',
}, {
  encodeValuesOnly: true, // prettify URL
});

await request(`/api/articles?${query}`);

To retrieve only draft entries, combine the preview publication state and the publishedAt fields:

GET /api/articles?publicationState=preview&filters[publishedAt][$null]=true

const qs = require('qs');
const query = qs.stringify({
  publicationState: 'preview',
  filters: {
    publishedAt: {
      $null: true,
    },
  },
}, {
  encodeValuesOnly: true, // prettify URL
});

await request(`/api/articles?${query}`);