The my-devices.net REST API

The reflector server provides a REST API for programmatically querying and modifying device meta information. Using the API you can get a list of devices, search for a device, get and modify device properties, create and delete devices.

Endpoint

The HTTP or HTTPS endpoint for all API requests is api.my-devices.net. We highly recommend using HTTPS, especially if sensitive data like usernames and passwords are transmitted. This is especially true if HTTP Basic Authentication is used.

Authentication

The API supports two authentication mechanisms. The first is HTTP Basic Authentication (over HTTPS), the other one is session-based authentication. For Basic Authentication, the username and password must be supplied in the Authorization header with every HTTP request.

Note: all following examples use username "user" and password "s3cr3t".

Following is an example for a request using Basic Authentication:

GET /my-devices/api/devices HTTP/1.1
Host: api.my-devices.net
Authorization: Basic dXNlcjpzM2NyM3Q=
Connection: Close

The second authentication mechanism is session-based authentication. This uses a session cookie, which must be passed with every request. To obtain a valid session cookie, a Login request must be sent to the server. This is a POST request to the server root ("/"), with the username and password supplied as form-encoded parameters in the request body.

POST / HTTP/1.1
Host: api.my-devices.net
Connection: Close
Content-Length: 42
Content-Type: application/x-www-form-urlencoded

action=login&username=user&password=s3cr3t

The following parameters must be given:

action: This must always have the value login.
username: The name of the user.
password: The user's password.

Additionally, the following optional parameters can be passed:

onsuccess: The URI of a page to redirect to if the login was successful. If this is given and authentication was successful, the response will have a 303 See Other status with a Location header containing the URI given here.
onfailure: Similar to onsuccess, the URI given here will be used if authentication failed.

If onsuccess and onfailure are not given, the response status will be 200 OK if authentication succeeded, or 401 Unauthorized if authentication failed.

If authentication was successful, the response will include a Set-Cookie header containing the session cookie. This session cookie must be passed in with all API requests.

HTTP/1.1 200 OK
Connection: Close
Content-Length: 0
Date: Thu, 01 Mar 2012 10:35:30 GMT
Set-Cookie: osp.web.session.my-devices=000000075EA788B0; 
    domain=.my-devices.net; 
    path=/; 
    expires=Thu, 01 Mar 2012 12:35:30 GMT

Here is an example for using the session cookie in a REST request:

GET /my-devices/api/devices HTTP/1.1
Host: api.my-devices.net
Cookie: osp.web.session.my-devices=000000075EA788B0
Connection: Close

Accessing Device Web Servers

The device web server of any device that is connected to the reflector server can be reached under the address <id>.my-devices.net, where <id> is the UUID identifying the device.

To access the device, a valid session cookie is required. Alternatively, HTTP Basic Authentication can be used to provide authentication info. However, as to not conflict with possible authentication required by the device itself, the authentication information is not passed via the Authorization header, but via the X-PTTH-Authorization header instead.

Example:

GET / HTTP/1.1
Host: a2359c27-cb1f-4692-8490-22d412ac87ba.my-devices.net
X-PTTH-Authorization: Basic dXNlcjpzM2NyM3Q=

This is a very useful feature for programmatically "pushing" data to devices, using a POST or PUT request to the device's web server.

Browsing Devices

For browsing all available devices, send a GET request to /my-devices/api/devices. Optionally, parameters can be supplied to filter or limit the result.

To get a list of all devices, that are online, send the following request:

GET /my-devices/api/devices HTTP/1.1
Host: api.my-devices.net
Authorization: Basic dXNlcjpzM2NyM3Q=
Connection: Close

The response will contain a JSON array of objects holding device properties (id, domain, name, online, etc.) in the body:

HTTP/1.1 200 OK
Cache-Control: no-cache
Connection: Close
Content-Type: application/json
Date: Thu, 01 Mar 2012 11:25:31 GMT
Transfer-Encoding: chunked

[
    {
        "name": "Axis Network Camera",
        "geolocation": "46.528760, 14.099177",
        "port": "0",
        "lastConnect": "2012-03-01T11:25:02Z",
        "id": "0a72da53-9de5-44c8-9adf-0090e80e20a7",
        "host": "80.122.195.86",
        "online": true,
        "domain": "e3efbb09-f384-4c00-8e7a-e18b8e93c362",
        "description": "Network camera via Reverse HTTP Proxy"
    },
    {
        "name": "Web HMI Demo",
        "geolocation": " 46.528760, 14.099177",
        "port": "0",
        "lastConnect": "2012-03-01T11:25:26Z",
        "id": "33a9c5a3-81d8-4d3a-8068-1c910b3c61f6",
        "host": "188.22.62.220",
        "online": true,
        "domain": "e3efbb09-f384-4c00-8e7a-e18b8e93c362",
        "description": "Industrial HMI built with web technologies",
        "hardware": "Digi ConnectCore 9C"
    },
    {
        "name": "iWeatherStation",
        "geolocation": "46.528760, 14.099177",
        "port": "0",
        "lastConnect": "2012-03-01T11:25:15Z",
        "id": "a2359c27-cb1f-4692-8490-22d412ac87ba",
        "host": "80.122.195.86",
        "online": true,
        "domain": "e3efbb09-f384-4c00-8e7a-e18b8e93c362",
        "description": "Internet-based weather station device",
        "hardware": "SSV DNP/9200"
    }
]

