Example:
POST /api/json HTTP/1.1 Content-Type: application/json; charset=utf-8 Host: localhost:8181 Content-Length: 79 { "tk": "1:QqjkQAtk4hyWRnbTt1+dZdGFCg3QE+nS", "browse": { "na": "" } }
http(s)://<ip/domain>:<port>/api/json
e.g.
http://localhost:8181/api/json
Method | POST |
---|---|
Content type | application/json |
Encoding | UTF-8 |
Content | JSON object |
Mandatory | Type | Purpose | |
---|---|---|---|
tk | yes (if username and password are not specified) | string | The Token of the Node which is to be authenticated. From this Node, all children will be relatively addressed. For how to find the Token see Node Access. e.g. the token for Node System/Plugins is set, then "na":"OPC UA Server" is the relative path for Node /System/Plugins/OPC UA Server . |
username | yes (if tk is not specified) | string | The email address or telephone number of the user to authenticate. |
password | yes (if tk is not specified) | string | The password of the user. |
get | no | object | Read Nodes |
browse | no | object | Read Nodes with all children (recursive) |
set | no | object | Write Nodes |
create | no | object | Create Nodes |
update | no | object | Update Nodes |
delete | no | object | Delete Nodes |
Example Request (using a Token):
{ "tk": "961:oseIqCm8WOOnPEE5g0tt1TZz2wbL/qUq", "get": { "na": "Temperature" } }
Example Request (using username-password):
{ "username": "demo@user.org", "password": "demo", "get": { "na": "/Demo-Nodes/Temperature" } }
Request frame:
{ "tk": /* Token */, "username": /* Username (if 'tk' not specified) */, "password": /* Password (if 'tk' not specified) */, "get": { /* "Get" elements */ }, "browse": { /* "Browse" elements */ }, "set": { /* "Set" elements */ }, "create": { /* "Create" elements */ }, "update": { /* "Update" elements */ }, "delete": { /* "Delete" elements */ } }
Mandatory | Type | Purpose | |
---|---|---|---|
get | no | object | Read & Browse response |
browse | no | object | Read & Browse response |
set | no | object | Write response |
create | no | object | Create response |
update | no | object | Update response |
delete | no | object | Delete response |
res | yes | object | Result of the query |
Possible res
results:
Mandatory | Type | Purpose | ||
---|---|---|---|---|
value | yes | number | Result codes: >= 0: OK - Everything is good! < 0: An error has occured! | |
reason | no | string | Reason for the error |
Example Response:
{ "get": { "nodes": [ { "id": 963, "na": "Temperature", "dn": "Temperature (°C)", "ds": "", "lo": null, "ty": "double", "hi": false, "min": -20, "max": 90, "unit", "°C", "values": [ { "va": 2, "ts": 1472738754519, "st": 0 } ] } ], "res": { "value": 0 } } }
Response Frame:
{ "get": { /* "Get" elements */ }, "browse": { /* "Browse" elements */ }, "set": { /* "Set" elements */ }, "create": { /* "Create" elements */ }, "update": { /* "Update" elements */ }, "delete": { /* "Delete" elements */ }, "res": { /* "Result" elements */ }, }
Mandatory | Type | Purpose | |
---|---|---|---|
id | yes (if na is not specified) | number | Local Identifier (“Id”) of the Node. |
na | yes (if id is not specified) | string | Name of the Node. When using a token for authentication, this is the relative path from the authenticated Node to the destination Node (if empty, the authenticated Node itself is the destination Node). Otherwise (for username-password authentication), it is the absolute path to the destination Node. |
count (if ttl is not present) | no | number | The amount of history values (max. 1000). Default is 1 , which means the actual value (instead of history values) is returned. |
from (if ttl is not present) | no | number | If specified, the start timestamp from which to retrieve history values. |
to (if ttl is not present) | no | number | If specified, the end timestamp up to which to retrieve history values. |
ttl (if count is not present) | no | number or null | Time To Live. If this parameter is not present, the function directly returns the current (“cached”) value of the Node. If the parameter is present, a synchronous read is done on the Node in order to read from the underlying device. A value of null means to use the default maximum value age of the Node. Otherwise, the value is the age in milliseconds that the current Node value can have to be returned directly. If the value of the Node is older, it is read synchronously from the device. To force a synchronous read regardless of the node's Max Value Age, specify a value of 0 . |
Example Read Request (using a Token):
{ "tk": "961:oseIqCm8WOOnPEE5g0tt1TZz2wbL/qUq", /* Authentication for "/Nodes/Demo-Nodes/" */ "get": [{ "na": "Temperature", /* Reads Node: "/Nodes/Demo-Nodes/Temperatur" */ }, { "id": 964, /* Reads Node: "/Nodes/Demo-Nodes/Pressure" */ "count": 5 /* Reads the last 5 historical values */ }] }
Example Read Request (using username-password):
{ "username": "demo@user.org", "password": "demo", "get": [{ "na": "/Nodes/Demo-Nodes/Temperature", /* must specify the absolute Node Path here */ }, { "id": 964, /* Reads Node: "/Nodes/Demo-Nodes/Pressure" */ "count": 5 /* Reads the last 5 historical values */ }] }
Mandatory | Type | Purpose | ||||
---|---|---|---|---|---|---|
res | yes | object | Result of the query | |||
id | yes | number | Identifier | |||
na | yes | string | Name | |||
dn | yes | string | Display name | |||
ds | yes | string | Description | |||
lo | yes | string | Location | |||
ty | yes | string | Type | |||
hi | yes | boolean | History Options | |||
min | yes | number | Minimum value | |||
max | yes | number | Maximum value | |||
values | yes | object array | ||||
nodes | no (only browse) | object array | Contains all child Nodes (recursive). For each child the properties are the same as in this table. |
Possible res
results:
Mandatory | Type | Purpose | |
---|---|---|---|
value | yes | number | Result Codes: >= 0: OK - Everything is good! < 0: An error has occured! |
reason | no | string | Reason for the error |
Possible value
results:
Example Read Response:
{ "get": { "nodes": [ { "id": 963, "na": "Temperature", "dn": "Temperature (°C)", "ds": "", "lo": null, "ty": "double", "hi": false, "min": -20, "max": 90, "values": [ { "va": 78, "ts": 1472740618590, "st": 0 } ] }, { "id": 964, "na": "Pressure", "dn": "Pressure", "ds": "", "lo": "", "ty": "double", "hi": true, "min": 10, "max": 110, "values": [ { "va": 86, "ts": 1472740619105, "st": 0 }, { "va": 84, "ts": 1472740617887, "st": 0 }, { "va": 98, "ts": 1472740616967, "st": 0 }, { "va": 32, "ts": 1472740615136, "st": 0 }, { "va": 31, "ts": 1472740612718, "st": 0 } ] } ], "res": { "value": 0 } } }
Mandatory | Type | Purpose | |
---|---|---|---|
id | yes (if na is not specified) | number | Identifier |
na | yes (if id is not specified) | string | Name |
va | yes | any | new value |
ts | No | number | Timestamp |
st | No | number | Status |
Example Write Request (using a Token):
{ "tk": "961:oseIqCm8WOOnPEE5g0tt1TZz2wbL/qUq", /* Authentication for "/Nodes/Demo-Nodes/" */ "set": [ { "na": "Temperature", /* Write Value 21 to Node: "/Nodes/Demo-Nodes/Temperatur" */ "va": 21 }, { "id": 964, /* Write Value 84 with the Timestamp 02.09.16 07:09 */ "va": 84, /* and the Status 0 */ "ts": 1472800198510, /* to Node: "/Nodes/Demo-Nodes/Pressure" */ "st": 0 } ] }
Example Write Request (using username-password):
{ "username": "demo@user.org", "password": "demo", "set": [ { "na": "/Nodes/Demo-Nodes/Temperature", /* Write Value 21 to Node (specified by absolute Node Path) */ "va": 21 }, { "id": 964, /* Write Value 84 with the Timestamp 02.09.16 07:09 */ "va": 84, /* and the Status 0 */ "ts": 1472800198510, /* to Node: "/Nodes/Demo-Nodes/Pressure" */ "st": 0 } ] }
Mandatory | Type | Purpose | |
---|---|---|---|
res | yes | object | Result of the query |
nodes | yes | object array | Contains all child Nodes (recursive). For each child the properties are the same as in this table. |
Possible res
results:
Mandatory | Type | Purpose | |
---|---|---|---|
value | yes | number | Result codes: >= 0: OK - Everything is good! < 0: An error has occured! |
reason | no | string | Reason for the error |
Example Write Response:
{ "set": { "nodes": [], "res": { "value": 0 } } }
Example Write Response (Error Case):
{ "set": { "nodes": [ { "id": 964, "va": 84, "ts": 4728001980, /* 24.02.1970 17:20 */ "st": 0, "res": { "value": -1, "reason": "values[0].Timestamp is lower than 01.01.2000 00:00:00 +00:00" } } ], "res": { "value": -1, "reason": "At least one error occured when processing the nodes: values[0].Timestamp is lower than 01.01.2000 00:00:00 +00:00" } } }
Mandatory | Type | Purpose | |
---|---|---|---|
pid | yes (if pna is not specified) | number | Parent Identifier New Node will be created as a Child of this Node. |
pna | yes | string | Parent Name New Node will be created as a Child of this Node. e.g if pna=“Demo-Nodes” , the new Node will be created in this folder. The new Node will be “/Nodes/Demo-Nodes/Name” |
na | yes (if pid is not specified) | string | Name |
dn | no | string | Display name |
ds | no | string | Description |
lo | no | string | Location |
path | no | string | Path (e.g. for device variables) |
ty | yes | string | Type |
hi | no | number | Hysteresis |
min | no | number | Minimum value |
max | no | number | Maximum value |
Example Create Request:
{ "tk": "938:843uqQeSaLAg+7TALdOhGDkLOHFZevZw", /* Authentication for "/Nodes" */ "create": [{ "pna": "Demo-Nodes", /* Creates Node "/Nodes/Demo-Nodes/New-Node-1" */ "na": "New-Node-1", /* with Type string */ "ty": "string" }, { "pid": 961, /* Creates Node "Nodes/Demo-Nodes/New-Node-2" */ "na": "New-Node-2", /* with specified Displayname (dn), */ "dn": "Display New-Node-2", /* Description (ds) and Type double */ "ds": "This is the new Node 2", "ty": "double" }] }
Mandatory | Type | Purpose | |
---|---|---|---|
res | yes | object | Result of the query |
nodes | yes | object array | Contains all child Nodes (recursive). For each child the properties are the same as in this table. |
Possible res
results:
Mandatory | Type | Purpose | |
---|---|---|---|
value | yes | number | Result Codes: >= 0: OK - Everything is good! < 0: An error has occured! |
reason | no | string | Reason for the error |
Example Create Response:
{ "tk": "938:843uqQeSaLAg+7TALdOhGDkLOHFZevZw", "create": [{ "pna": "Demo-Nodes", "na": "New-Node-1", "ty": "string" }, { "pid": 961, "na": "New-Node-2", "dn": "Display New-Node-2", "ds": "This is the new Node 2", "ty": "double" }] }
Exampe Create Response (Error Case):
{ "create": { "nodes": [ { "pna": "Demo-Nodes", "na": "Existing-Node", "ty": "string", "res": { "value": -1, "reason": "An object with the same name does already exist. Please choose another name." } }, { "pid": 961, "na": "New-Node-2", "dn": "Display New-Node-2", "ds": "This is the new Node 2", "ty": "qwertz", "res": { "value": -1, "reason": "Could not find the Node Type \"qwertz\"." } } ], "res": { "value": -1, "reason": "At least one error occured when processing the nodes: An object with the same name does already exist. Please choose another name." } } }