Added cursor-based pagination to the "List events" endpoint

Changes

Added cursor-based pagination to the List events endpoint. Offset-based pagination is still supported but we highly encourage you to use the new pagination system to benefit from a huge performance boost.

📘
Offset-based pagination deprecation
We are currently in the process of adding cursor-based pagination to all the endpoints that list resources to improve the performance of our API. As soon as we released this improvement for all these endpoints, we will deprecate the offset-based pagination API-wide.

Migration guide

The main difference between offset-based and cursor-based pagination is the parameter used to list resources. Listing events with offset-based pagination is done with the page parameter. Listing resources with cursor-based pagination is done with a cursor parameter. The cursor is an opaque short-lived value that represents where you are in the list of resources. You don't want to store cursors for a long period of time as they could expire.

If you used to use per_page to get a specific number of events, you now need to use limit.

To fetch your most recent events, you don't have to specify the cursor:

curl --request GET \
     --url 'https://gorgias.gorgias.com/api/events?limit=2' \
     --header 'Accept: application/json'

const fetch = require('node-fetch');

const url = 'https://gorgias.gorgias.com/api/events?limit=2';
const options = {method: 'GET', headers: {Accept: 'application/json'}};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error('error:' + err));

import requests

response = requests.request("GET", 
                            "https://gorgias.gorgias.com/api/events?limit=2", 
                            headers={"Accept": "application/json"})

print(response.text)

The server will return the list of events as well as pagination information containing:

a prev_cursor value if there are events before the ones you fetched. It will be null if you fetched the events at the beginning of the list (similar to the first page).
a next_cursor value if there are events after the ones you fetched. It will be null if you fetched the events at the end of the list (similar to the last page).

{
    "data": [
        {
            "id": 768,
            "context": "be71cef8-ab02-4d89-b33c-1a00c387310d",
            "created_datetime": "2021-11-02T21:58:43.171610+00:00",
            "data": null,
            "object_id": 2,
            "object_type": "User",
            "type": "user-logged-out",
            "user_id": 2,
            "uri": "/api/events/768/"
        },
        {
            "id": 767,
            "context": "a0619320-611d-487b-9f28-5c297fd0793a",
            "created_datetime": "2021-11-02T21:58:32.951424+00:00",
            "data": null,
            "object_id": 1,
            "object_type": "Account",
            "type": "account-updated",
            "user_id": null,
            "uri": "/api/events/767/"
        }
    ],
    "object": "list",
    "uri": "/api/events",
    "meta": {
        "prev_cursor": null,
        "next_cursor": "bmV4dF9fNzY3X18yMDIxLT=="
    }
}

To continue to list your events, get older events (default order is most recent events first), you now need to set the cursor parameter to the next_cursor value returned in the response (bmV4dF9fNzY3X18yMDIxLT==)

curl --request GET \
     --url 'https://gorgias.gorgias.com/api/events?cursor=bmV4dF9fNzY3X18yMDIxLT==&limit=2' \
     --header 'Accept: application/json'

const fetch = require('node-fetch');

const url = 'https://gorgias.gorgias.com/api/events?cursor=bmV4dF9fNzY3X18yMDIxLT==&limit=2';
const options = {method: 'GET', headers: {Accept: 'application/json'}};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error('error:' + err));

import requests
url = "https://gorgias.gorgias.com/api/events?cursor=bmV4dF9fNzY3X18yMDIxLT==&limit=2"
response = requests.request("GET", url, headers={"Accept": "application/json"})

print(response.text)

The server will return:

{
    "data": [
        {
            "id": 766,
            "context": "60d87c4e-268b-44c3-b453-910d83ed7d2c",
            "created_datetime": "2021-11-01T22:41:55.377130+00:00",
            "data": null,
            "object_id": 2,
            "object_type": "User",
            "type": "user-updated",
            "user_id": 2,
            "uri": "/api/events/766/"
        },
        {
            "id": 765,
            "context": "a7a8534d-4fff-4ddd-aa58-38752ba41d1f",
            "created_datetime": "2021-11-01T10:52:37.921041+00:00",
            "data": null,
            "object_id": 2,
            "object_type": "User",
            "type": "user-logged-in",
            "user_id": 2,
            "uri": "/api/events/765/"
        }
    ],
    "object": "list",
    "uri": "/api/events?limit=2&cursor=bmV4dF9fNzY3X18yMDIxLT==",
    "meta": {
        "prev_cursor": "cHJldl9fNzY2X18yMDIxLTjEzMA==",
        "next_cursor": "bmV4dF9fNzY1X18jM3LjkyMTA0MQ=="
    }
}

As you can see, now that you are in the middle of the list, the server returned a value for:

the previous cursor (prev_cursor) to fetch events before the ones you just fetched (newer events)
the next cursor (next_cursor) to fetch events after the ones you just fetched (older events)

Feel free to reach out at [email protected] if you have any questions.

Changes

📘Offset-based pagination deprecation

Migration guide

📘
Offset-based pagination deprecation