.. _API_resource_listing_best_practice:


API resource listing best practice
----------------------------------

.. _20.1.1|VOSS-695|EKB-3868:

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:

.. tabularcolumns:: |p{2.5cm}|p{8cm}|p{2cm}|p{2.5cm}|

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


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