Paging
Lists come back a page at a time. Transmission feeds and classified ads page with a cursor; other lists page by number. Either way, follow hasMore until it's false.
The list envelope
A list is an object with two parts: data, the page's items, and paging, which says how to get the next page.
{
"data": [
{ "transmissionId": "3f2c8a51-7d4e-4b9a-9c1e-2a6f0b8d5e17", "...": "..." }
],
"paging": {
"nextCursor": "NjM5MTMyNTE2MDAwMDAwMDAwOjhmMTRlNDVmY2VlYTRjMmE5YjNkMWU2ZjVhN2MyZDkw",
"hasMore": true,
"newestCursor": "NjM5MTMyNTE5MDAwMDAwMDAwOjJhOWIzZDFlNmY1YTdjMmQ5MDhmMTRlNDVmY2VlYTRj"
}
}A list with nothing in it has an empty data, not a 404. A few responses aren't in the envelope:
- Short lists come back as a plain array, with no paging: hub categories, classified categories and subcategories, a Site's event years, both searches (at most 10 results each) and emoticons.
- A Site's catalog home is an object of its own: the Site, its categories, and featured and recent products.
- A catalog category is
{ category, products, paging }: the products are inproducts, notdata. - A single resource, such as a profile or one transmission, is the resource itself.
Two kinds of list
| List | How you page | Page size |
|---|---|---|
| Transmission feeds: a user's, a Site's, a hub's, a hashtag's | cursor |
take: 1–25, default 20 |
| A category's classified ads | cursor |
take: 1–100, default 20 |
| Followers, following, hub members, hubs in a category, a Site's events | page, up to 1000 |
pageSize: 1–100, default 20 |
| A catalog category | page, up to 34 |
Always 30 |
Cursor lists
Cursor lists are newest first. To read one:
- Call it without a
cursorto get the newest page. - While
paging.hasMoreistrue, call it again withcursorset to the last page'spaging.nextCursor. Each page is older than the one before. - When
hasMoreisfalse, you've reached the end, andnextCursorisnull.
curl "https://api.blazot.com/v2/users/exampleuser/transmissions?take=25&cursor=NjM5MTMyNTE2MDAwMDAwMDAwOjhmMTRlNDVmY2VlYTRjMmE5YjNkMWU2ZjVhN2MyZDkw" \
--header "Authorization: Bearer $BLAZOT_TOKEN"Send the same parameters with every page. take, a hashtag feed's tags, and on account feeds includeRelays and includeHubTransmissions aren't part of the cursor.
Go by hasMore, not by how many items came back. A page can hold fewer than take items, or none, and still have more after it: an account feed leaves out a relay whose original you can't see, and with a Site's key, every transmission feed leaves out transmissions from accounts that have blocked the Site's owner.
User, Site and hashtag feeds also give a newestCursor, for fetching only what's new since you last looked: see Polling for new transmissions. Hub feeds and classified ads have none, and neither does a page fetched with cursor.
Cursors are opaque
Pass a cursor back exactly as you got it. Don't build one, change one, or read meaning into its contents: what's inside can change without notice. Use a cursor only with the list it came from. A cursor the API can't read is a 400, and on the feeds you can poll, sending both cursor and newerThan is a 400 too.
Page-numbered lists
Ask for a page by number, from 1, and say how many items you want with pageSize:
curl "https://api.blazot.com/v2/users/exampleuser/followers?page=2&pageSize=100" \
--header "Authorization: Bearer $BLAZOT_TOKEN"{
"data": [
{ "userName": "anotheruser", "...": "..." }
],
"paging": {
"page": 2,
"pageSize": 100,
"hasMore": true
}
}While hasMore is true, ask for page + 1, with the same pageSize, and for a Site's events the same year. A page past the end of the list has an empty data; a catalog category answers 404 instead.
- The deepest page is 1000 (34 for a catalog category, which pages 30 products at a time and takes no
pageSize). A higher number is served as that page, andpaging.pageshows the page you got.hasMoreis alwaysfalsethere, so paging stops even if the list goes on. A catalog category with fewer than 34 pages answers404to a higher number, as a page past the end. - Lists can shift while you page. Each page is counted from the start of the list as it stands when you ask, so a new follower or event added in between can move items from one page to the next. Expect an occasional repeat, and key items by their username or id.
Out-of-range values
Paging values outside their range are brought into it, not refused:
- A
takeorpageSizeabove its maximum is lowered to the maximum; zero or less gives the default (20). - A
pageof zero or less gives page 1; above the deepest page gives the deepest page.
A page-numbered list's paging shows the page and pageSize it used, so you can see when a value was changed. A cursor list doesn't echo take. A value that isn't a number at all, such as take=abc, is a 400: see Errors.