Appendix 1. Reference commentary

Data types

Zabbix API always returns values as strings or arrays only.

Property behavior

Some of the object properties are marked with short labels to describe their behavior. The following labels are used:

read-only - the value of the property is set automatically and cannot be defined or changed by the user, even in some specific conditions (e.g., read-only for inherited objects or discovered objects);
write-only - the value of the property can be set, but cannot be accessed after;
constant - the value of the property can be set when creating an object, but cannot be changed after;
supported - the value of the property is not required to be set, but is allowed to be set in some specific conditions (e.g., supported if type is set to “Simple check”, “External check”, “SSH agent”, “TELNET agent”, or “HTTP agent”);
required - the value of the property is required to be set for all operations (except get operations) or in some specific conditions (e.g., required for create operations; required if operationtype is set to “global script” and opcommand_hst is not set).

For update operations a property is considered as “set” when setting it during the update operation.

Properties that are not marked with labels are optional.

Parameter behavior

Some of the operation parameters are marked with short labels to describe their behavior for the operation. The following labels are used:

read-only - the value of the parameter is set automatically and cannot be defined or changed by the user, even in some specific conditions (e.g., read-only for inherited objects or discovered objects);
write-only - the value of the parameter can be set, but cannot be accessed after;
supported - the value of the parameter is not required to be set, but is allowed to be set in some specific conditions (e.g., supported if status of Proxy object is set to “passive proxy”);
required - the value of the parameter is required to be set.

Parameters that are not marked with labels are optional.

The following parameters are supported by all get methods:

Parameter	Type	Description
countOutput	boolean	Return the number of records in the result instead of the actual data.
editable	boolean	If set to `true` return only objects that the user has write permissions to. Default: `false`.
excludeSearch	boolean	Return results that do not match the criteria given in the `search` parameter.
filter	object	Return only those results that exactly match the given filter. Accepts an array, where the keys are property names, and the values are either a single value or an array of values to match against. Doesn’t work for `text` fields.
limit	integer	Limit the number of records returned.
output	query	Object properties to be returned. Default: `extend`.
preservekeys	boolean	Use IDs as keys in the resulting array.
search	object	Return results that match the given wildcard search (case-insensitive). Accepts an array, where the keys are property names, and the values are strings to search for. If no additional options are given, this will perform a `LIKE “%…%”` search. Works only for `string` and `text` fields.
searchByAny	boolean	If set to `true` return results that match any of the criteria given in the `filter` or `search` parameter instead of all of them. Default: `false`.
searchWildcardsEnabled	boolean	If set to `true` enables the use of “*” as a wildcard character in the `search` parameter. Default: `false`.
sortfield	string/array	Sort the result by the given properties. Refer to a specific API get method description for a list of properties that can be used for sorting. Macros are not expanded before sorting. If no value is specified, data will be returned unsorted.
sortorder	string/array	Order of sorting. If an array is passed, each value will be matched to the corresponding property given in the `sortfield` parameter. Possible values: `ASC` - (default) ascending; `DESC` - descending.
startSearch	boolean	The `search` parameter will compare the beginning of fields, that is, perform a `LIKE “…%”` search instead. Ignored if `searchWildcardsEnabled` is set to `true`.

User permission check

Does the user have permission to write to hosts whose names begin with “MySQL” or “Linux” ?

Response:

{
           "jsonrpc": "2.0",
           "result": "0",
           "id": 1
       }

Zero result means no hosts with read/write permissions.

Mismatch counting

Count the number of hosts whose names do not contain the substring “ubuntu”

Response:

{
           "jsonrpc": "2.0",
           "result": "44",
           "id": 1
       }

Searching for hosts using wildcards

Find hosts whose name contains word “server” and have interface ports “10050” or “10071”. Sort the result by host name in descending order and limit it to 5 hosts.

Request:

Response:

{
           "jsonrpc": "2.0",
           "result": [
               {
                   "host": "WebServer-Tomcat02",
                   "interfaces": [
                       {
                           "port": "10071"
                       }
                   ]
               },
               {
                   "host": "WebServer-Tomcat01",
                   "interfaces": [
                       {
                           "port": "10071"
                       }
                   ]
               },
               {
                   "hostid": "50004",
                   "host": "WebServer-Nginx",
                   "interfaces": [
                       {
                           "port": "10071"
                       }
                   ]
               },
               {
                   "hostid": "99032",
                   "host": "MySQL server 01",
                   "interfaces": [
                       {
                           "port": "10050"
                       }
                   ]
               },
               {
                   "hostid": "99061",
                   "host": "Linux server 01",
                   "interfaces": [
                       {
                           "port": "10050"
                       }
                   ]
               }
           ],
           "id": 1
       }

Searching for hosts using wildcards with “preservekeys”

If you add the parameter “preservekeys” to the previous request, the result is returned as an associative array, where the keys are the id of the objects.

Request:

{
           "result": {
               "50003": {
                   "hostid": "50003",
                   "host": "WebServer-Tomcat02",
                       {
                           "port": "10071"
                       }
                   ]
               },
               "50005": {
                   "hostid": "50005",
                   "host": "WebServer-Tomcat01",
                   "interfaces": [
                       {
                           "port": "10071"
                       }
                   ]
               },
               "50004": {
                   "hostid": "50004",
                   "host": "WebServer-Nginx",
                   "interfaces": [
                       {
                           "port": "10071"
                       }
                   ]
               },
               "99032": {
                   "hostid": "99032",
                   "host": "MySQL server 01",
                   "interfaces": [
                       {
                           "port": "10050"
                       }
                   ]
               },
               "99061": {
                   "hostid": "99061",
                   "host": "Linux server 01",
                   "interfaces": [
                       {
                           "port": "10050"
                       }
                   ]
               }
           },