Cursor-based pagination replaces offset-based pagination for all listing endpoints

Changes

Cursor-based pagination was added to all list resource endpoints. It replaces previous offset-based pagination and provides lower latency when listing resources. This change affects all listing resource endpoints:

Offset-based pagination is still available, but won't be accessible anymore after 01-08-2022.

Migration guide

The main difference between offset-based and cursor-based pagination is the parameter used to list resources. Listing resources 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 resources, you now need to use limit.

Example

Let's make an example of cursor-based pagination usage on list events endpoint. 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'

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'

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.