Paging Through Results With Limit and Offset

Last modified on August 24, 2023 at 6:16 pm

Paging Overview

All URLs which return collections of resource results (e.g. GET /dc/api/v5/users) follow the same pattern for paging. When issuing your HTTP request, you can include two parameters which determine paging behavior:

limit

The limit parameter controls the maximum number of items that may be returned for a single request. This parameter can be thought of as the page size. If no limit is specified, the system defaults to a limit of 15 results per request. The maximum valid limit value is 100.

offset

The offset parameter controls the starting point within the collection of resource results. For example, if you have a collection of 15 items to be retrieved from a resource and you specify limit=5, you can retrieve the entire set of results in 3 successive requests by varying the offset value: offset=0, offset=5, and offset=10. Note that the first item in the collection is retrieved by setting a zero offset.

The response to these requests is typically a JSON object with the following three properties: results, next, and prev. The results property is simply an array of the items returned for your request. If you are paged into the result set, the prev property will contain a link to the previous page of results. A next property, if present, will contain a link to the next page of results based on your current limit and offset values.

Examples

First Page, Three Items at a Time

For this scenario, we will make a request to the users resource, limiting the results to three items per page. Notice the next property on the response object contains a link with an identical URL but with an adjusted offset to include the next set of items.

Request

GET /dc/api/v5/users?limit=3 HTTP/1.1
Host: api.digitalchalk.com
Accept: application/json

Response

HTTP/1.1 200 OK
Content-type: application/json
Content-length: 931

{
	"results": [
		{
		  "id": "7877a21a721f0fe399dc6f1086a45892",
		  "firstName": "Sam",
		  "lastName": "Spurlock",
		  "username": "sspurlock",
		  "email": "sspurlock@exampleorg.com",
		  "locale": "en",
		  "createdDate": "2009-04-15T00:50:04Z",
		},
		{
		  "id": "ac7272aa721f0fe399dc6f1086a45651",
		  "firstName": "Evan",
		  "lastName": "Anderson",
		  "username": "eanderson",
		  "email": "eanderson@exampleorg.com",
		  "locale": "en",
	  "createdDate": "2008-02-07T07:02:44Z",
		},
		{
		  "id": "3622881a721f0fe399dc6f1086a4510e",
		  "firstName": "Marc",
		  "lastName": "Sanchez",
		  "username": "msanchez",
		  "email": "msanchez@exampleorg.com",
		  "tags": [ "nm", "santafe" ],
		  "locale": "en",
		  "createdDate": "2009-04-15T00:50:04Z",
		  "lastLoginDate": "2013-11-05T06:27:02Z"
		}
	],
	"next": "http://api.digitalchalk.com/dc/api/v5/users?limit=3&amp;offset=3"
}

Second Page, Two Items at a Time

This time, we use limit and offset to select the second “page” of items in the collection. Because we are now beyond the first set of items, the result object contains a link back to the previous items in the prev property.

Request

GET /dc/api/v5/users?limit=2&amp;offset=2 HTTP/1.1
Host: api.digitalchalk.com
Accept: application/json

Response

HTTP/1.1 200 OK
Content-type: application/json
Content-length: 931

{
	"results": [
		{
		  "id": "3622881a721f0fe399dc6f1086a4510e",
	  "firstName": "Marc",
		  "lastName": "Sanchez",
		  "username": "msanchez",
		  "email": "msanchez@exampleorg.com",
		  "tags": [ "nm", "santafe" ],
		  "locale": "en",
		  "createdDate": "2009-04-15T00:50:04Z",
		  "lastLoginDate": "2013-11-05T06:27:02Z"
		},
		{
		  "id": "87340010a21f0fe399dc6f1086a6672a",
		  "firstName": "Travis",
		  "lastName": "Brown",
		  "username": "msanchez",
		  "email": "tbrown@exampleorg.com",
		  "locale": "en",
		  "createdDate": "2011-09-12T05:01:12Z",
		}
	],
	"next": "http://api.digitalchalk.com/dc/api/v5/users?limit=2&amp;offset=4"
	"prev": "http://api.digitalchalk.com/dc/api/v5/users?limit=2&amp;offset=0"
}