5.14.3 api dir update

The /api/dir/update function updates an array of entries in the directory and sets their selected fields.

Methods

PUT

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 representation.

Table 1. Request JSON Keys

Key Name

Mandatory

Expected Values

Default Value

Description

users

Yes

array of JSON objects defining parameters of an entry in the directory

-

The array has to contain at least one object with the key uuid, which defines the entry to be updated.

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.

Example of Request

URL: https://192.168.1.1/api/dir/update JSON { "users": [ { "uuid": "01234567-89AB-CDEF-0123-456789ABCDEF", "name": "ABCD", "email": "abcd@def.cz", "access": { "pin": "1234" } }, { "uuid": "76543210-68FF-18CA-3210-FEDCBA987654", "name": "ABCD2", "owner": "My2N", "email": "abcd2@def.cz" }, { "uuid": "01234567-89A-CDEF-0123-456789ABCDEF", "name": "ABCD3", "owner": "My2N", "email": "abcd3@def.cz" }, { "uuid": "01234567-89AB-CDEF-0123-456789ABCDEF", "name": "ABCD4", "owner": "My2N", "email": "abcd4@def.cz", "albert": "einstein" }, { "uuid": "01234567-89AB-CDEF-0123-456789ABCDEF", "name": "ABCD4", "owner": "My2N", "email": "abcd4@def.cz", "access.pin": "hello" } ] }

If there is no entry in the directory with uuid 01234567-89AB-CDEF-0123-456789ABCDEF, the device will respond with an error code (see below). Similarly for the second uuid 76543210-68FF-18CA-3210-FEDCBA987654.

If the entry with uuid 01234567-89AB-CDEF-0123-456789ABCDEF is present, it will update its parameters according to the specified values for various keys. Similarly for the second uuid 76543210-68FF-18CA-3210-FEDCBA987654.

The third entry will not be updated (uuid has a wrong format).

The fourth entry will not be updated (unknow field name).

The fifth entry will not be updated (wrong format of access pin).

Response

The response is in the application/json format. The result object contains the keys series and users.

Go to the topic api/dir/query to get more information on the use of the key series.

The key users contains an 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.

Table 2. Response JSON Keys in the users Array

Key	Typical Returned Values	Description
uuid	uuid	Unique User Identifier of a modified or unchanged entry.
timestamp	integer	A timestamp of performed changes in the directory. Go to the topic api/dir/query to get more information on the use of the timestamp. The timestamp is present only when a change in the directory was successful.
errors	array of error objects	An error object containing array of all errors that occured. errors key is present only when a change in the directory failed. It contains an error code in the key code showing a reason for the failure of a change in the directory. It may contain a further specification of the error reason in the key field for error codes `EDIR_FIELD_NAME_UNKNOWN` and `EDIR_FIELD_VALUE_ERROR` showing which key or value violates the validation rules. The following error codes may be returned in a response: `EDIR_UUID_DOES_NOT_EXIST` - entry with the given uuid does not exist (i.e. cannot be updated). `EDIR_UUID_IS_MISSING` - the mandatory key uuid is missing. `EDIR_UUID_INVALID_FORMAT` - uuid is not in the valid format which is "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX", where X can be any hexadecimal digit. All zeroes are reserved as an empty uuid. `EDIR_FIELD_NAME_UNKNOWN` - unknown key. The list of available keys for a particular device can be obtained using the /api/dir/template function. `EDIR_FIELD_VALUE_ERROR` - a specified value does not fit the validation criteria (the value is not valid). `EDIRLIM_PHOTO` - the limit of the photo storage has been reached. Photos cannot be added. `EDIRLIM_FPT` - the limit of the fingerprint template storage has been reached. Fingerprint templates cannot be added. `EINCONSISTENT` - there is an inconsistency in the values of the keys validFrom and validTo (validFrom has to be lower than validTo).

Example of Response

{ "success": true, "result": { "series": "6423407687606431951", "users": [ { "uuid": "01234567-89AB-CDEF-0123-456789ABCDEF", "timestamp": 39 }, { "uuid": "76543210-68FF-18CA-3210-FEDCBA987654", "errors": [ { "code": "EDIR_UUID_DOES_NOT_EXIST" } ] }, { "uuid": "01234567-89A-CDEF-0123-456789ABCDEF", "errors": [ { "code": "EDIR_UUID_INVALID_FORMAT" } ] }, { "uuid": "01234567-89AB-CDEF-0123-456789ABCDEF", "errors": [ { "code": "EDIR_FIELD_NAME_UNKNOWN", "field": "albert" } ] }, { "uuid": "01234567-89AB-CDEF-0123-456789ABCDEF", "errors": [ { "code": "EDIR_FIELD_VALUE_ERROR", "field": "access.pin" } ] } ] } }

The first entry in the directory is updated successfully, its uuid and timestamp of the change are returned.

The second entry does not exist (no entry with such uuid).

The third object has a wrong format of uuid.

An unknown key albert has been passed in the fourth object.

An invalid value of PIN has been passed in the fifth object.