List Ticket Pagination

Summary

The Alert to Ticket Module provides a mechanism for Vendors to pull a list of tickets logs for alerts that were sent to a given Partner. As time goes on, a Partner's list of tickets will grow at a large rate and the base functionality of the endpoint does not provide pagination.

To that end, we have implemented a backwards compatible way to paginate this ticket list endpoint.

Existing Functionality

The current oem-alerts-api endpoint is:

POST api/oem-alerts-api/alert/list/tickets

This endpoint requires your client credentials as well as the organization oem token to fetch a full list of ticket logs for alerts which have been sent through the user's account.

When hitting this endpoint, we return the entire list of ticket logs that we have in our system. This is not sustainable given the volume that is now expected.

Once a Partner's ticket log list reaches the many thousands, the server will likely not respond, and you may receive 504s or 502s.

To that end we have implemented cursor based pagination.

📘
You may still use the old system by simply not including the pagination object in the POST request.

Pagination System

Our pagination system is Cursor based. You provide an initial request with some filters, and will be given back a response with the data request as well as a cursors object with a next and prev cursor.

When making a page request:

The next cursor will be populated if there is a next page otherwise it will be null
The prev cursor will be populated if there is a previous page otherwise it will be null

When making the follow up request for the next page, you pass only the cursor key with the cursor value.

📘
This system does not allow you to jump between pages, but only allows you to navigate back and forth one page at a time.

Filters

We have a couple of filters available to you to help you get the data you need.

sort - asc or desc
pageSize - Defaults to 500 and has a max value of 1000
dateFrom - The date you want to begin from, inclusive (In the format of YYYY-MM-DD).
dateTo - The date you want to end at, inclusive (In the format of YYYY-MM-DD).

📘
All filters are are optional. However, if you want to paginate, you must provide at least one value (this is due to backwards compatibility).

Filter Defaults

Page Size defaults to 500
Sort defaults to desc
date defaults to all dates

How to Use Pagination

When working with the pagination system there are some things to keep in mind.

On the initial request, you can provide your filters. Those can be pageSize, sort, dateFrom, and or dateTo. However, the pagination object cannot be completely empty otherwise it will default to legacy behaviour and provide the entire list of tickets.

POST /api/oem-alerts-api/alert/list/tickets HTTP/1.1
Content-Type: application/json

{
	"clientId": "66abbbae5a078102ccf5790c6a84b4de4cac647110f3db597399cde2010d7d17",
	"clientSecret": "bad6425ac1fd5bd2157f839496580ad9371e9b5b0abd65c3b88fe34d471eeef37c3cf06bda3932782b0cbc003c1980be450c1a3214eae3a0c2781a95efc1859347b81bdc4b8914745fe669cfccf933dfaa46ed0795725412cbfdc7663eb13c28",
  "grantType": "client_credentials",
  "scope": "vendor_manage",
  "organizationOemToken": "bad6425ac1fd5bd2157f839496580ad9371e9b5b0abd65c3b88fe34d471eeef37c3cf06bda3932782b0cbc003c1980be450c1a3214easdas34d39347b81bdc4b8914745fe669cfccf933dfaa46ed0795725412cbfdc7663eb13c28",
  "integrationId": "690b98ea1a4906f08f785ad8",
  "pagination": {
  	"sort": "desc",
		"pageSize": "250"
	}
}

Once you get your response, you will be given a cursor object with next and prev cursors.

{
  "message": "success",
  "statusCode": 201,
  "data": [ ... data],
  "cursors": {
    "next": "eyJkaXJlY3Rpb24iOiJuZXh0IiwiaWQiOiI2YTFkZTc4M2UyNTAwOGUyYjI3ZjY3NzAiLCJjcmVhdGVkQXQiOiIyMDI2LTA2LTAxVDIwOjExOjQ3LjMwN1oiLCJwcmV2aW91c1N0YWNrIjpbeyJpZCI6IjZhMWRmNDZkMjYyYjExYTAzMzk4Yzk4NiIsImNyZWF0ZWRBdCI6IjIwMjYtMDYtMDFUMjE6MDY6NTQuMjE2WiJ9XSwiZmlsdGVycyI6eyJkYXRlRnJvbSI6bnVsbCwiZGF0ZVRvIjpudWxsfSwic29ydCI6ImRlc2MiLCJwYWdlU2l6ZSI6Mn0",
    "prev": null
  }
}

To fetch the next page in the list, you pass the pagination object with the cursors property and the next cursor value.

POST /api/oem-alerts-api/alert/list/tickets HTTP/1.1
Content-Type: application/json

