5.14.2 api dir create

The /api/dir/create function creates (or overwrites) 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 NameMandatoryExpected ValuesDefault ValueDescription

force

No

truefalse

false

This key selects whether the entry in the directory identified by uuid (see below) is overwritten by the new set of data.

When the value for this key is set to true, a new dataset overwrites the existing data and the remaining fields are reset to their default values.

When it is set to false or omitted and there is an existing entry in the directory with the specified uuid, the device replies with error code EDIR_UUID_ALREADY_EXISTS and changes to the configuration are not processed.

This key does not affect a creation of a new entry in the directory in any way.

users

No

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

-

If this key is omitted or if its value is an empty array, the device response contains only the key series (no new entries in the directory are created).

It is possible to submit empty objects in the array. The device creates an empty entry in the directory for each empty object (it is only assigned a uuid).

If an object in the array contains the key uuid, an entry with the specified uuid is created or modified, or the device replies with an error code.

If an object in the array does not contain uuid, the device creates a new entry and assign it a new uuid. The entry parameters are set to the values according to the keys defined in the JSON structure of a request. Study the example below.

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/create JSON { "force": true, "users": [ { "uuid": "01234567-89AB-CDEF-0123-456789ABCDEF", "name": "ABCD", "email": "abcd@def.cz", "access": { "pin": "1234" } }, { "name": "ABCD2", "owner": "My2N", "email": "abcd2@def.cz" }, { "uuid": "01234567-89AB-CDEF-0123-456789ABCDEF", "name": "ABCD3", "email": "something", "access": { "pin": "5678" }, "test": "something", "albert": "einstein" }, {}, {} ] }

If there is no entry in the directory with uuid 01234567-89AB-CDEF-0123-456789ABCDEF, the device creates an entry in the directory with this uuid and set its parameters name, email and access to the specified values.


If there is an entry in the directory with uuid 01234567-89AB-CDEF-0123-456789ABCDEF, the device overwrites its parameters name, email and access to the specified values and sets all of its other parameters to their default values (because the key force is set to true).


The device creates a second entry, assigns it a random uuid, sets its name, owner and email to the specified values and leaves the rest of its parameters at default values.

The third entry does not overwrite the existing entry with the same uuid because there are several errors (wrong email format, two non-existent fields referenced by test and albert).


Furthermore, two new empty entries are created (because there are two empty objects in the array). Each is assigned a random uuid, the rest of their parameters are set to default values.


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
KeyTypical Returned ValuesDescription

uuid

uuid

Unique User Identifier of a created, 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. Timestamp is present only when a change in the directory was successful.

errors

array of error objects

An error object containing an array of all errors that occured. errors object is present only when a change in the directory failed.

It contains an error code in the value of 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 value of 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_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_UUID_ALREADY_EXISTS - an entry with the specified uuid exists in the directory and the key force is set to false or omitted. Therefore the requested modification cannot be performed.

  • 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 - the specified value does not fit validation criteria (the value is not valid).

  • EDIRLIM_USER - the directory is full.

  • EDIRLIM_PHOTO - the limit of photo storage has been reached. New entries can be created without photos.

  • EDIRLIM_FPT - the limit of fingerprint templates storage has been reached. New entries can be created without fingerprint templates.

  • 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": 34 }, { "uuid": "044197A7-54AD-7577-6EEA-787A6097263E", "timestamp": 35 }, { "errors": [ { "code": "EDIR_FIELD_VALUE_ERROR", "field": "email" }, { "code": "EDIR_FIELD_NAME_UNKNOWN", "field": "test" }, { "code": "EDIR_FIELD_NAME_UNKNOWN", "field": "albert" } ] }, { "uuid": "41970B83-21C8-45DD-8FFC-787A6097263E", "timestamp": 36 }, { "uuid": "0447BBA7-6E7c-420C-A654-466D43D6A067", "timestamp": 37 } ] } }


The first entry is created with the specified uuid and fields (unspecified fields are set to their default values). The entry gets created regardless whether there is an already existing entry with the same uuid because the key force in the request is set to true. The timestamp of the change is returned.


The second entry is created, assigned a random uuid and its specified fields are filled (unspecified fields are set to their default values). The timestamp of the change is returned.

The third object in the request contained an invalid email address format. Furthermore, non-existent fields were referenced by the keys test and albert.


The fourth and fifth entries where created successfully with randomly assigned uuids and all fields set to default values. The timestamp in the device updated twice to reflect that. The timestamps of the changes are returned.


Tip

  • If the key force in the request is not set to true, any attempts to create an entry with the existing uuid end with error code EDIR_UUID_ALREADY_EXISTS.