Access Rights

To protect data from third parties access rights will be queried by comparing keys. To read and edit data different keys are needed. Therefore a read key (ApiRdKey) to read data and a write key (ApiWrKey) to write data is used. This is shown in lisitng.
Serveral security levels are implemented, so that not every user has access to all data, if one key is known. This means, it's possible that multiple keys are needed for different data. This keys can be changed anytime by authorised personal.

Read Data

In order to read data from the device, an HTTP GET request at the desired API path has to be made. Its possible to read the whole json structure of one endpoint, as well as a part or just one variable of the endpoint with one request. Reading multiple endpoints with one request is not supported. The listing shows the general structure of a read request. A request with the command-line application "cURL" generates the shown HTTP-request. For example the response of a request to the URI http://192.168.15.100/api/v1/properties/name is only the name of the device. However, if the URI is http://192.168.15.100/api/v1/properties all device settings are received.

Example read access

Structure of the URI

http://<host>/api/v1/<path>

corresponding HTTP request

GET /api/v1/<path> HTTP/1.1\r\n
Host: <host>\r\n
ApiRdKey: <read key>\r\n
\r\n

Example read access using cURL

Read Command

curl -H "ApiRdKey: rdKey1" 192.168.15.100/api/v1/properties/name

corresponding HTTP request

GET /api/v1/properties/name HTTP/1.1\r\n
Host: 192.168.15.100\r\n
User-Agent: curl/7.55.1\r\n
ApiRdKey: rdKey1\r\n

Output

{"meta":{"error":0,"message":"JSON_ERROR_NONE"},"data":"enetmini"}

corresponding HTTP response

HTTP/1.0 200 OK\r\n
Content-type: application/json\r\n
Content-length: 66\r\n
\r\n
{"meta":{"error":0,"message":"JSON_ERROR_NONE"},"data":"enetmini"}

Edit Data

For editing data the HTTP PUT-method has to be used. Multiple values can only be changed, if they are in the same object. For example: setting the IP address and IP mask simultanously is possible, since they are in the same object. but setting the IP address and enabling SNTP client (setting the enable variable to true) is not possible since they are in different objects in the json structure.

The data must be added as content (http message body data) to the PUT request, encoded with the application/x-www-form-urlencoded MIME type. With the cURL command an HTTP request, as shown below, is generated.

Structure of the URI

http://<host>/api/v1/<path>

corresponding HTTP request

PUT /api/v1/<apth> HTTP/1.1\r\n
Host: <host>\r\n
ApiRdKey: <read key>\r\n
ApiWrKey: <write key>\r\n
Content-Length: <length of data>\r\n
Content-Type: application/x-www-form-urlencoded\r\n
\r\n
data...

example with cURL

Command

curl -H "ApiRdKey: rdKey1" -H "ApiWrKey: wrKey1" -v -X PUT -d "name=eNetMini1" 192.168.15.100/api/v1/properties

corresponding HTTP request

PUT /api/v1/properties HTTP/1.1\r\n
Host: 192.168.15.100\r\n
ApiRdKey: rdKey1\r\n
ApiWrKey: wrKey1\r\n
Content-Length: 14\r\n
Content-Type: application/x-www-form-urlencoded\r\n
\r\n
name=eNetMini1\r\n

Output

{"meta":{"error":0,"message":"JSON_ERROR_NONE"},"data":{}}

corresponding HTTP response

HTTP/1.0 200 OK\r\n
Content-type: application/json\r\n
Content-length: 58\r\n
\r\n
{"meta":{"error":0,"message":"JSON_ERROR_NONE"},"data":{}}

Response

A request on a valid REST API endpoint has always the HTTP response status 200 - OK., even if the path doesn't exist (e.g. /api/v1/data/test). Requests on a non existing REST API endpoint (e.g. /api/v1/test) will have the HTTP response status 404 - Not Found.

For a list of valid paths see Structure of Endpoints

The response on valid REST API paths is a JSON object containing two variables. The first ("meta") holds the information about the success of the request. The second ("data") holds the data in case of an read request.

example of a valid GET request to /api/v1/data/entries/0/pin

{ 
    "meta": {
        "error":0,
        "message":"JSON_ERROR_NONE"
    },
    "data": 0.000
}

This request is valid, since meta holds the error code 0 and respectively the message "JSON_ERROR_NONE" In this case we requested a specific variable, which is of type float (/api/v1/data/entries/0/pin) so the data variable holds a float value.

example of a valid GET request to /api/v1/data/entries/0

{
    "meta": {
            "error":0,
            "message":"JSON_ERROR_NONE"
        },
    "data":{
            "pin":0.000,
            "time":1504607559,
            "error":0,
            "Json+typeName":
            "MkcJsonLib.jDataAo",
            "Json+typeRevision":0
        }
}

This request is valid, since meta holds the error code 0 and respectively the error message "JSON_ERROR_NONE" In this case we made a request to an object (/api/v1/data/entries/0) so the data variable holds an object.

example of an an invalid GET request to /api/v1/data/test

{
    "meta":{
        "error":6,
        "message":"JSON_ERROR_TOKEN_NOT_FOUND"
        },
    "data":{}
}

In this case we made a request to a non existing object (/api/v1/data/test) so the meta variable hold the error code 6 and the corresponding error message. In this case the data object/value is empty or null. It should not be interpreted in any way.

Error Codes

The server's response always contains one of these API status codes and the corresponding status message.

status code	status message	description
0	JSON_ERROR_NONE	No error
1	JSON_ERROR_MEMORY_ALLOCATION	Not enough memory space could be reserved.
2	JSON_ERROR_MEMORY_TOKEN_NOT_FOUND	The token could not be found within a specific memory.
3	JSON_ERROR_UNKNOWN_HANDLE	The used handle is unknown.
4	JSON_ERROR_APIRDKEY	Wrong or missing ApiRdKey
5	JSON_ERROR_APIWRKEY	Wrong or missing ApiWrKey
6	JSON_ERROR_TOKEN_NOT_FOUND	The value to be edited could not be found.
7	JSON_ERROR_TOKEN_CHANGEFXN_NOT_FOUND	The function to edit a value is not implemented or the designation is incorrect.
8	JSON_ERROR_TOKEN_CHANGEFXN_NOT_ALLOWED	It's not allowed to change the selected value.
9	JSON_ERROR_TOKEN_CHANGEFXN_FAILED	Failed to change a value.
10	JSON_ERROR_SAVEFXN_FAILED	Failed to save a value.
11	JSON_ERROR_TYPE_OBJECT	No JSON object was used.
12	JSON_ERROR_TYPE_INTEGER	Provided value is not an Integer.
13	JSON_ERROR_TYPE_INTEGER_MINIMUM	Provided integer value is smaller than allowed.
14	JSON_ERROR_TYPE_INTEGER_MAXIMUM	Provided integer value is bigger than allowed.
15	JSON_ERROR_TYPE_INTEGER_UNSIGNED	Provided value is not an unsigned Integer.
16	JSON_ERROR_TYPE_STRING	Provided value is not a String.
17	JSON_ERROR_TYPE_STRING_LENGTH	Provided string is too long.
18	JSON_ERROR_TYPE_BOOLEAN	Provided value is not a Boolean.
19	JSON_ERROR_TYPE_DOUBLE	Provided value is not a Double.
20	JSON_ERROR_OBJECT_TYPENAME	The requested class doesn't exist.
21	JSON_ERROR_OBJECT_TYPEREVISION	The revision of the class is wrong.
22	JSON_ERROR_COUNT	Other Error