API Parameters

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=<version_number>

  • Request header: X-Version:<version_number>

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.

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]

Key

Description

Value

template

Apply the Configuration Template with pkid [CFG pkid] to the payload of the POST request.

[CFG pkid]

template_name

Apply the Configuration Template with name [CFG name] to the payload of the POST request.

[CFG name]

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/

Key

Description

Value

policy

Return a model form schema where the Field Display Policy with pkid [FDP pkid] is applied to it. Use policy with the parameters schema and format=json.

[FDP pkid]

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

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]/

Key

Description

Value

Default

cached

System will respond with resource information where the data was obtained from cache. (Functionally only applicable to device models and domain models containing device models)

true, false

true

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

Key

Description

Value

schema

Return the schema of the resource. Use with the parameter format=json

true, false

schema_rules

Return the GUI Rules and Field Display Policies of the resource if available. Use with the parameters format=json and schema to see schema_rules in the response.

true, false

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

Key

Description

Value

Default

skip

The list resource offset. If the Range request header is used, it will override this parameter.

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

List format

  • List format parameters

Key

Description

Value

Default

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

traversal

The direction of the resource lookup of resources tied to the hierarchy tree from the hierarchy node provided as parameter

up, down, local

down

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:

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. If equals is used in a condition, then other filter sets are ignored.

One of the conditions below, applied to a filter_text string value.

  • startswith

  • endswith

  • contains

  • notcontain

  • equals

  • notequal

contains

filter_text

A text string applied to the filter_field by a filter_condition.

Plain text

ignore_case

Additional specifier applied to the case of the filter_text.

Either true or false.

true

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.

Key

Description

Value

Default

nowait

Controls the API synchronous or asynchronous behavior for requests resulting in transactions. Please refer to the support_async property in the model schema under meta -> actions, for an indication of support per action.

true, false

false

Tags

To manage (add, remove) tags of a resource instance where the resource operations permissions allows tag management.

Key

Description

Value

tag

  • Applies to resource instance (<instance_pkid>)

  • Uses +tag in URL

  • Resource operation enables Tag

  • API call is PATCH on resource instance

<tag_value>

See below.

<tag_value> can be:

  1. a tag name (no capital letters if tag should be searchable).

  2. __CLEAR_TAG__<tag_name> to remove a tag <tag_name>.

  3. __CLEAR_ALL_TAGS__ to remove all tags.

PATCH /api/(str:model_type)/(str:model_name)/<instance_pkid>/+tag/?
  hierarchy=[hierarchy]
  &tag=<tag_value>

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.

Key

Description

Value

version_tag

  • Applies to resource instance (<instance_pkid>)

  • Uses +tag_version in URL

  • Resource operation enables Version Tag

  • API call is PATCH on resource instance

<version_tag_value>

for example 1.1, 1.2 ..

PATCH /api/(str:model_type)/(str:model_name)/<instance_pkid>/+tag_version/?
  hierarchy=[hierarchy]
  &version_tag=<version_tag_value>

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"
          }