Hi Creators,
As a follow up to our post on user pagination of their most recently favorited items, we would like to share that the cursor-based pagination API for paging through your favorite bundles and assets has been released on CatalogApi and roblox.com.
As part of this change, we will be deprecating the pageNumber based pagination interface in favor of the cursor-based pagination interface. Please review our deprecation timeline below for more details. Users will still be able to paginate past the most recent 500 of their favorite items.
These changes are a result of an underlying storage technology upgrade which increases resiliency and reliability of our systems. The new storage technology only supports cursor based pagination, it is unable to support the page based pagination we currently use efficiently and at a large scale.
Previously, you would page through your favorited bundles using a pageNumber query parameter:
The sample response model is:
{
"favorites": [
{
"id": 0,
"name": "string",
"description": "string",
"bundleType": "string",
"items": [
{
"owned": true,
"id": 0,
"name": "string",
"type": "string"
}
],
"creator": {
"id": 0,
"name": "string",
"type": "string",
"hasVerifiedBadge": true
},
"product": {
"id": 0,
"type": "string",
"isPublicDomain": true,
"isForSale": true,
"priceInRobux": 0,
"isFree": true,
"noPriceText": "string",
"premiumPricing": {
"premiumDiscountPercentage": 0,
"premiumPriceInRobux": 0
}
},
"itemRestrictions": [
1
],
"collectibleItemDetail": {
"collectibleItemId": "string",
"name": "string",
"description": "string",
"collectibleProductId": "string",
"price": 0,
"lowestPrice": 0,
"lowestResalePrice": 0,
"totalQuantity": 0,
"unitsAvailable": 0,
"saleLocation": {
"type": 0,
"universeIds": [
0
],
"enabledUniverseIds": [
0
]
},
"hasResellers": true,
"saleStatus": 0,
"quantityLimitPerUser": 0,
"offSaleDeadlineTime": "2024-02-26T23:53:42.273Z",
"collectibleItemType": 0
}
}
],
"moreFavorites": true,
"nextCursor": "string",
"previousCursor": "string"
}
How to paginate forward
For the first page, you simply omit pageNumber from the query parameter. It will always return you items from the first page and the nextCursor for the next page in the response. For subsequent pages, specify a cursor query parameter with value equal to the value of nextCursor in your previous response.
How to paginate backwards
If you have paged to the end of your collection and would like to page to the previous page, you would set cursor query parameter to the value of previousCursor in your last received response and add isPrevious=true query parameter like so:
The API for paging through a user’s favorite assets works in a similar fashion.
Deprecation timeline and support:
We will continue to support both pagination interfaces until the end of May 2024. Developers and other users of our public APIs will have until that time to switch over to the new pagination interface. Only cursor based pagination will be supported after 1st June 2024.
Only the pageNumber query parameter will not be supported as part of this deprecation effort. Do take note that itemsPerPage query parameter will still work as before.
The above-mentioned APIs are not exposed in the Roblox Game Engine at all, hence we do not foresee any impact to game developers.
FAQ
What happens if I use both pageNumber and cursor?
-
If you pass in both pageNumber and cursor, we have no idea which pagination interface you are asking for, hence you will get 400 BadRequest. If you pass in any random string for the cursor, you would get a 500 InternalServerError.
Take note that the above endpoint for retrieving favorited bundles only works for the current authenticated user. You cannot request another user’s favorite bundles unless you are logged in as that user already.
Will my inventory page continue to work as it is?
- This feature has nothing to do with the items you own. Inventory page will continue to work.
Will my favorite page continue to work?
- The favorites page for assets and bundles has switched over to the new pagination interface. There is no further action required from you. You will continue to be able to access your favorite assets and bundles.
We thank you for your patience and welcome any feedback or ideas.
