Paginating responses from the API

Table of contents

Introduction

When you read data from the API, the API by default responds with all objects which match your filter. If there are too many objects which match your filter, this may cause timeouts. For instance, if the goods owner has 100 000 articles and you try to fetch them all with GetInventoryByQuery at the same time, you will most likely encounter a timeout.

To solve this issue, you need to paginate the results. Instead of making 1 API call which is supposed to return 100 000 articles, you can make 100 API calls where each response contains 1000 articles.

If the API function supports pagination, it is strongly recommended that you use it. In our experience, using pagination is particularly crucial for the functions GetInventoryByQuery, GetOrdersByQuery and GetInOrdersByQuery.

How to paginate

Pagination is achieved by combining two filters in your query:

  1. Max objects to return
  2. Only return objects whose ID is greater than "X"

In your initial query, you specify "max objects to return" = 1000. This is the first page of results.

When you have got back the response from the first query, you compute the greatest object ID which was returned. Call this number "X"

In your second query, you specify "max objects to return" = 1000, and this time you also specify "only return objects whose ID is greater than 1 + X". This will be the second page of results.

This procedure is repeated until you the responses are empty.

GetInventoryByQuery example

The GetInventoryByQuery API call is used to fetch article data and stock balances. It supports pagination using the filters MaxArticlesToGet and ArticleSystemIdFrom.

In pseudocode, paginating the responses looks like this: 


public List FetchArticles()
{
  var responses = new List();

  var query = new GetInventoryQuery();
  // Add your own filters to the query here.

  query.MaxArticlesToGet = 1000; // Each page will contain at most 1000 articles.

  int? maxArticleSystemId = null;

  while(true)
  {
	  if(maxArticleSystemId.HasValue)
	  {
		  // If the last page contained articles, for *this* page,
		  // we only want articles whose ID is greater than the last page's.
		  query.ArticleSystemIdFrom = 1 + maxArticleSystemId.Value;
	  }

	  var response = APIClient.GetInventoryByQuery(query);
	  if(response.InventoryLines.Count == 0)
	  {
		  // There are no more articles to fetch - we are done.
		  break;
	  }
	  else
	  {
		  // We got a page which contained articles.
		  responses.Add(Responses)
		  // Compute the maximum ArticleSystemId and save it for the next loop iteration.
		  maxArticleSystemId = response.InventoryLines.Max(line => line.Article.ArticleSystemId);
	  }
  }

  return responses;
}