Records Filtration API¶

filter and exclude are two query parameters you can manage what records you want to get with.

Lookups¶

Here is the list of lookups you can use

Operator	Description
contains	Case-sensitive containment test
icontains	Case-insensitive containment test
exact	Exact match
iexact	Case-insensitive exact match
in	In a given array
gt	Greater than
gte	Greater than or equal to
lt	Less than
lte	Less than or equal to
startswith	Case-sensitive starts-with
istartswith	Case-insensitive starts-with
endswith	Case-sensitive ends-with
iendswith	Case-insensitive ends-with

Examples¶

For example, let's get products with price greater than 10 and title that contains "t-shirt" in title.

HTTP

GET https://api.apisful.com/v1/collections/products/?filter={"price": {"gt": 10}, "title": {"icontains": "t-shirt"}}
X-Api-Key: {your_key_here}

cURL

curl -X GET \
  -H "X-Api-Key: {your_key_here}" \
  https://api.apisful.com/v1/collections/products/?filter={"price": {"gt": 10}, "title": {"icontains": "t-shirt"}}

JavaScript

// [!] we use https://github.com/axios/axios lib in this example

// create an axios instance with default config for all other requests
const API = axios.create({
  baseURL: 'https://api.apisful.com/v1/',
  headers: {
    'X-Api-Key': '{your_key_here}'
  }
});

// make a record retrieving request
API.get('collections/products/', params: {
    filter: JSON.stringify({
        price: { gt: 10 },
        title: { icontains: "t-shirt" }
    })
})
  .then(function (response) {
    console.log(response);
  })
  .catch(function (error) {
    console.log(error);
  });

You'll get

{
    "count": 30,
    "next": "https://api.apisful.com/v1/collections/products/?page=2&...",
    "previous": null,
    "results": [
        {
          "id": 54844,
          "title": "Base T-shirt (blue color)",
          "price": 17.99,
          "sizes": "S, M, L, XL",
          "created_at": "2020-07-10T11:15:31.867705Z",
          "updated_at": "2020-07-10T11:15:31.867705Z"
        },
        ...
        {
          "id": 54864,
          "title": "T-shirt with a print",
          "price": 12.99,
          "sizes": "S, M, L, XL",
          "created_at": "2020-06-10T11:15:31.867705Z",
          "updated_at": "2020-06-10T11:15:31.867705Z"
        }
    ]    
}

If you don't want to get blue t-shirts, exclude results with this word in title field:

HTTP

GET https://api.apisful.com/v1/collections/products/?filter={"price": {"gt": 10}, "title": {"icontains": "t-shirt"}}&exclude={"title": {"icontains": "blue"}}
X-Api-Key: {your_key_here}

cURL

curl -X GET \
  -H "X-Api-Key: {your_key_here}" \
  https://api.apisful.com/v1/collections/products/?filter={"price": {"gt": 10}, "title": {"icontains": "t-shirt"}}&exclude={"title": {"icontains": "blue"}}

JavaScript

// [!] we use https://github.com/axios/axios lib in this example

// create an axios instance with default config for all other requests
const API = axios.create({
  baseURL: 'https://api.apisful.com/v1/',
  headers: {
    'X-Api-Key': '{your_key_here}'
  }
});

// make a record retrieving request
API.get('collections/products/', params: {
    filter: JSON.stringify({
        price: { gt: 10 },
        title: { icontains: "t-shirt" }
    }),
    exclude: JSON.stringify({
        title: { icontains: "blue" }
    }),
})
  .then(function (response) {
    console.log(response);
  })
  .catch(function (error) {
    console.log(error);
  });

Here we go

{
    "count": 29,
    "next": "https://api.apisful.com/v1/collections/products/?page=2&...",
    "previous": null,
    "results": [
        ...
        {
          "id": 54864,
          "title": "T-shirt with a print",
          "price": 12.99,
          "sizes": "S, M, L, XL",
          "created_at": "2020-06-10T11:15:31.867705Z",
          "updated_at": "2020-06-10T11:15:31.867705Z"
        }
    ]    
}

Using exact lookup¶

If you need to filter or exclude records by exact lookup, you can just pass a string instead of an object. For example, you can use

filter={"title": "T-shirt with a print"}

instead of

filter={"title": {"exact": "T-shirt with a print"}}