API resource listing best practice

This section provides best practices when using API GET requests when listing resources, and examines best practices for using a number of API request parameters and parameter values.

Note

For further details on API parameters, refer to the API Guide.

The table describes API request parameters for resource listing:

Parameter	Description	Value	Default
skip	The list resource offset as a number.		0
limit	The maximum number of resources returned. The maximum value is 2000. If the Range request header is used, it will override this parameter.	1-2000	50
count	Specify if the number of resources should be counted. If false, the pagination object in the response shows the total as 0, so no total is calculated and the API performance is improved.	true, false	true
order_by	The summary attribute field to sort on.		First summary attribute
direction	The direction of the summary attribute field sort (asc:ascending, desc: descending).	asc, desc	asc
summary	Only summary data is returned in the data object.	true, false	true
policy_name	Return a model form schema where the Field Display Policy with name [FDP name] is applied to it. Use policy with the parameters schema and format=json.	[FDP name]
cached	System will respond with resource information where the data was obtained from cache. (Functionally only applicable to device models and data models).	true, false	true

The table lists parameters with their best practice recommendations and considerations:

count	The value of count=true is very expensive in terms of performance, and more so as the size of the resource grows. The first count query of, for example, a 36 000 Data Number Inventory resource can take as long as a minute to return a response. However, subsequent calls should decrease in execution time. The value count=true should only be used if it is unavoidable. An alternative is to iterate over pages (limit=200) until the request returns less than 200 instances, or to simply paginate until no more resources are returned.
order_by	No performance change if another summary attribute is specified.
direction	No performance change if either values asc or desc are used.
policy_name	The parameter is used by the GUI for display purposes. Timing data shows that the initial call with this parameter takes longer than subsequent ones, possibly because of cache priming after a restart. Subsequent calls show the execution time is on par with requests that do not include the parameter.
summary	Depending on the data required by the request, time can be saved if the value summary=true, so that only the summary data is returned.
limit	Execution time and memory consumption is impacted if the limit value is large.

The recommended parameter values for an optimal API list request (GET) are as follows:

• cached=true

• summary=true

• count=false

• policy_name not used

Example results with various parameter values (36 000 Data Number Inventory resource):

count:true, skip:0, policy_name:, limit:200, summary:false in 6.51744103432 s
count:true, skip:0, policy_name:, limit:200, summary:true in 5.6118888855 s
count:false, skip:0, policy_name:, limit:200, summary:false in 1.55350899696 s
count:false, skip:0, policy_name:policy_name=HcsDNInventoryDatFDP, limit:200,
     summary:true in 5.17663216591 s
count:false, skip:0, policy_name:, limit:200, summary:true in 1.09510588646 s