{
	"clientId": "66abbbae5a078102ccf5790c6a84b4de4cac647110f3db597399cde2010d7d17",
	"clientSecret": "bad6425ac1fd5bd2157f839496580ad9371e9b5b0abd65c3b88fe34d471eeef37c3cf06bda3932782b0cbc003c1980be450c1a3214eae3a0c2781a95efc1859347b81bdc4b8914745fe669cfccf933dfaa46ed0795725412cbfdc7663eb13c28",
  "grantType": "client_credentials",
  "scope": "vendor_manage",
  "organizationOemToken": "bad6425ac1fd5bd2157f839496580ad9371e9b5b0abd65c3b88fe34d471eeef37c3cf06bda3932782b0cbc003c1980be450c1a3214easdas34d39347b81bdc4b8914745fe669cfccf933dfaa46ed0795725412cbfdc7663eb13c28",
  "integrationId": "690b98ea1a4906f08f785ad8",
  "pagination": {
		"cursor": "eyJkaXJlY3Rpb24iOiJuZXh0IiwiaWQiOiI2YTFkZTc4M2UyNTAwOGUyYjI3ZjY3NzAiLCJjcmVhdGVkQXQiOiIyMDI2LTA2LTAxVDIwOjExOjQ3LjMwN1oiLCJwcmV2aW91c1N0YWNrIjpbeyJpZCI6IjZhMWRmNDZkMjYyYjExYTAzMzk4Yzk4NiIsImNyZWF0ZWRBdCI6IjIwMjYtMDYtMDFUMjE6MDY6NTQuMjE2WiJ9XSwiZmlsdGVycyI6eyJkYXRlRnJvbSI6bnVsbCwiZGF0ZVRvIjpudWxsfSwic29ydCI6ImRlc2MiLCJwYWdlU2l6ZSI6Mn0"
	}
}

📘
When cursoring, you can omit the filters that you passed in the first request as the cursor is encoded with those values. That being said, you can leave the initial properties with the same values if you choose.

{
  "message": "success",
  "statusCode": 201,
  "data": [ ... data],
  "cursors": {
    "next": "eyJkaXJlY3Rpb24iOiJuZXh0IiwiaWQiOiI2YTFkZTc4M2UyNTAwOGUyYjI3ZjY3NzAiLCJjcmVhdGVkQXQiOiIyMDI2LTA2LTAxVDIwOjExOjQ3LjMwN1oiLCJwcmV2aW91c1N0YWNrIjpbeyJpZCI6IjZhMWRmNDZkMjYyYjExYTAzMzk4Yzk4NiIsImNyZWF0ZWRBdCI6IjIwMjYtMDYtMDFUMjE6MDY6NTQuMjE2WiJ9XSwiZmlsdGVycyI6eyJkYXRlRnJvbSI6bnVsbCwiZGF0ZVRvIjpudWxsfSwic29ydCI6ImRlc2MiLCJwYWdlU2l6ZSI6Mn0",
    "prev": "eyJkaXJlY3Rpb24iOiJwcmV2IiwiaWQiOiI2YTFkZjQ2ZDI2MmIxMWEwMzM5OGM5ODYiLCJjcmVhdGVkQXQiOiIyMDI2LTA2LTAxVDIxOjA2OjU0LjIxNloiLCJwcmV2aW91c1N0YWNrIjpbXSwiZmlsdGVycyI6eyJkYXRlRnJvbSI6bnVsbCwiZGF0ZVRvIjpudWxsfSwic29ydCI6ImRlc2MiLCJwYWdlU2l6ZSI6Mn0="
  }
}

Similarly, if you would like the previous page, you pass the pagination object with the prev cursor value.

POST /api/oem-alerts-api/alert/list/tickets HTTP/1.1
Content-Type: application/json

{
	"clientId": "66abbbae5a078102ccf5790c6a84b4de4cac647110f3db597399cde2010d7d17",
	"clientSecret": "bad6425ac1fd5bd2157f839496580ad9371e9b5b0abd65c3b88fe34d471eeef37c3cf06bda3932782b0cbc003c1980be450c1a3214eae3a0c2781a95efc1859347b81bdc4b8914745fe669cfccf933dfaa46ed0795725412cbfdc7663eb13c28",
  "grantType": "client_credentials",
  "scope": "vendor_manage",
  "organizationOemToken": "bad6425ac1fd5bd2157f839496580ad9371e9b5b0abd65c3b88fe34d471eeef37c3cf06bda3932782b0cbc003c1980be450c1a3214easdas34d39347b81bdc4b8914745fe669cfccf933dfaa46ed0795725412cbfdc7663eb13c28",
  "integrationId": "690b98ea1a4906f08f785ad8",
  "pagination": {
		"cursor": "eyJkaXJlY3Rpb24iOiJwcmV2IiwiaWQiOiI2YTFkZjQ2ZDI2MmIxMWEwMzM5OGM5ODYiLCJjcmVhdGVkQXQiOiIyMDI2LTA2LTAxVDIxOjA2OjU0LjIxNloiLCJwcmV2aW91c1N0YWNrIjpbXSwiZmlsdGVycyI6eyJkYXRlRnJvbSI6bnVsbCwiZGF0ZVRvIjpudWxsfSwic29ydCI6ImRlc2MiLCJwYWdlU2l6ZSI6Mn0="
	}
}

📘
When in the middle of a cursor session, if you change the filters, you will reset your cursor session and receive an initial request that adheres to the new filters you have provided.

Conclusion

That is all there is to using the pagination system. It is a simple system that should allow you to access the data that you need given timeframes and perhaps some UI based views on your own platform.