Chunking

In an effort to improve server response time, chunking is used to reduce the size of the response. The size of a chunk is predefined by the server and is set to 25. This way the client can not unintentionally waste resources.

The response body of a collection resource will contain a Collection Object. If there are more items to be retrieved, that collection will have a property containing the link for the next chunk in the collection. This property is named next. It will also have a property named previous containing the link to the previous chunk in the collection if it’s not the first chunk. Clients are discouraged from constructing these URLs and instead should rely on the resource to provide them with the necessary navigational links.

Here is an example response of a chunked collection:

{
  "items": [ ... ],
  "total_items": 36,
  "returned_items": 25,
  "next": {
    "href": "/entitydefinitions/M.Asset/entities?skip=25",
    "title": "The next page in this collection"
  },
  "self": {
    "href": "/entitydefinitions/M.Asset/entities",
    "title": "This collection"
  }
}

As shown in the example above, if the chunk is at the beginning of the list there will be no previous property. Consequently, if it's at the end of the collection, there will be no next property.

The following pseudocode demonstrates how a client might want to retrieve a complete collection:

var list = []
var url = '/resource'
do while (url != null) {
  var resource = fetch(url)
  list.append(resource.items)
  url = resource.next 
}

This automatic chunking is only applicable to resources that return the type ListResource, which excludes the /search resource;

If you need to customize the chunking size and the item from which to start, you will need the skip and take parameters as described in the Ranging section.