.. _API_parameters: API Parameters -------------- .. _20.1.1|EKB-3608: .. _19.1.1|EKB-664: .. _20.1.1|VOSS-695|EKB-3868: .. note:: VOSS Automate will not support API Backward Compatibility from release 21.1 and future releases. From release 21.1 forward, the following must be removed from API requests. * API parameter: ``api_version=`` * Request header: ``X-Version:`` The hierarchy parameter is required for each API request and can be specified as any of the following: * the pkid of the hierarchy node in the form of a UUID, for example ``1c055772c0deab00da595101`` * in dot notation, for example ``ProviderName.CustomerName.LocationName`` To obtain the pkid of a hierarchy node, refer to the ``path`` element in the metadata of ``data/HierarchyNode`` resource. .. note:: For the purposes of simplifying the documentation, the hierarchy API parameter ``&hierarchy=[hierarchy]`` is not included in all examples in this document. Specifying the hierarchy is however required in all API requests where the instance pkid is not referenced. In the examples, ``[hierarchy]`` is substituted with the caller's hierarchy id. Format ......... The system API supports the following request parameters for data format when handling requests. .. tabularcolumns:: |p{2.5cm}|p{10.5cm}|p{2cm}| +-------------+-------------------------------------------------+-------+ | Key | Description | Value | +=============+=================================================+=======+ | format | The format type of the body of the request | json | +-------------+-------------------------------------------------+-------+ A request of the following format returns HTML: :: GET /api/(str:model_type)/(str:model_name)/help/ A parameter ``&format=json`` is not displayed in all examples, but it is required for all requests unless a different format is specifically stated. Configuration Template and Template Name ............................................. The Configuration Template can be specified in the POST request parameters for a resource as follows: :: POST /api/(str:model_type)/(str:model_name)/&template_name=[CFG name] .. tabularcolumns:: |p{2.5cm}|p{10cm}|p{2.5cm}| +---------------+------------------------------------------------------+-------------+ | Key | Description | Value | +===============+======================================================+=============+ | template | Apply the Configuration Template with pkid [CFG pkid]| [CFG pkid] | | | to the payload of the POST request. | | +---------------+------------------------------------------------------+-------------+ | template_name | Apply the Configuration Template with name [CFG name]| [CFG name] | | | to the payload of the POST request. | | +---------------+------------------------------------------------------+-------------+ Field Display Policy ..................... Field Display Policy can be specified in the GET request parameters for a resource as follows: :: GET /api/(str:model_type)/(str:model_name)/add/ .. tabularcolumns:: |p{2.5cm}|p{10cm}|p{2.5cm}| +-------------+------------------------------------------------------+-------------+ | Key | Description | Value | +=============+======================================================+=============+ | policy | Return a model form schema where the Field Display | [FDP pkid] | | | Policy with pkid [FDP pkid] is applied to it. Use | | | | ``policy`` with the parameters ``schema`` and | | | | ``format=json``. | | +-------------+------------------------------------------------------+-------------+ | 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 ........... The API can return cached data from the system or data from devices, using the following format: :: GET /api/(str:model_type)/(str:model_name)/[pkid]/ .. tabularcolumns:: |p{2.5cm}|p{8.5cm}|p{2cm}|p{2cm}| +--------+------------------------------------------------------+-------+---------+ | Key | Description | Value | Default | +========+======================================================+=======+=========+ | cached | System will respond with resource information where | true, | true | | | the data was obtained from cache. (Functionally only | false | | | | applicable to device models and domain models | | | | | containing device models) | | | +--------+------------------------------------------------------+-------+---------+ .. note:: From 11.5.2 onwards, the API URL ``cached`` parameter on the Subscriber list (``/api/relation/Subscriber/``) will not be honoured. Data presented to the API will always display cached information and will not refresh the information from the device during a list query with ``cached=false``. Resource instance ................. To identify a single resource, the API call contains the single resource (pkid) using the following format: :: GET /api/(str:model_type)/(str:model_name)/(pkid)/ Schema and Schema Rules ............................ To obtain the schema or schema rules of a resource, use the following parameters to an API request: :: GET /api/(str:model_type)/(str:model_name)/? hierarchy=[hierarchy]&schema=true&schema_rules=true .. tabularcolumns:: |p{2.5cm}|p{10.5cm}|p{2cm}| +----------------+------------------------------------------------------+-------------+ | Key | Description | Value | +================+======================================================+=============+ | schema | Return the schema of the resource. Use with the | true, false | | | parameter ``format=json`` | | +----------------+------------------------------------------------------+-------------+ | schema_rules | Return the GUI Rules and Field Display Policies of | true, false | | | the resource if available. Use with the parameters | | | | ``format=json`` and ``schema`` to see | | | | ``schema_rules`` in the response. | | +----------------+------------------------------------------------------+-------------+ List pagination ................ The system API supports the following two tables of API request parameters when specifying the format of and structure of the resources to list. * Pagination parameters .. tabularcolumns:: |p{2.5cm}|p{8cm}|p{2cm}|p{2.5cm}| +-------+---------------------------------------------------------------------------+--------+---------+ | Key | Description | Value | Default | +=======+===========================================================================+========+=========+ | skip | The list resource offset. If the ``Range`` request header is used, it | | 0 | | | will override this parameter. | | | +-------+---------------------------------------------------------------------------+--------+---------+ | 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. | | | +-------+---------------------------------------------------------------------------+--------+---------+ List format .............. * List format parameters .. tabularcolumns:: |p{2.5cm}|p{8cm}|p{2cm}|p{2.5cm}| +-----------+---------------------------------------------------------------------------+-------+---------------+ | Key | Description | Value | Default | +===========+===========================================================================+=======+===============+ | 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 | | +-----------+---------------------------------------------------------------------------+-------+---------------+ | traversal | The direction of the resource lookup of | up, | down | | | resources tied to the hierarchy tree from | down, | | | | the hierarchy node provided as parameter | local | | +-----------+---------------------------------------------------------------------------+-------+---------------+ .. note:: From 11.5.2 onwards for ``api/relation/Subscriber``: * The API URL ``summary`` parameter on the Subscriber list (``/api/relation/Subscriber/``) will not be honoured. Data presented to the API will always display summarized information and will not display full CUCM User data with ``summary=false``. * The API parameter ``traversal=up`` on the Subscriber list (``/api/relation/Subscriber/``) will not be honoured. Data presented to the API will default to display resources down the hierarchy tree with ``traversal=up``. Filter ............ Models that have the ``list`` action defined in their schema can also be filtered by using a number of URL filter parameters in parameter sets of four key-value pairs. Filters also apply to the ``api/tool/Transaction/`` endpoint, which has additional filter functionality to filter by transaction ID. Refer to the topic on Filter Transactions. These parameters can be added in addition to the parameters available to list resources as in the topic on API Parameters. A single filter query can contain one or more sets of the following four parameters: .. tabularcolumns:: |p{2.5cm}|p{7cm}|p{3cm}|p{2.5cm}| +------------------+-------------------------------------------------+---------------------------------------------------------------------------------+--------------+ | Key | Description | Value | Default | +==================+=================================================+=================================================================================+==============+ | filter_field | The model attribute name to filter. | The name of the attribute in the list of ``summary_attrs`` in the model schema. | | +------------------+-------------------------------------------------+---------------------------------------------------------------------------------+--------------+ | filter_condition | The matching operator for the ``filter_field``. | One of the conditions below, applied to a ``filter_text`` string value. | ``contains`` | | | If ``equals`` is used in a condition, then | | | | | other filter sets are ignored. | * ``startswith`` | | | | | * ``endswith`` | | | | | * ``contains`` | | | | | * ``notcontain`` | | | | | * ``equals`` | | | | | * ``notequal`` | | +------------------+-------------------------------------------------+---------------------------------------------------------------------------------+--------------+ | filter_text | A text string applied to the ``filter_field`` | Plain text | | | | by a ``filter_condition``. | | | +------------------+-------------------------------------------------+---------------------------------------------------------------------------------+--------------+ | ignore_case | Additional specifier applied to the case of the | Either ``true`` or ``false``. | ``true`` | | | ``filter_text``. | | | +------------------+-------------------------------------------------+---------------------------------------------------------------------------------+--------------+ Example showing a single filter set: :: GET /api/(str:model_type)/(str:model_name)/? hierarchy=[hierarchy] &filter_field=[attribute_name] &filter_condition=startswith &filter_text=John &ignore_case=false .. note:: For ``relation/Subscriber``, the list of ``filter_field`` values are restricted to: * ``userid`` * ``firstname`` * ``lastname`` * ``mailid`` * ``hierarchy_friendly_name`` * ``device`` * ``extension_mobility`` * ``phone`` If more than one filter set is used, all similar keys are grouped, so that the key position indicates the filter set. For example: :: GET /api/(str:model_type)/(str:model_name)/? hierarchy=[hierarchy] &filter_field=[attribute_name] &filter_field=[attribute_name2] &filter_condition=startswith &filter_condition=endswith &filter_text=John &filter_text=an &ignore_case=false &ignore_case=false The two filter sets in this example, are: * ``&filter_field=[attribute_name]`` * ``&filter_condition=startswith`` * ``&filter_text=John`` * ``&ignore_case=false`` and * ``&filter_field=[attribute_name2]`` * ``&filter_condition=endswith`` * ``&filter_text=th`` * ``&ignore_case=false`` Synchronous and Asynchronous ............................... It is possible to submit mutator type operations with API parameters to complete synchronously, in which case the synchronous response to the transaction either includes the status of the transaction or a fault response. This is not recommended as long-running transactions or a busy system may exceed the HTTP timeout. This is only available for models where the actions in the meta data contains ``support_async``. .. tabularcolumns:: |p{2.5cm}|p{8.5cm}|p{2cm}|p{2cm}| +---------+-------------------------------------------------------+-------+---------+ | Key | Description | Value | Default | +=========+=======================================================+=======+=========+ | nowait | Controls the API synchronous or asynchronous behavior | true, | false | | | for requests resulting in transactions. Please refer | false | | | | to the ``support_async`` property in the model schema | | | | | under **meta** -> **actions**, for an indication of | | | | | support per action. | | | +---------+-------------------------------------------------------+-------+---------+ Tags ..... To manage (add, remove) tags of a resource instance where the resource operations permissions allows tag management. .. tabularcolumns:: |p{2.5cm}|p{8cm}|p{4.5cm}| +-----+------------------------------------------------------+-----------------+ | Key | Description | Value | +=====+======================================================+=================+ | tag | * Applies to resource instance (````) | ```` | | | * Uses ``+tag`` in URL | | | | * Resource operation enables Tag | | | | * API call is PATCH on resource instance | See below. | +-----+------------------------------------------------------+-----------------+ ```` can be: 1. a tag name (no capital letters if tag should be searchable). 2. ``__CLEAR_TAG__`` to remove a tag ````. 3. ``__CLEAR_ALL_TAGS__`` to remove all tags. :: PATCH /api/(str:model_type)/(str:model_name)//+tag/? hierarchy=[hierarchy] &tag= .. note:: More than one ``tag`` parameter may be used, for example ``&tag=tag_one&tag=tag_two...`` Example JSON export of ``meta`` object of an instance showing: * ``tags``: "mytag", "another_tag" * ``version_tag``: "1.2" :: "meta": { "tags": [ "mytag", "another_tag" ], "pkid": "5ad5e4e3affa9343e4d9b140", "schema_version": "0.2.2", "hierarchy": "sys", "version_tag": "1.2", "model_type": "data/GeneralHelp" } Version Tags .............. To manage (add, remove) tags of a resource instance where the resource operations permissions allows tag management. .. tabularcolumns:: |p{2.5cm}|p{10.5cm}|p{2cm}| +-------------+------------------------------------------------------+-------------------------+ | Key | Description | Value | +=============+======================================================+=========================+ | version_tag | * Applies to resource instance (````) | ```` | | | * Uses ``+tag_version`` in URL | | | | * Resource operation enables Version Tag | for example | | | * API call is PATCH on resource instance | ``1.1``, ``1.2`` .. | +-------------+------------------------------------------------------+-------------------------+ :: PATCH /api/(str:model_type)/(str:model_name)//+tag_version/? hierarchy=[hierarchy] &version_tag= Example JSON export of ``meta`` object of an instance showing: * ``tags``: "mytag", "another_tag" * ``version_tag``: "1.2" :: "meta": { "tags": [ "mytag", "another_tag" ], "pkid": "5ad5e4e3affa9343e4d9b140", "schema_version": "0.2.2", "hierarchy": "sys", "version_tag": "1.2", "model_type": "data/GeneralHelp" } .. |VOSS Automate| replace:: VOSS Automate .. |Unified CM| replace:: Unified CM