Often times when you make an API call, there may be hundreds, thousands, or even tens of thousands of results. To ensure efficient performance of the API, we set a limit on the number of results displayed for each call. This page will help you understand how to navigate paging in the Dragon Metrics API.
By default all calls return 50 results. Using the parameter limit you can change this to your preferred value.
The maximum value you can use is 500. Making a request with a limit greater than 500 will receive a error. If this parameter is omitted, a default of 50 will be used.
If all calls are limited to a 500 results, how do you get the rest of the results if there are more than this? That's where the parameter start comes in. This parameter represents the index of the first result in the set returned. The default for start is 0, which is the first item in the collection.
For example, let's say you want to make a request to a collection that contains 1,000 results. If your first request is set to limit=50 and start=0, you will get back items 0-49. If you want the next page of results, you will set limit=50 and start=50 to get items 50-99. After this, you'd use limit=50 and start=100, and so on.
Using limit and start to page through large sets of results is simple enough, but we actually try to make it easier for you. Just about every API reponse contains a paging object, that contains everything you need to know about navigating around the entire set of results.
Here's an example of a typical response:
Let's take a look at this in a bit more detail:
- The first property, total, is the total number of results in the set
- The limit and start properties are the parameters used to make this call
- prev is the URL of the previous page of results. If at the first page of results, this value will be null.
- self is the URL of the current request that was just made
- next is the URL of the next page of results. If at the last page of results, this value will be null.
So to get all results in a collection, you can begin with start=0 for your first request. Then, if there is a value for next, use this URL for your next request. Repeat this process until the next value is null, which means you're at the final page of results.