HTTP API

Calling the nomos system Controller API over HTTP

Every call of the Socket.io API is also available over HTTP. This suits scripts and systems that send single requests and do not keep a connection open.

Calls

The name of the call is the last part of the address:

POST http://<controller-ip>/api/v1/<function>

The parameters that go into the first argument over Socket.io are sent as JSON in the body:

curl -s -X POST -H "x-nomos-sid: <session-id>" -H "content-type: application/json" \
  -d '{"cid":"C5","property":"state"}' \
  http://<controller-ip>/api/v1/getComponentData

Form data (-d 'cid=C5&property=state') and GET with query parameters (/api/v1/getComponentData?cid=C5&property=state) work as well. The texts true and false then become booleans. The controller answers methods other than GET and POST with status 405.

Which calls exist and which parameters they expect is on apidocs.

Authentication

There are two ways, and every request needs one of them.

User name and password in the headers auth-username and auth-password:

curl -s -X POST -H "auth-username: USERNAME" -H "auth-password: PASSWORD" \
  http://<controller-ip>/api/v1/getVersion

{"api":"0.3.41","ncd":"1.15","engine":"1.2.2"}

Session ID in the header x-nomos-sid. You get the ID once with POST /api/v1/auth:

curl -s -X POST -H "auth-username: USERNAME" -H "auth-password: PASSWORD" \
  -H "auth-persistent: true" http://<controller-ip>/api/v1/auth

{"sessionID":"<session-id>","userID":<user-id>}

curl -s -X POST -H "x-nomos-sid: <session-id>" http://<controller-ip>/api/v1/getVersion

Use the session ID for repeated calls. With user name and password the controller checks the password again on every request and, as long as your client does not keep cookies, creates a new session every time. Without auth-persistent: true a session lasts 24 hours from its last use, with it two years. More under Sessions.

The header accept-language (such as de or en) sets the language of errorText.

logout ends the session:

curl -s -X POST -H "x-nomos-sid: <session-id>" http://<controller-ip>/api/v1/logout

Responses and errors

On success the controller answers with status 200 and, in the body, with what the call returns over Socket.io, such as true, an object or a list.

On failure the body holds errorCode and errorText, and the status shows the kind of error:

Status	Meaning	Example
400	The call was answered with an error.	{"errorCode":106,"errorText":"Parameter(s) error"} when a required parameter is missing; 112 for something that does not exist; 117 when the user may not use the call
401	The login failed.	110 for a wrong password, 106 for an expired or unknown session, 109 during a lockout after failed attempts
405	Method not allowed	{"errorCode":117,"errorText":"Method Not Allowed"} for PUT or DELETE
408	No answer within 15 seconds.	{"errorCode":116,"errorText":"Timeout occurred"}, also for a call that does not exist

Decide in your code by errorCode, not by errorText. The meaning of every error code is on apidocs.

Limits

• No events: Over HTTP the controller does not report changes on its own. To follow values continuously, use Socket.io with the event onComponentUpdate, or MQTT.
• 15 seconds per call: If a call does not answer within 15 seconds, status 408 follows. The call may still have been carried out, a long scene for example.

HTTPS

On port 443 the controller uses a self-signed certificate without a host name. How your program trusts exactly this certificate, and why curl is not enough for that, is under HTTPS and certificate.