C Pro API – Documentation

Getting started

This API was developed to enable customized control in the diverse machine control environments. The API provides programmatic access to read state and control the camera system.

Two web-based communication protocols are available. On the one hand, it is possible to set up a stateless connection via the standard HTTP GET or POST request to fetch or set the desired data. On the other hand, an event-driven system can be developed via a WebSocket connection. In this way, the software programmed by the customer can react to changing information that is synchronized in real time.

Http API

The HTTP API is a RESTful API. The control unit of the Rotoclear C Pro represents the server in the local network environment and the program is the client. Communication happens stateless between server and client. This means that the server does not know anything about the last requested data and even if the data is still up to date it will be sent again on request.

This API is ideal for writing a simple and small control program. It is also easy to test. The GET request URL can be entered directly in the browser URL input field, or tested with Postman or curl. All that is needed is an HTTP client and some understanding of the HTTP protocol, URL queries, HTTP headers, and JSON format.

Connection

The HTTP API can be accessed via both web servers on the control unit. The origin of the connection URL is the same under which the web client is accessible in the browser. The path `/api` is appended to this URL origin (see *Connection URL examples*). The respective web server must be switched on in the connection settings. These connection settings also contain the port needed for the HTTP client connection.

> **Note:** For security reasons, the HTTPS connection is always recommended.

Connection URL examples: 
    http://rotoclear.local:80/api
    https://rotoclear.local:443/api
    https://192.168.0.123:3000/api

Response:
    401 Unauthorized

Authentication and Authorization

Furthermore, we need also the API token from the settings. This is configurable after the activation of the API module. The system has an internal permissions system, which can assign different rights for different users. With the activation of the API module, an 'API-User' user is created in addition to the 'admin' user. The token set in the settings reflects the password of the 'API-User'.

Authentication via parameters in the url query:

The user and the password can be set as one parameter in the URL query. In this case, the keywords 'token' and 'password' are mapped to the same field of the user as password. If the user is not passed, the 'API-User' is assumed as default. (example: 'Authentication in URL Query'). This authetification variant has advantages and disadvantages. One disadvantage is that the token is readable in its raw form in the url query. One advantage is that a request can be made simply as URL text, as for example with the GET request by entering the url in browser.

If an http client connects only with this information, then all information authorized for the user is sent as response, since no further information and selection is provided.

Authentication in URL Query: 
    http://rotoclear.local:80/api?user=API-User&token=***
    https://rotoclear.local:443/api?token=***
    https://192.168.0.123:3000/api?password=***

Curl example:
    curl -X GET -G https://rotoclear.local:443/api -d token=***

Response:
    200 Success. 
    With JsonObject as description of the state in body of the response.

Simplified and formatted body example of the response body: 
    {
      "oct0":"69.7°C",
      "oct1":"80.0°C",
      "light0":false,
      "light1":false,
      "hasInternet":true,
      "macAddr":"00:15:5D:7E:D9:46",
      "hostname":"rotoclear",
      "netInfo":[
        {
          "name":"eth0",
          "description":"eth0",
          "macAddress":"00:15:5D:7E:D9:46",
          "gateway":"",
          "isServer":false,
          "dhcp":true,
          "dhcpServers":[],
          "connections":[{
              "address":"172.28.32.226",
              "netmask":"255.255.240.0",
              "broadcast":"172.28.47.255"
          }],
          "dhcpSelected":true,
          "staticIp":"192.168.214.221",
          "staticMask":"255.255.255.0",
          "staticGateway":"192.168.214.1",
          "staticDns":"8.8.8.8",
          "staticUseGateway":false,
          "staticUseDns":false
        }
      ],
      "pan0":{"x":50.31323414252154,"y":49.89594172736733},
      "pan1":{"x":50,"y":50},
      "pip":0,
      "psi0":"1712mbar",
      "psi1":"1008mbar",
      "psiSetpoint":"1150mbar",
      "changeVideoName":"",
      "changeImageName":"",
      "changePostName":"",
      "record":"stop",
      "recordTime":0,
      "rtspPort":1025,
      ...
    }

