Filter, sort and search content

Before we begin

This tutorial assumes you have followed the quick start guide and are familiar with XPKit resources and how to call API endpoints with an Authorization header. We continue to use the EMEA region in the examples below.

Resources and fields

You are free to create any field you require in your resources. However please note that XPKit uses the x__ and _xpkit_ prefixes throughout the platform. You will see examples of these below so to avoid clashes it is recommended you do not name your fields similarly.

Referencing fields

Let's look at the activity resource we created in the previous tutorial:

{
    "experience_id": "game-developers-conference-2024",
    "owner_id": "c48ea5a2-1f6e-4772-a23f-c4bc09732b47",
    "activity_type": "registration",
    "payload": {
        "object_id": "registration-website",
        "number_of_tickets": 5
    }
}

It is possible to search, filter and sort on any field in this resource. You should reference fields within objects using dot notation. For example if we are interested in activities based on the number_of_tickets requested we would specify the field in API calls like so: payload.number_of_tickets.

Filtering

A full list of the filtering options are available. For now let's focus on retrieving all activities for the Game Developers Conference that require 3 or more tickets. For this we suffix our tickets field with __gte (greater than or equal to).

Therefore our lookup criteria would be provided like so:

• payload.number_of_tickets__gte=3
• experience_id=game-developers-conference-2024

Here is the request in full:

Python

import requests

endpoint = 'https://activities.emea.xpkit.net/api/activity/'

headers = {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json'}

params = {
    'experience_id': 'game-developers-conference-2024',
    'payload.number_of_tickets__gte': 3}

req = requests.get(url=endpoint, headers=headers, params=params)
result = req.json()

JavaScript

async function getData(url) {
    const response = await fetch(url, {
        method: 'GET',
        headers: {
            'Content-Type': 'application/json',
            'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
        }
    });
    return response.json();
}

getData('https://activities.emea.xpkit.net/api/activity/?experience_id=game-developers-conference-2024&payload.number_of_tickets__gte=3').then((data) => {
    const result = data;
});

cURL

curl --location 'https://activities.emea.xpkit.net/api/activity/?experience_id=game-developers-conference-2024&payload.number_of_tickets__gte=3' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json'

We will receive a results array of resources that match the criteria.

{
    "count": 1,
    "next": null,
    "next_token": null,
    "previous": null,
    "previous_token": null,
    "results": [
        {
            "resource": {
                "activity_type": "registration",
                "created": "2023-07-04T04:56:32Z",
                "experience_id": "game-developers-conference-2024",
                "last_modified": "2023-07-04T04:56:32Z",
                "owner_id": "d159b839-9a96-4a51-8f25-2c8314137bb4",
                "payload": {
                    "number_of_tickets": 5,
                    "object_id": "registration-website"
                }
            },
            "resource_id": "568760a6-fd18-47b6-b1e3-ae4c028f77df",
            "resource_url": "/api/activity/568760a6-fd18-47b6-b1e3-ae4c028f77df/"
        }
    ]
}

Sorting

If we need to order the activities by the number of tickets requested in descending order (the largest first) we can provide an order by param called x__order_by.

We would amend our request above to include the following additional parameter:

• x__order_by=payload.number_of_tickets__desc

The suffix of the field can be either __asc (ascending, the default) or __desc (descending).

The full endpoint would be:

https://activities.emea.xpkit.net/api/activity/
?experience_id=game-developers-conference-2024
&payload.number_of_tickets__gte=3
&x__order_by=payload.number_of_tickets__desc

Searching

Full details on all the full text search options are available. For now we'll look at retrieving all activities that contain the string "registration", but not the string "game-developers-conference-2023". This should ensure we don't retrieve any data from last year's event.

We achieve this by using the x__query parameter. Our query will be:

• x__query=registration -game-developers-conference-2023.

Here is the endpoint we would call:

https://activities.emea.xpkit.net/api/activity/
?x__query=registration%20-game-developers-conference-2023