Getting results in pages

If other operations occur on the users account which change the order of the items being requested, you may encounter duplicates and/or skipped items while paging through a set.

One way or another, your application will probably be dealing with albums and images, and SmugMug has a lot of both. In the SmugMug API, every endpoint that returns multiple objects has support for paging, so you can get results in smaller, more manageable increments.

How to use paging

In this request, we ask for the first two child nodes of /api/v2/node/zx4Fx (a node is a folder, album, or page):

Here are a few things to look for in the response:

  • Response.Node is a JSON array containing two Node objects
  • Response.Pages.NextPage is the URI of the next page

You'll probably want a larger page size in your application.

Fields in Response.Pages

Name Description
Count The number of items actually returned in the response
RequestedCount The number of items that were requested. This is the same as the count parameter provided in the query argument, except it may be clamped to a per endpoint defined maximum value
Total The complete number of items available
Start The 1-based index in the total set of the first item in this request
FirstPage The URI that will return the first RequestedCount items in the set
PrevPage The URI that will return the previous RequestedCount items in the set. In some cases this may not be available, see below for more details about the Misaligned field
NextPage The URI that will return the next RequestedCount items in the set.
LastPage The URI that will return the last (incomplete) page of items in the set. The URIs start will be a multiple of the count parameter
Misaligned See below for further details

The Response.Pages section contains several entries to help you traverse a large dataset using paging. The entries can be broken into two categories: count/index related entries and navigation links.

The navigation links are designed to help you easily make subsequent requests for pages. The generated links will always be created using the same count= in the original request in order to ensure a repeatable page size across all requests.

Misaligned Pages

The Response.Pages object can contain four different URLs: FirstPage, PrevPage, NextPage, and LastPage.

These URLs are generated using the same count value as the current request. In the event you have made a request which uses a start value that is not a multiple of your count value, these links will still appear, but you will not be able to iterate all the way to the beginning of the item set using the PrevPage link. If this is the case, Response.Pages.Misaligned will be set to true to let you know about the error. The link will appear until the API no longer has a complete set of items to return using the current count value.