Note: in order to improve readability, the chunk sizes have been stripped from the responses shown in this document.

The following parameters can be added:

query: Specify a whitespace-separated list of keywords to only return devices matching these keywords. If any of the keywords are found in the name, description or tags properties of the device, then the device will be included in the result.
fromIndex: A zero-based index of the first desired result. This is used for paging output, along with maxResults.
maxResults: Maximum number of results for paged output. Usually used together with fromIndex.
status: Only include devices with the given online status. Valid values are online, offline and all.

Example: Browse for all devices containing the keyword "axis" in their name, description or tags:

GET /my-devices/api/devices?query=axis HTTP/1.1
Host: api.my-devices.net
Authorization: Basic dXNlcjpzM2NyM3Q=
Connection: Close

Server Response:

HTTP/1.1 200 OK
Cache-Control: no-cache
Connection: Close
Content-Type: application/json
Date: Thu, 01 Mar 2012 11:19:21 GMT
Transfer-Encoding: chunked

[
    {
        "name": "Axis Network Camera",
        "geolocation": "46.528760, 14.099177",
        "port": "0",
        "lastConnect": "2012-03-01T11:19:07Z",
        "id": "0a72da53-9de5-44c8-9adf-0090e80e20a7",
        "host": "80.122.195.86",
        "online": true,
        "domain": "e3efbb09-f384-4c00-8e7a-e18b8e93c362",
        "description": "Network camera via Reverse HTTP Proxy"
    }
]

Example: paged results:

GET /my-devices/api/devices?firstIndex=1&maxResults=10 HTTP/1.1
Host: api.my-devices.net
Authorization: Basic dXNlcjpzM2NyM3Q=
Connection: Close

Getting Properties of a Specific Device

To return all device properties for a device identified by its UUID, issue a GET request to /my-devices/api/device/<id>, where <id> is replaced with the device UUID.

Example:

GET /my-devices/api/device/0a72da53-9de5-44c8-9adf-0090e80e20a7 HTTP/1.1
Host: api.my-devices.net
Authorization: Basic dXNlcjpzM2NyM3Q=
Connection: Close

Server Response:

HTTP/1.1 200 OK
Cache-Control: no-cache
Connection: Close
Content-Type: application/json
Date: Thu, 01 Mar 2012 11:36:32 GMT
Transfer-Encoding: chunked

{
    "name": "Axis Network Camera",
    "geolocation": "46.528760, 14.099177",
    "port": "0",
    "lastConnect": "2012-03-01T11:35:59Z",
    "id": "0a72da53-9de5-44c8-9adf-0090e80e20a7",
    "host": "80.122.195.86",
    "online": true,
    "domain": "e3efbb09-f384-4c00-8e7a-e18b8e93c362",
    "description": "Network camera via Reverse HTTP Proxy"
}

It is also possible to only return a specific property. To do this, the name of the property must be added to the request URI:

GET /my-devices/api/device/0a72da53-9de5-44c8-9adf-0090e80e20a7/name HTTP/1.1
Host: api.my-devices.net
Authorization: Basic dXNlcjpzM2NyM3Q=
Connection: Close

Server Response:

HTTP/1.1 200 OK
Cache-Control: no-cache
Connection: Close
Content-Type: application/json
Date: Thu, 01 Mar 2012 11:36:32 GMT
Transfer-Encoding: chunked

{
    "name": "Axis Network Camera"
}

Setting Properties of a Specific Device

The properties of a device can be modified, and new properties can be added. This is done with a PUT request to /my-devices/api/device/<id>, where <id> is replaced with the device UUID.

The new property values are given through a JSON document in the request body.

Example:

PUT /my-devices/api/device/0a72da53-9de5-44c8-9adf-0090e80e20a7 HTTP/1.1
Host: api.my-devices.net
Authorization: Basic dXNlcjpzM2NyM3Q=
Connection: Close
Content-Type: application/json
Content-Length: 38

{
    "name": "Axis Network Camera"
}

Server Response:

HTTP/1.1 200 OK
Connection: Close
Content-Length: 0
Date: Thu, 01 Mar 2012 11:38:24 GMT

Note: System properties (id, domain, online, lastConnect, host and port) cannot be modified.

Deleting a Device Property

A device property can be deleted with a DELETE request to /my-devices/api/device/<id>/<prop>, where <id> is replaced with the device UUID and <prop> is replaced with the property name.

Example:

DELETE /my-devices/api/device/0a72da53-9de5-44c8-9adf-0090e80e20a7/tags HTTP/1.1
Host: api.my-devices.net
Authorization: Basic dXNlcjpzM2NyM3Q=
Connection: Close
Content-Length: 0

