Web server API

The device exposes a REST API (endpoint /api/). The API can be used to programmatically interface with the device web server.

The device storage is navigated by adding the device path to the endpoint /api/<DEVICE_STORAGE_PATH>/.

Note

The device only supports one concurrent connection, and automatically closes the socket after each request, regardless of the client wishes to keep the socket open (using HTTP headers). To avoid errors, it can be necessary to include small delays between API calls.

The Python module canedge_http provides helper functions making it easy to e.g. list, download and delete files through the API from Python. See https://github.com/CSS-Electronics/canedge_http for more information.

In the following, the API is demonstrated using the cURL command-line tool. The examples assume that the device is assigned IP 192.168.1.100. cURL supports basic digest authentication (if enabled in the device configuration) as demonstrated below:

$ curl --user user:<password> --digest http://192.168.1.100/api/

Device ID

The HTTP HEAD verb can be used to retrieve the device-ID. The device ID is returned in the Device-id header field.

$ curl --head http://192.168.1.100/api/
HTTP/1.1 200 OK
Content-type: text/plain
Cache-Control: no-cache
Connection: close
Device-id: AABBCCDD

Check permission

The HTTP OPTIONS verb can be used to check permissions.

When permission is configured to Read only:

$ curl -i -X OPTIONS http://192.168.1.100/api/
HTTP/1.1 200 OK
Content-type: text/plain
Cache-Control: no-cache
Connection: close
Device-id: AABBCCDD
Allow: OPTIONS, GET, HEAD

When permission is configured to Read, write and execute:

$ curl -i -X OPTIONS http://192.168.1.100/api/
HTTP/1.1 200 OK
Content-type: text/plain
Cache-Control: no-cache
Connection: close
Device-id: AABBCCDD
Allow: OPTIONS, GET, HEAD, PUT, DELETE

Check path

The HTTP HEAD verb can be used to check if a path (<DEVICE_STORAGE_PATH>) exists:

  • HTTP 200: Path does exist

  • HTTP 404: Path does not exist

Check if path /device.json exists
$ curl --head http://192.168.1.100/api/device.json
HTTP/1.1 200 OK
Content-type: text/plain
Cache-Control: no-cache
Connection: close
Device-id: AABBCCDD
Content-length: 598
Check if path /non-existing-file.json exists
$ curl --head http://192.168.1.100/api/non-existing-file.json
HTTP/1.1 404 Not Found
Content-type: text/plain
Cache-Control: no-cache
Connection: close
Device-id: AABBCCDD
Content-length: 0

List content

The HTTP GET verb can be used to list content of a path to a directory (<DEVICE_STORAGE_PATH>)

List files stored in /
$ curl http://192.168.1.100/api/
{
  "path": "/",
  "files": [
    {
      "name": "LOG",
      "lastWritten": 1720083840,
      "size": 0,
      "isDirectory": 1
    },
    {
      "name": "config-01.02.json",
      "lastWritten": 1720083802,
      "size": 5856,
      "isDirectory": 0
    },
    {
      "name": "schema-01.02.json",
      "lastWritten": 1720001536,
      "size": 40844,
      "isDirectory": 0
    },
    {
      "name": "device.json",
      "lastWritten": 1720157648,
      "size": 598,
      "isDirectory": 0
    }
  ]
}

In above response, the entry with name LOG is a directory. The content of the LOG directory can be listed with:

List files stored in /log/
$ curl http://192.168.1.100/api/log
{
  "path": "/log/",
  "files": [
    {
      "name": "AABBCCDD",
      "lastWritten": 1720083840,
      "size": 0,
      "isDirectory": 1
    }
  ]
}

Download content

The HTTP GET verb can be used to download a file from a path (<DEVICE_STORAGE_PATH>)

Display json (text) file stored in /device.json
$ curl http://192.168.1.100/api/device.json
{
  "id": "AABBCCDD",
  "type": "0000001F",
  ...
}
Download MF4 (binary) file stored in /log/aabbccdd/00000001/00000001.mf4 using remote-name.
$ curl --remote-name http://192.168.1.100/api/log/aabbccdd/00000001/00000001.mf4
__% Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100  1024  100  1024    0     0  10612      0 --:--:-- --:--:-- --:--:-- 10666

Upload content

The HTTP PUT verb can be used to upload a file to a path (<DEVICE_STORAGE_PATH>)

Note

Requires Read, write and execute permission

Upload new configuration file (config-01.02.json) to device
$ curl -i --upload-file config-01.02.json http://192.168.1.100/api/
HTTP/1.1 200 OK
Cache-Control: no-cache
Connection: close

Note

Uploading a configuration file triggers a device reboot

The following error is returned if the permission setting does not allow upload (PUT).

Upload not allowed
$ curl -i --upload-file config-01.02.json http://192.168.1.100/api/
HTTP/1.1 405 Method Not Allowed
Connection: close
Allow: OPTIONS, GET, HEAD

Delete content

The HTTP DELETE verb can be used to delete a file at a path (<DEVICE_STORAGE_PATH>)

Note

Requires Read, write and execute permission

Delete log file (log/aabbccdd/00000001/00000001.mf4) stored on device
$ curl -i -X DELETE http://192.168.1.100/api/log/aabbccdd/00000001/00000001.mf4
HTTP/1.1 200 OK
Cache-Control: no-cache
Connection: close

The following error is returned if the permission setting does not allow delete.

Delete not allowed
$ curl -i -X DELETE http://192.168.1.100/api/log/aabbccdd/00000001/00000001.mf4
HTTP/1.1 405 Method Not Allowed
Connection: close
Allow: OPTIONS, GET, HEAD