API – Paginating Responses

Introduction

The LMS API will occasionally respond with objects that contain a list of items rather than just a single item. This is most common with the following:

  • GET requests to OData endpoints where an ID is not specified
  • POST requests to Elasticsearch search endpoints

Response Objects with Multiple Results

By default, OData will return 50 results and Elasticsearch will return 10. These defaults are in place to limit endpoint bandwidth and lower response times while still providing an abundant amount of information.

But what if you don't want the first 10 or 50 results and instead want the second 10 or 50? What if you want to start the result set from a specific point? Both OData and Elasticsearch provide the necessary tools to do so in the form of endpoint parameters. This article will describe how to use endpoint parameters so that you can filter the information you receive in your requests.

Let's begin by looking at an example OData endpoint:

https://loanpro.simnang.com/api/public/api/1/odata.svc/Payments?$filter=entityId eq 5919&$top=30

At first glance, this might look a little hectic. You probably recognize the base URL, but near the end it just becomes a jumble of characters. But once you understand a bit of HTTP syntax, you'll be able to make sense of it.

LMS endpoint parameters are tacked on to the endpoint URL by first adding a single question mark (?) at the end of the URL before the parameter list. Then, the parameter name is added and is preceded by a dollar sign ($). The parameter name is followed by an equals sign (=) and a value. Lastly, if you are using multiple endpoint parameters, an ampersand (&) is placed between each one. Listed below is the order of a parameter list as well as examples of endpoints with parameters.

Here's an example OData endpoint:

Example

Description

https://loanpro.simnang.com/api/public/api/1/

The base URL for all LMS endpoints.

odata.svc/Payments

The OData endpoint for Payments.

?

HTTP syntax. The question mark indicates that the regular endpoint has ended, and everything that follows is an endpoint parameter that will limit or expand the results.

$filter

The parameter name. The dollar sign indicates that it is an OData token that can carry out a specific function beyond a normal parameter that simply holds a value.

=entityId eq 5919

The value. The equals sign connects this to the parameter name that preceded it.

&

HTTP syntax. The ampersand distinguishes between parameters.

$top

A second parameter name, indicating how many results should be shown.

=30

The value matching the $top parameter name. It tells the system we want the top 30 entries.

And here's an example Elasticsearch endpoint:

Example

Description

https://loanpro.simnang.com/api/public/api/1/

The base URL for all LMS endpoints.

Loans/Autopal.Search()

The Elasticsearch endpoint for searching loans.

?

HTTP syntax. The question mark indicates that the regular endpoint has ended, and everything that follows is an endpoint parameter that will limit or expand the results.

$start

The parameter name, indicating where the results should begin.

=20

The value paired to the preceding parameter. In this case, it tells the system to start the results at the twentieth entry.

&

HTTP syntax. The ampersand distinguishes between parameters.

$top

A second parameter name, indicating how many entries should be shown.

=30

The value matching the $top parameter name. It tells the system we want the top 30 entries.

Currently, the LoanPro LMS OData implementation only supports paging parameters at the root level and not for nested associated entities. Due to this, you'll need to submit requests to the correct endpoints.

A desired request such as:

GET /odata.svc/Loans(5919)/Payments?$top=30

will not work as assumed, and should instead be written as:

GET /odata.svc/Payments?$filter=entityId eq 5919&$top=30

Paging with OData Requests

Set Page Size

Let's say you're dissatisfied with the default page size that OData provides; however, you also don't want all of the results returned to you. Instead, you'd like to set the page size. We can do this with the $top parameter. This does not guarantee that the specified amount of results will be returned, and it will not change the order the items are returned. But it will guarantee that no more than the specified number of items are returned.

https://loanpro.simnang.com/api/public/api/1/odata.svc/Payments?$filter=entityId eq 5919&$top=200

Skip and Skiptoken

We've covered altering the page size, but how about retrieving results from a specified point and beyond? To achieve this, we can use the $skip and $skiptoken parameters. The $skip parameter allows you to do exactly that: skip however many results you'd like and return the results that follow.

https://loanpro.simnang.com/api/public/api/1/odata.svc/Payments?$filter=entityId eq 5919&$skip=50

Where $skip specifies a static number of results to skip, $skiptoken allows you to specify an exact ID from the database for the entity to skip past and return the results that follow.

https://loanpro.simnang.com/api/public/api/1/odata.svc/Payments?$filter=entityId eq 5919&$skiptoken=239898
Both $skip and $skiptoken are non-inclusive, meaning wherever you skip to will not be included in the results (e.g. $skip=50 will not include result 50; returned results will start at 51)

Filter

The last parameter we'll cover for OData requests is $filter, which allows you to restrict the result set that will be returned without having to use an Elasticsearch query object.

The $filter parameter can be used on any property returned in a list item for the endpoint and follows this basic structure:

Example

Description

https://loanpro.simnang.com/api/public/api/1/

The base URL for all LMS endpoints.

odata.svc/Payments

The OData endpoint for Payments.

?

HTTP syntax. The question mark indicates that the regular endpoint has ended, and everything that follows is an endpoint parameter that will limit or expand the results.

$filter

The parameter name, indicating the results limitation.

=entityId eq 5919

The value paired to the preceding parameter. In this case, it tells the system to only retrieve results who have an entityId equal to 5919.

and

Keyword to separate expressions in the same $filter parameter.

date lt datetime'2021-10-04T00:00:00'

The second value paired to the preceding parameter. In this case, it tells the system to only retrieve results who have a date that is less than the date of 10/04/2021 at 00:00:00.

The $filter parameter supports the following comparison operators; eq (equal), lt (less than), gt (greater than), le, (less than or equal to), and ge (greater than or equal to).

Additionally, any string values being compared to should be contained in single quotes ('string'). This will include any dates, datetimes, words, sentences, etc.

You can use $filter with any name/value pair from the JSON object that is returned by default in the response from the entity. For example, the response from a payment list item includes a comment field. You could add a filter token to find only the payments with a specific comment: $filter=comments eq 'A Specific Comment' 

Response Summary

Each OData request response will contain a small summary object with the following properties:

  • start - The index at which the results list starts
  • pageSize - The set page size
  • total - The number of results returned in the results list

Paging with Elasticsearch Requests

Set Page Size

Setting page size in the search endpoints works in the same way as the OData endpoints. If you'd like to set the page size, you can do so with the $top parameter. Again, this does not guarantee that the specified amount of results will be returned, and it will not change the order the items are returned, but it will guarantee that no more than the specified number of items are returned.

https://loanpro.simnang.com/api/public/api/1/Loans/Autopal.Search()?$top=50

Start

The OData parameters of $skip and $skiptoken are not supported for the search endpoints. Instead, these requests utilize the $start parameter to specify a starting place for the results. For example, using $start for search endpoints functions the same way as $skip for OData.

https://loanpro.simnang.com/api/public/api/1/Loans/Autopal.Search()?$start=50

Response Summary

Each search request response will contain a small summary object with the following properties:

  • totalHits - The total number of results returned from the query (this will not match the results contained in the results list, as this is handled with paging)
  • totalTime - The amount of time it took to retrieve results


How did we do?


Powered by HelpDocs (opens in a new tab)