Server Response:

HTTP/1.1 200 OK
Connection: Close
Content-Length: 0
Date: Thu, 01 Mar 2012 11:44:32 GMT

Deleting a Device

A device can be deleted with a DELETE request to /my-devices/api/device/<id>, where <id> is replaced with the device UUID.

Deleting a device is normally only allowed if the device is offline. However, by adding the X-PTTH-Force: disconnect header to the request, the device will be disconnected before being deleted.

Example:

DELETE /my-devices/api/device/0a72da53-9de5-44c8-9adf-0090e80e20a7 HTTP/1.1
Host: api.my-devices.net
Authorization: Basic dXNlcjpzM2NyM3Q=
Connection: Close
Content-Length: 0

Server Response:

HTTP/1.1 200 OK
Connection: Close
Content-Length: 0
Date: Thu, 01 Mar 2012 11:44:32 GMT

Creating a Device

A device can be created with a POST request to /my-devices/api/device/<id>, where <id> is replaced with the device UUID of the new device.

The new device properties must be passed as JSON object in the request body. The properties must at least include domain and name. The id property must not be included. The id and online properties will be set automatically.

Example:

POST /my-devices/api/device/0a72da53-9de5-44c8-9adf-0090e80e20a7 HTTP/1.1
Host: api.my-devices.net
Authorization: Basic dXNlcjpzM2NyM3Q=
Connection: Close
Content-Length: 195

{
    "name": "Axis Network Camera",
    "geolocation": "46.528760, 14.099177",
    "domain": "e3efbb09-f384-4c00-8e7a-e18b8e93c362",
    "description": "Network camera via Reverse HTTP Proxy"
}

Server Response:

HTTP/1.1 200 OK
Connection: Close
Content-Length: 0
Date: Thu, 01 Mar 2012 11:44:32 GMT

Creating or Updating a Device

POST can also be used to update an existing device's properties. For this to work, a X-PTTH-If-Exists: update header must be included in the request.

If this header is included, and the device with the given ID already exists, it's properties will be updated. If the device does not exist, it will be created.

Example:

POST /my-devices/api/device/0a72da53-9de5-44c8-9adf-0090e80e20a7 HTTP/1.1
Host: api.my-devices.net
Authorization: Basic dXNlcjpzM2NyM3Q=
Connection: Close
Content-Length: 195
X-PTTH-If-Exists: update

{
    "name": "Axis Network Camera",
    "geolocation": "46.528760, 14.099177",
    "domain": "e3efbb09-f384-4c00-8e7a-e18b8e93c362",
    "description": "Network camera via Reverse HTTP Proxy"
}

Server Response:

HTTP/1.1 200 OK
Connection: Close
Content-Length: 0
Date: Thu, 01 Mar 2012 11:44:32 GMT

HTTP Method Override (Firewall)

If your firewall does not allow HTTP PUT or HTTP DELETE requests, you can send a POST request and add the X-HTTP-Method-Override header to specify the actual method to use. Please note that method names are case sensitive. Example:

POST /my-devices/api/device/0a72da53-9de5-44c8-9adf-0090e80e20a7 HTTP/1.1
Host: api.my-devices.net
Authorization: Basic dXNlcjpzM2NyM3Q=
X-HTTP-Method-Override: DELETE
Connection: Close
Content-Length: 0

Server Response:

HTTP/1.1 200 OK
Connection: Close
Content-Length: 0
Date: Thu, 01 Mar 2012 11:44:32 GMT

Error Handling

The following conventions are used by the API for reporting errors:

A successful action will always result in a 200 OK response.
If a device or property does not exist, a 404 Not Found response is returned.
An attempt to create a device that already exists results in a 409 Conflict response.
If no authentication information or bad credentials are provided, a 401 Unauthorized response is returned.
An incorrect HTTP method results in a 405 Method Not Allowed response.
If the URI is malformed, a 400 Bad Request response is returned.
If the server encounters an error during processing the request, a 500 Internal Server Error response is returned.

cURL Example

The well-known cURL utility can be used to test the API.

Example: get a list of all devices:

curl -uuser:s3cr3t https://api.my-devices.net/my-devices/api/devices?status=all

Overview
Endpoint
Authentication
Accessing Device Web Servers
Browsing Devices
Getting Properties of a Specific Device
Setting Properties of a Specific Device
Deleting a Device Property
Deleting a Device
Creating a Device
Creating or Updating a Device
HTTP Method Override (Firewall)
Error Handling
cURL Example

my-devices.net		Related Links
Home	Log In	Applied Informatics
Get Started	Status	POCO C++ Libraries
Learn More	API Docs
Solutions & Services	Downloads
Contact Us

API Documentation

The my-devices.net REST API

Endpoint

Authentication

Accessing Device Web Servers

Browsing Devices

Getting Properties of a Specific Device

Setting Properties of a Specific Device

Deleting a Device Property

Deleting a Device

Creating a Device

Creating or Updating a Device

HTTP Method Override (Firewall)

Error Handling

cURL Example

Table of Contents