5.14.6 api dir query
The /api/dir/query function retrieves an array of entries in the directory defined by timestamp iterator and their specified fields.
Methods
- POST
Request
The request contains parameters in the application/json format. Go to the topic api/dir/template to get more information on various parameters of an entry in the directory and their object representation.
| Key Name | Mandatory | Expected Values | Default Value | Description |
|---|---|---|---|---|
series | No | string | current device series | The string represent a number of the timestamps series in the device. If the key is not submitted, the current device series is considered. If the specified series differs from the current device series, the device will return its series, the highest timestamp value and invalid timestamp. |
fields | No | array of strings | all fields with non-default values | Specify the names of the required fields in the response, if the key is not specified, all fields with non-default values are returned, if an empty array is submitted, all available fields are returned. Go to the topic api/dir/template to get an overview of all available keys in the JSON definition of an entry in the directory. Unknown field names are ignored. |
iterator | No | JSON object | {"timestamp": 0} | The key defines the iterator for the query (timestamp iterator is supported). The timestamp iterator has an integer value. When specified, only newer entries are returned. The last timestamp is always returned by any of api/dir/create, api/dir/update or api/dir/delete and can be used as "the last known" change. If the timestamp iterator value is zero, all directory entries are returned. If the timestamp iterator value is higher or equal than the current timestamp value in the device, the device will return its series and the highest timestamp value. |
Example of Request
URL: https://192.168.1.1/api/dir/query JSON { "series": "2229480630597592840", "fields": [ "name", "email", "callPos.peer", "callPos[1].grouped" ], "iterator": { "timestamp": 6 } }
If the series is inconsistent with the current series in the device, the device returns its current series, the maximum value of the timestamp and invalid timestamp.
If the specified timestamp is lower than the current maximum timestamp, all the higher timestamps are returned.
The device is capable of handling of up to 10000 unique user identifiers. Once the number of uuids gets higher, the device returns key invalid, which indicates that there is an unknown history of the directory (there were entries in the directory that were deleted and the device no longer stores them).
If the specified timestamp is lower than the invalid timestamp, the device returns its current series, the maximum value of the timestamp and invalid timestamp.
Response
The response is in the application/json format. The result object contains the keys series and users.
The key users contains array of objects that contain keys and values of the result of the request (see the table below).
Tip
- You can get better acquainted with the structure of the JSON response in the example at the end of this topic.
| Key Name | Typical Returned Values | Description |
|---|---|---|
uuid | uuid | Unique User Identifier of a found entry. |
Various keys | various | Specified fields of an entry in the directory that are returned. See the api/dir/template. |
timestamp | integer | A timestamp of the last performed changes for each returned entry in the directory. The timestamp is present only when an entry in the directory is returned. |
Example of Response
{ "success": true, "result": { "series": "2229480630597592840", "users": [ { "uuid": "01234567-89AB-CDEF-0123-456789ABCDEF", "name": "ABCD", "email": "abcd@abcd.cz", "callPos": [ { "peer": "" }, { "peer": "", "grouped": "false" }, { "peer": "" } ], "timestamp": 7 }, { "uuid": "A6543210-68FF-18CA-3210-FEDCBA987654", "name": "DEFG", "email": "defgd@defg.cz", "callPos": [ { "peer": "" }, { "peer": "", "grouped": "false" }, { "peer": "" } ], "timestamp": 9 }, { "uuid": "044197A7-54AD-7577-6EEA-787A6097263E", "name": "HIJK", "email": "hijk@hijk.cz", "callPos": [ { "peer": "" }, { "peer": "", "grouped": "false" }, { "peer": "" } ], "timestamp": 10 } ] } }
Three entries in the directory that have timestamp higher than 6 are returned (in this case the maximum timestamp in the directory is 10).