REST-API adapter

This adapter uses Sentry libraries to automatically report exceptions and code errors to the developers. For more details and for information how to disable the error reporting see Sentry-Plugin Documentation! Sentry reporting is used starting with js-controller 3.0.

This is a RESTFul interface to read the objects and states from ioBroker and to write/control the states over HTTP Get/Post requests.

The purpose of this adapter is similar to simple-api. But this adapter supports long-polling and URL hooks for subscribes.

It has a beneficial web interface to play with the requests:

Usage

Call in browser http://ipaddress:8093/ and use Swagger UI to request and modify the states and objects.

Some request examples:

http://ipaddress:8093/v1/state/system.adapter.rest-api.0.memHeapTotal - read state as JSON
http://ipaddress:8093/v1/state/system.adapter.rest-api.0.memHeapTotal/plain - read state as string (only value)
http://ipaddress:8093/v1/state/system.adapter.rest-api.0.memHeapTotal?value=5 - write state with GET (only for back compatibility with simple-api)
http://ipaddress:8093/v1/sendto/javascript.0?message=toScript&data={"message":"MESSAGE","data":"FROM REST-API"} - send a message to javascript.0 in script scriptName

Subscribe to the state's or object's changes

Your application could get notifications by every change of the state or object.

For that, your application must provide an HTTP(S) end-point to accept the updates.

Example in node.js see here demoNodeClient.js

Long polling

This adapter supports a subscribing on data changes via long polling.

Example for browser could be found here: demoNodeClient.js

Web extension

This adapter can run as a web extension. In this case, the path is available under http://iipaddress:8082/rest

Notice

POST is always for creating a resource (does not matter if it was duplicated)
PUT is for checking if resource exists then update, else create new resource
PATCH is always for updating a resource

Commands

Additionally, you can execute many socket commands via special interface:

http://ipaddress:8093/v1/command/<commandName>?arg1=Value2&arg2=Value2

E.g.

http://ipaddress:8093/v1/command/getState?id=system.adapter.admin.0.alive - to read the state of system.adapter.admin.0.alive
http://ipaddress:8093/v1/command/readFile?adapter=admin.admin&fileName=admin.png - to read the file admin.admin/admin.png as JSON result
http://ipaddress:8093/v1/command/readFile?adapter=admin.admin&fileName=admin.png?binary - to read the file admin.admin/admin.png as file
http://ipaddress:8093/v1/command/extendObject?id=system.adapter.admin.0?obj={"common":{"enabled":true}} - to restart admin

You can request all commands with POST method too. As body must be an object with parameters. E.g.:

curl --location --request POST 'http://ipaddress:8093/v1/command/sendTo' \
--header 'Content-Type: application/json' \
--data-raw '{
"adapterInstance": "history.0",
"command": "getHistory",
"message": {"id": "system.adapter.admin.0.memRss","options": {"aggregate": "onchange", "addId": true}}
}'

You cannot send POST request to commands via GUI.

States

getStates(pattern) - get the list of states for pattern (e.g. for system.adapter.admin.0.*). GUI can have problems by visualization of answer.
getForeignStates(pattern) - same as getStates
getState(id) - get state value by ID
setState(id, state) - set state value with JSON object (e.g. {"val": 1, "ack": true})
getBinaryState(id) - get binary state by ID
setBinaryState(id, base64) - set binary state by ID

Objects

getObject(id) - get object by ID
getObjects(list) - get all states and rooms. GUI can have problems by visualization of answer.
getObjectView(design, search, params) - get specific objects, e.g. design=system, search=state, params={"startkey": "system.adapter.admin.", "endkey": "system.adapter.admin.\u9999"}
setObject(id, obj) - set object with JSON object (e.g. {"common": {"type": "boolean"}, "native": {}, "type": "state"})
delObject(id, options) - delete object by ID

Files