Authentication via Basic Authentication:

The second authentication variant is Basic Authentication. For this purpose, according to the RFC7617 standard, the 'Authorization' key is specified in the http header. The value of authorization key composes the text "Basic " and the base64 encoded 'username:password'. Further information should be taken from the documentation of the respective http client and used programming language.

Basic Authentication - Curl example:
    curl -X GET -G https://rotoclear.local:443/api \
        -u "API-User:token"

Response:
    200 Success. 
    With JsonObject as description of the state in body of the response.

Http Get method

Now that the connection and the authentication to the API was successful, we can go into some details about the requests. In the request with the http Get method, additional parameters can be added in the URL query. To get only the state of the system, the keyword 'get' can be used to list only the desired system state variables. The description of the state variables can be found at the end of this documentation (see: 'State Description'). All variables allowed to the user can be queried in this way. Unknown or unauthorized state variables are ignored by the API. This means that these values are not listed in the response.

Query selected state variables - URL example:
    https://rotoclear.local:443/api?token=***&get=[light0,record,recordTime,pan0]

Query selected state variables - Curl example:
    curl -X GET -G https://rotoclear.local:443/api \
        -d token=*** \
        -d get=[light0,record,recordTime,pan0]
    
Response:
    {
      "light0": true,
      "record": "stop",
      "recordTime": 0,
      "pan0": {
        "x": 50.26041666666666,
        "y": 50.0
      }
    }

The Get method can also be used to set values in the system state. Please note that complex and nested structure variables cannot be easily mapped in a query, so they will not work with a GET request. To set a variable, simply match its key to the value in the query. Since in the query the variables are written only in the form of text, these variables are converted internally into the respective data types. That means "true" or "false" becomes a JSON boolean, written-out numbers are converted into the respective JSON numbers as Integer or Float number and saturated. In addition, the values are validated and caught in a valid and defined range. After setting the variable, the updated state variables are listed in the response of the request.

Set state variables - URL example:
    https://rotoclear.local:443/api?token=***&light0=true&record=start

Set state variables - Curl example:
    curl -X GET -G https://rotoclear.local:443/api \
        -d token=*** \
        -d light0=true \
        -d record=start

Response:
    {
      "light0": true,
      "record": "stop",
    }
The system could respond with a "record": "stop" if, for example, no storage medium was selected for recording.

Http Post method

There are also some slightly more complex data types in the system state. These include for example network, time, stream pan settings, etc. If you want to set these more complex data types, you can use the http post method. To do this, the settings in JSON format are passed to the request in the body.

Set pan for first camera head - Post Request with a JSON body:
    curl -X POST https://rotoclear.local:443/api \
      -u "API-User:***" \
      -H "Content-Type: application/json" \
      -d '{"pan0": {"x": -10.5, "y": -10}, "zoom0": 20000}'

Response:
      {
        "pan0": {
          "x": 39.5,
          "y": 40.0
        },
        "zoom0": 20000
      }
While the control of the camera heads, i.e. the pan and the zoom 
are calculated relative to the current value, the return value 
of the API is always the absolute value currently set.

For simplicity, values can also be queried via the post method. To do this, the get key must be matched with an array of keys in string form.

Furthermore, it should be mentioned that with one request state getter and setter can be sent at the same time. Usually these are executed in the written order. The same applies to the get requests, where the order of the query parameters is considered.

Query state - Post Request with a JSON body:
    curl -X POST https://rotoclear.local:443/api \
      -u "API-User:***" \
      -H "Content-Type: application/json" \
      -d '{"get": ["light0","record","recordTime","pan0"]}'

Response:
    {
      "light0": true,
      "record": "stop",
      "recordTime": 0,
      "pan0": {
        "x": 50.26041666666666,
        "y": 50.0
      }
    }