Manipulating Large Collection Results Requests - Intergraph Smart Instrumentation - Version 2.3 - Training - Intergraph

Intergraph Smart Instrumentation Web API Tutorial

Language
English
Product
Intergraph Smart Instrumentation
Subproduct
Web API
Search by Category
Training
Smart Instrumentation Web Version
2.3.7

The maximum number of items that can be retrieved on a single page of the payload is set by default to 25, though you can set it to any number you require between 1 to 1000. (See requests 05.04 and 05.05 in this topic.) The pagination uses $top and $skip query options to select the next set of data. We recommend including the $orderby query option on properties with distinct values as part of the request, so that pagination is consistent. Alternately, you can sort by multiple properties.

It is important to understand that the $count reflects the scope of the data and is not affected by the number of items showing in the page (i.e. if you ask for $top=3 the count will not necessarily be 3).

The system queries add options to the request that help with keeping the number of items displayed in the result.

Method

Description

$orderby

The $orderby query option specifies the order in which items are returned from the service.

$top

The $top query option specifies a non-negative integer n that limits the number of items displayed on the page.

$skip

The $skip query option specifies a non-negative integer n that excludes the first n items of the queried collection from the result

Get Pagination - Default

This request fetches the Items in ascending order, using the $orderby method.

  • Select the 05.01 Pagination - Default request and click Send.

    {{baseUri}}api/si/{{versionNumber}}/Sites('{{SiteId}}')/PlantGroups('{{PlantGroupId}}')/Projects('0')/InstrumentProject?$select=Id,InstrumentName,InstrumentType,LoopName&$orderby=InstrumentName asc

    The bottom of the response displays a link to the next items, skipping the first 25 items.

  1. Click the ellipses (…) next to the request and select Duplicate from the list.

  2. Copy the link and paste it in the GET address bar to retrieve the next set of 25 items.

Get Pagination - $top=3

This request uses '$top' to include only the top number of items in the result. In our case, the request is for the first three instruments.

  • Select the 05.02 Pagination - $top=3 request and click Send.

{{baseUri}}api/si/{{versionNumber}}/Sites('{{SiteId}}')/PlantGroups('{{PlantGroupId}}')/Projects('0')/InstrumentProject?$select=Id,InstrumentName,InstrumentType,LoopName&$orderby=InstrumentName asc&$top=3&$count=true

In this case there is no next link and the count reflects the total number of items.

Get Pagination - $top under $expand

This request expands the top three cable sets of a cable with Id=4568. This cable is "C-101-JB-DCS-001/1" from the demo database.

  • Select the 05.03 Pagination - $top under $expand request and click Send.

    {{baseUri}}api/si/{{versionNumber}}/Sites('{{SiteId}}')/PlantGroups('{{PlantGroupId}}')/Projects('0')/CableProject('4568')?$expand=CableSetCable($count=true;$top=3)

For more information and uses of the $expand method, see Requests using $expand Method (see $expand Method Requests).

Pagination using odata.maxpagesize

The system’s default number of items that can be displayed in one page is 25 and a link at the bottom of the payload provides access to the next 25 items. From Smart version 2.3.7, the page size can be set to a different value (up to a maximum of 1000) per request by specifying odata.maxpagesize in the request's parameters or as a header.

The following request includes the required odata.maxpagesize value in the request:

Select the 05.04 Pagination - Using odata.maxpagesize as a query option request and click Send.

{{baseUri}}api/si/{{versionNumber}}/Sites('{{SiteId}}')/PlantGroups('{{PlantGroupId}}')/Projects('0')/CableProject?$select=Id,CableName&$odata.maxpagesize=3

SIWEBAPI_05_04

The next page includes ?$skip=3 link.

The following request includes the required odata.maxpagesize as a preference header using the prefer key.

SIWEBAPI_05_05

Select the 05.05 Pagination - Using odata.maxpagesize in a preference header request and click Send.

The payload for this request will include 10 cables.

  • You can include $top and skip in the request.

  • If sending a request with odata.maxpagesize in the request and in the preference header, the governing value will be taken form the request.

  • The system uses a value of 25 as default when odata.maxpagesize is not stated.

  • The odata.maxpagesize is not supported under $expand.