readFile(adapter, fileName) - read file, e.g. adapter=vis.0, fileName=main/vis-views.json. Additionally, you can set option in query binary=true to get answer as file and not as json
readFile64(adapter, fileName) - read file as base64 string, e.g. adapter=vis.0, fileName=main/vis-views.json. Additionally, you can set option in query binary=true to get answer as file and not as json
writeFile64(adapter, fileName, data64, options) - write file, e.g. adapter=vis.0, fileName=main/vis-test.json, data64=eyJhIjogMX0=
unlink(adapter, name) - delete file or folder
deleteFile(adapter, name) - delete file
deleteFolder(adapter, name) - delete folder
renameFile(adapter, oldName, newName) - rename file
rename(adapter, oldName, newName) - rename file or folder
mkdir(adapter, dirName) - create folder
readDir(adapter, dirName, options) - read content of folder
chmodFile(adapter, fileName, options) - change file mode. E.g. adapter=vis.0, fileName=main/*, options = {"mode": 0x644}
chownFile(adapter, fileName, options) - change file owner. E.g. adapter=vis.0, fileName=main/*, options = {"owner": "newOwner", "ownerGroup": "newgroup"}
fileExists(adapter, fileName) - check if file exists

Admins

getHostByIp(ip) - read host information by IP. e.g. by localhost
readLogs(host) - read file name and size of log files. You can read them with http://ipaddress:8093/
delState(id) - delete state and object. Same as delObject
getRatings(update) - read adapter ratings (as in admin)
getCurrentInstance() - read adapter namespace (always rest-api.0)
decrypt(encryptedText) - decrypt string with system secret
encrypt(plainText) - encrypt string with system secret
getAdapters(adapterName) - get objects of type "adapter". You can define optionally adapterName
updateLicenses(login, password) - read licenses from ioBroker.net portal
getCompactInstances() - read list of instances with short information
getCompactAdapters() - read list of installed adapters with short information
getCompactInstalled(host) - read short information about installed adapters
getCompactSystemConfig() - read short system config
getCompactSystemRepositories()
getCompactRepository(host) - read short repository
getCompactHosts() - get short information about hosts
addUser(user, pass) - add new user
delUser(user) - delete user
addGroup(group, desc, acl) - create new group
delGroup(group) - delete group
changePassword(user, pass) - change user password
getAllObjects() - read all objects as list. GUI can have problems by visualization of answer.
extendObject(id, obj) - modify object by ID with JSON. (.e.g. {"common":{"enabled": true}})
getForeignObjects(pattern, type) - same as getObjects
delObjects(id, options) - delete objects by pattern

Others

log(text, level[info]) - no answer - add log entry to ioBroker log
checkFeatureSupported(feature) - check if feature is supported by js-controller.
getHistory(id, options) - read history. See for options: https://github.com/ioBroker/ioBroker.history/blob/master/docs/en/README.md#access-values-from-javascript-adapter
httpGet(url) - read URL from server. You can set binary=true to get answer as file
sendTo(adapterInstance, command, message) - send command to instance. E.g. adapterInstance=history.0, command=getHistory, message={"id": "system.adapter.admin.0.memRss","options": {"aggregate": "onchange", "addId": true}}
listPermissions() - read static information with function permissions
getUserPermissions() - read object with user permissions
getVersion() - read adapter name and version
getAdapterName() - read adapter name (always rest-api)
clientSubscribe(targetInstance, messageType, data)
getAdapterInstances(adapterName) - get objects of type "instance". You can define optionally adapterName

Changelog

2.0.3 (2024-07-13)

(jkuenemund) Changed response for the endpoint get states to the dictionary in swagger

2.0.1 (2024-05-23)

(foxriver76) ported to @iobroker/webserver
(theshengfui) Fixed history requests
(bluefox) Minimum required node.js version is 16

1.1.0 (2023-05-03)

(bluefox) Converting of the setState values to the according type
(bluefox) Implemented file operations

1.0.5 (2023-03-27)

(Apollon77) Prepare for future js-controller versions

1.0.4 (2022-08-31)

(bluefox) Check if the port is occupied only on defined interface

1.0.2 (2022-07-27)

(bluefox) Implemented binary read/write operations

1.0.1 (2022-07-27)

(bluefox) Increased the max size of body to 100Mb

1.0.0 (2022-05-19)

(bluefox) Final release

0.6.0 (2022-05-18)

(bluefox) Added sendTo path

0.5.0 (2022-05-17)

(bluefox) Some access errors were corrected

0.4.0 (2022-04-26)

(bluefox) Added socket commands

0.3.6 (2022-04-22)

(bluefox) Added object creation and enumerations reading

0.3.5 (2022-04-22)

(bluefox) Allowed the reading of current subscriptions

0.3.4 (2022-04-20)

(bluefox) Corrected subscription

0.3.1 (2022-04-15)

(bluefox) First release

0.1.0 (2017-09-14)

(bluefox) initial commit

License

Apache 2.0

ioBroker/ioBroker.rest-api