| layout | title | active | sidebar |
|---|---|---|---|
default |
The Dog Gateway - Rest API |
Develop |
rest-api-sidebar.html |
The Dog REST API allows developers to easily integrate home and building automation into their applications, be they web applications, smartphone (Android, iOS, etc.) apps or computer programs.
APIs allow to:
- manage connected devices
- query the gateway about installed devices, their location, functionalities and configurations;
- require execution of commands to existing devices;
- monitor device statuses and measures in real-time;
- add or update the set of devices controlled through the gateway;
- update the location and the description of a device controlled through the gateway;
- manage information about the environment
- insert, update or delete rooms;
- insert, update or delete flats;
- manage rules and automation scenarios
- insert, update, or delete automation rules;
- insert, update, or delete scenarios;
- monitor the home/building performance
- historical information on consumptions;
- historical information on activations;
- related statistics;
- manage Dog
- manage system performance;
- manage system updates;
- troubleshoot problems.
API access is currently available over HTTP, at:
http://<dog-address>/api/v1.
To select the desired response type (JSON or XML), the Accept HTTP header must be used in the request.
In the same way, a proper Content-Type must be always present for PUT and POST requests.
|:----|:----| |Resource /devices | Represents domotic devices handled by Dog and "controllable" by applications using this API. | |Resource /devices/{device-id} | Represents a single domotic device handled by Dog, identified by a unique device-id (currently encoded in the id attribute for the XML response to the GET /devices request), and "controllable" by applications using this API. | |Resource /devices/{device-id}/location | Update the location of a single domotic device handled by Dog, identified by a unique device-id. | |Resource /devices/{device-id}/description | Update the description (i.e., the long name) of a single domotic device handled by Dog, identified by a unique device-id. | |Resource /devices/status | Represents the status of devices registered in the Dog gateway runtime, i.e., defined in the Dog configuration and successfully registered within the gateway runtime.| |Resource /devices/{device-id}/status | Represents the status of the device identified by the given device-id, registered in the Dog gateway runtime, i.e., defined in the Dog configuration and successfully registered within the gateway runtime. | |Resource /devices/{device-id}/commands/{command-name} |Represents a command, identified by a command-name, to be sent to the device identified by the given device-id. Commands are idempotent: the same command always results in the same behavior of the selected device. If the command brings the device in same state in which the device is, no differences will be appreciable.| |Resource /dog/configuration | Unsupported, to be implemented in future... | |Resource /environment | Represents the environment (i.e., the building) configured in Dog.| |Resource /environment/flats | Represents all the flats present in the environment (i.e., the building).| |Resource /environment/flats/{flat-id} | Represents a specific flat present in the environment (i.e., the building).| |Resource /environment/flats/{flat-id}/rooms | Represents all the rooms present in a given flat.| |Resource /environment/flats/{flat-id}/rooms/{room-id} | Represents a specific room present in a given flat in the environment (i.e., the building).| |Resource /rules/ | Represents the rules registered in Dog. By using this resource, it is possible to get all the existing rules or add a new rule.| |Resource /rules/{rule-id} | Represents a single rule registered in Dog. By using this resource, it is possible to update or delete an existing rule.|
Updated on Mon, 2014-01-22 API version 1.0
|----------------|------------------| |Authentication |None| |Response Format|json or xml| |HTTP Methods|GET| |Resource family|device| |Response Object|Array [ Device ]| |API Version|v1.0|
Represents domotic devices handled by Dog and "controllable" by applications using this API.
URL: /devices
| Method | Description |
|---|---|
| GET | List all devices (with their details) used by the Dog gateway |
Example Request
GET http://www.mydog.com/api/v1/devices
{% include accordion-header.html %} {% include open-accordion-item.html panelTitle='Example Response (JSON)' panelCount='1' %}
{% include restapi/get-configuration-response.json %}
{% include close-accordion-item.html %} {% include open-accordion-item.html panelTitle='Example Response (XML)' panelCount='2' %}
{% capture xml %}
{% include restapi/get-configuration-response.xml %}
{% endcapture %}
{{ xml | escape }}
{% include close-accordion-item.html %} {% include accordion-footer.html %}
Updated on Thu, 2014-01-22 API version 1.0
|----------------|------------------| |Authentication |None| |Response Format|json or xml| |HTTP Methods|GET| |Resource family|device| |Response Object|Device| |API Version|v1.0|
Represents a single domotic device handled by Dog, identified by a unique device-id (currently encoded in the id attribute for the XML response to the GET /devices request), and "controllable" by applications using this API.
URL: /devices/{device-id}
| Method | Description |
|---|---|
| GET | Returns the details of the device identified by the given device-id |
GET: Example
GET http://www.mydog.com/api/v1/devices/Lamp_Holder
{% include accordion-header.html %} {% include open-accordion-item.html panelTitle='Example Response (JSON)' panelCount='3' %}
{% include restapi/get-configuration-single-device.json %}
{% include close-accordion-item.html %} {% include open-accordion-item.html panelTitle='Example Response (XML)' panelCount='4' %}
{% capture xml %}
{% include restapi/get-configuration-single-device.xml %}
{% endcapture %}
{{ xml | escape }}
{% include close-accordion-item.html %} {% include accordion-footer.html %}
Updated on Thu, 2013-11-11 API version 1.0
|----------------|------------------| |Authentication |None| |Response Format|json| |HTTP Methods|PUT| |Resource family|device| |Response Object|String| |API Version|v1.0|
Updates the location of a single domotic device handled by Dog, identified by a unique device-id.
URL: /devices/{device-id}/location
| Method | Description |
|---|---|
| PUT | Update the location of the device identified by the given device-id |
PUT: Example
PUT http://www.mydog.com/api/v1/devices/Lamp_Holder/location
{% include accordion-header.html %} {% include open-accordion-item.html panelTitle='Request Body' panelCount='5' %}
{% include restapi/put-location-single-device.json %}
{% include close-accordion-item.html %} {% include accordion-footer.html %}
Updated on Thu, 2013-11-11 API version 1.0
|----------------|------------------| |Authentication |Requires app key| |Response Format|json| |HTTP Methods|PUT| |Resource family|device| |Response Object|String| |API Version|v1.0|
Updates the description (i.e., the long name) of a single domotic device handled by Dog, identified by a unique device-id.
URL: /devices/{device-id}/description
| Method | Description |
|---|---|
| PUT | Update the description (i.e., the long name) of the device identified by the given device-id |
PUT: Example
PUT http://www.mydog.com/api/v1/devices/Lamp_Holder/description
{% include accordion-header.html %} {% include open-accordion-item.html panelTitle='Request Body' panelCount='6' %}
{% include restapi/put-description-single-device.json %}
{% include close-accordion-item.html %} {% include accordion-footer.html %}
Updated on Mon, 2014-01-22 API version 1.0
|----------------|------------------| |Authentication |None| |Response Format|json| |HTTP Methods|GET| |Resource family|status| |Response Object|Array [ DeviceState ]| |API Version|v1.0|
Represents the status of devices registered in the Dog gateway runtime, i.e., defined in the Dog configuration and successfully registered within the gateway runtime.
URL: /devices/status
| Method | Description |
|---|---|
| GET | List the current status of all devices actually managed by the Dog gateway, i.e. defined in the Dog configuration and registered within the gateway runtime, be they active or not |
Example Request
GET http://www.mydog.com/api/v1/devices/status
{% include accordion-header.html %} {% include open-accordion-item.html panelTitle='Example Response (JSON)' panelCount='7' %}
{% include restapi/get-all-device-status.json %}
{% include close-accordion-item.html %} {% include open-accordion-item.html panelTitle='Example Response (XML)' panelCount='8' %}
{% capture xml %}
{% include restapi/get-all-device-status.xml %}
{% endcapture %}
{{ xml | escape }}
{% include close-accordion-item.html %} {% include accordion-footer.html %}
Updated on Thu, 2014-01-22 API version 1.0
|----------------|------------------| |Authentication |None| |Response Format|json| |HTTP Methods|GET| |Resource family|status| |Response Object|DeviceState| |API Version|v1.0|
Represents the status of the device identified by the given device-id and registered in the Dog gateway runtime, i.e., defined in the Dog configuration and successfully registered within the gateway runtime.
URL: /devices/{device-id}/status
| Method | Description |
|---|---|
| GET | List the current status of the device identified by the given device-id and actually managed by the Dog gateway, i.e. defined in the Dog configuration and registered within the gateway runtime, be they active or not |
Example Request
GET http://www.mydog.com/api/v1/devices/MeteringPowerOutlet/status
{% include accordion-header.html %} {% include open-accordion-item.html panelTitle='Example Response (JSON)' panelCount='9' %}
{% include restapi/get-single-device-status.json %}
{% include close-accordion-item.html %} {% include open-accordion-item.html panelTitle='Example Response (XML)' panelCount='10' %}
{% capture xml %}
{% include restapi/get-single-device-status.xml %}
{% endcapture %}
{{ xml | escape }}
{% include close-accordion-item.html %} {% include accordion-footer.html %}
Updated on Fri, 2014-05-06 API version 1.0
|----------------|------------------| |Authentication |None| |Response Format|json| |HTTP Methods|PUT or POST| |Resource family|device| |Response Object|none| |API Version|v1.0|
Represents a command, identified by a command-name, to be sent to the device identified by the given device-id.
The command-name is the value associated to the realCommandName parameter present in the device description (see the \devices resource).
Commands are idempotent: the same command always results in the same behavior of the selected device. If the command brings the device in same state in which the device is, no differences will be appreciable.
URL: /devices/{device-id}/commands/{command-name}
| Method | Description |
|---|---|
| PUT | sends the command identified by the given command-name |
| POST | sends the command identified by the given command-name (deprecated) |
{% include accordion-header.html %} {% include open-accordion-item.html panelTitle='Example Requests' panelCount='11' %}
{% include restapi/put-single-device-command.html %}
{% include close-accordion-item.html %} {% include accordion-footer.html %}
Updated on Thu, 2013-12-05 API version 1.0
|----------------|------------------| |Authentication |None| |Response Format|json| |HTTP Methods|PUT| |Resource family|device| |Response Object|String| |API Version|v1.0|
Sets the Weekly Schedule for the Thermostatic Vlave identified by {device-id}
URL: /devices/{device-id}/commands/setClimateSchedule
| Method | Description |
|---|---|
| PUT | Set the new weekly schedule for the Thermostatic Valve identified by {device-id}, the previous schedule is discarded. |
| POST | (Deprecated) Set the new weekly schedule for the Thermostatic Valve identified by {device-id}, the previous schedule is discarded. |
PUT: Example
PUT http://www.mydog.com/api/v1/devices/ThermostaticRadiatorValve_1/commands/setClimateSchedule
{% include accordion-header.html %} {% include open-accordion-item.html panelTitle='Request Body' panelCount='12' %}
{% include restapi/put-climate-schedule.json %}
{% include close-accordion-item.html %} {% include accordion-footer.html %}
Updated on Thu, 2013-12-05 API version 1.0
|----------------|------------------| |Authentication |None| |Response Format|json| |HTTP Methods|PUT| |Resource family|device| |Response Object|String| |API Version|v1.0|
Sets the Daily Schedule for the Thermostatic Valve identified by {device-id}
URL: /devices/{device-id}/commands/setDailyClimateSchedule
| Method | Description |
|---|---|
| PUT | Set the new daily schedule for the Thermostatic Valve identified by {device-id}, the previous schedule is discarded. |
| POST | (Deprecated) Set the new daily schedule for the Thermostatic Valve identified by {device-id}, the previous schedule is discarded. |
PUT: Example
PUT http://www.mydog.com/api/v1/devices/ThermostaticRadiatorValve_1/commands/setDailyClimateSchedule
{% include accordion-header.html %} {% include open-accordion-item.html panelTitle='Request Body' panelCount='13' %}
{% include restapi/put-daily-climate-schedule.json %}
{% include close-accordion-item.html %} {% include accordion-footer.html %}
Updated on Thu, 2013-12-05 API version 1.0
|----------------|------------------| |Authentication |None| |Response Format|json| |HTTP Methods|PUT| |Resource family|device| |Response Object|String| |API Version|v1.0|
Sets the Temperature setPoint for the Thermostatic Valve identified by {device-id}
URL: /devices/{device-id}/commands/setTemperatureAt
| Method | Description |
|---|---|
| PUT | Set the new temperature setPoint for the Thermostatic Valve identified by {device-id}, the previous schedule is discarded. |
| POST | (Deprecated) Set the new temperature setPoint for the Thermostatic Valve identified by {device-id}, the previous schedule is discarded. |
PUT: Example
PUT http://www.mydog.com/api/v1/devices/ThermostaticRadiatorValve_1/commands/setTemperatureAt
{% include accordion-header.html %} {% include open-accordion-item.html panelTitle='Request Body' panelCount='14' %}
{% include restapi/put-setpoint.json %}
{% include close-accordion-item.html %} {% include accordion-footer.html %}
Updated on Tue, 2013-10-22 Unavailable
|----------------|------------------| |Authentication |None| |Response Format|json| |HTTP Methods|GET| |Resource family|configuration| |Response Object|DeviceConfigurations| |API Version|v1.1|
URL: /dog/configuration
| Method | Description |
|---|---|
| GET | List all low-level device configurations used by the Dog gateway |
| PUT | Create / Update the set of low-level device configurations that Dog should manage. Any device configuration matching an already configured device replaces the existing configuration, whereas devices not being mentioned in the current Dog configurations are added, and deployed at runtime, i.e., made available to calling applications. |
Updated on Thu, 2013-11-09 API version 1.0
|----------------|------------------| |Authentication |None| |Response Format|json or xml| |HTTP Methods|GET| |Resource family|environment| |Response Object|Array [ Buildings ]| |API Version|v1.0|
Represents the environment (i.e., the building) configured in Dog.
URL: /environment
| Method | Description |
|---|---|
| GET | List the building environments (i.e., the building) configured in the Dog gateway. |
Example Request
GET http://www.mydog.com/api/v1/environment
{% include accordion-header.html %} {% include open-accordion-item.html panelTitle='Example Response (JSON)' panelCount='15' %}
{% include restapi/get-environment.json %}
{% include close-accordion-item.html %} {% include open-accordion-item.html panelTitle='Example Response (XML)' panelCount='16' %}
{% capture xml %}
{% include restapi/get-environment.xml %}
{% endcapture %}
{{ xml | escape }}
{% include close-accordion-item.html %} {% include accordion-footer.html %}
Updated on Thu, 2013-11-09 API version 1.0
|----------------|------------------| |Authentication |None| |Response Format|json| |HTTP Methods|GET or POST| |Resource family|environment| |Response Object|Array [ Flat ]| |API Version|v1.0|
Represents all the flats present in the environment (i.e., int the building).
URL: /environment/flats
| Method | Description |
|---|---|
| GET | List all the flats present in the in the (only, right now) building configured in Dog. |
| POST | Add a new flat to the building configured in Dog. |
Example Requests
GET http://www.mydog.com/api/v1/environment/flats
{% include accordion-header.html %} {% include open-accordion-item.html panelTitle='Example Response (JSON)' panelCount='17' %}
{% include restapi/get-environment-flat.json %}
{% include close-accordion-item.html %} {% include accordion-footer.html %}
POST http://www.mydog.com/api/v1/environment/flats
{% include accordion-header.html %} {% include open-accordion-item.html panelTitle='Request Body' panelCount='18' %}
{% capture xml %}
{% include restapi/post-environment-flat.json %}
{% endcapture %}
{{ xml | escape }}
{% include close-accordion-item.html %} {% include accordion-footer.html %}
Updated on Wed, 2014-05-07 API version 1.0
|----------------|------------------| |Authentication |None| |Response Format|json| |HTTP Methods|GET or PUT| |Resource family|environment| |Response Object|Flat| |API Version|v1.0|
Represents a specific flat present in the environment (i.e., in the building).
URL: /environment/flats
| Method | Description |
|---|---|
| GET | Returns the details of the flat identified by the given flat-id. |
| PUT | Update the flat identified by the given flat-id. |
| DELETE | Delete the flat identified by the given flat-id. |
Example Requests
GET http://www.mydog.com/api/v1/environment/flats/flat
{% include accordion-header.html %} {% include open-accordion-item.html panelTitle='Example Response (JSON)' panelCount='19' %}
{% include restapi/get-environment-single-flat.json %}
{% include close-accordion-item.html %} {% include accordion-footer.html %}
PUT http://www.mydog.com/api/v1/environment/flats/flat
{% include accordion-header.html %} {% include open-accordion-item.html panelTitle='Request Body' panelCount='20' %}
{% capture xml %}
{% include restapi/put-environment-single-flat.json %}
{% endcapture %}
{{ xml | escape }}
{% include close-accordion-item.html %} {% include accordion-footer.html %}
DELETE http://www.mydog.com/api/v1/environment/flats/flat
Updated on Thu, 2013-11-09 API version 1.0
|----------------|------------------| |Authentication |None| |Response Format|json| |HTTP Methods|GET or POST| |Resource family|environment| |Response Object|Array [ Room ]| |API Version|v1.0|
Represents all the rooms present in a given flat.
URL: /environment/flats
| Method | Description |
|---|---|
| GET | List all the rooms present in the flat identified by the given flat-id. |
| POST | Add a new room to the flat identified by the given flat-id. |
Example Requests
GET http://www.mydog.com/api/v1/environment/flats/flat/rooms
{% include accordion-header.html %} {% include open-accordion-item.html panelTitle='Example Response (JSON)' panelCount='21' %}
{% include restapi/get-environment-rooms.json %}
{% include close-accordion-item.html %} {% include accordion-footer.html %}
POST http://www.mydog.com/api/v1/environment/flats/flat/rooms
{% include accordion-header.html %} {% include open-accordion-item.html panelTitle='Request Body' panelCount='22' %}
{% capture xml %}
{% include restapi/post-environment-rooms.json %}
{% endcapture %}
{{ xml | escape }}
{% include close-accordion-item.html %} {% include accordion-footer.html %}
Updated on Wed, 2014-05-07 API version 1.0
|----------------|------------------| |Authentication |None| |Response Format|json| |HTTP Methods|GET or PUT| |Resource family|environment| |Response Object|Room| |API Version|v1.0|
Represents a specific room in the flat identified by the given flat-id.
URL: /environment/flats/{flat-id}/rooms/{room-id}
| Method | Description |
|---|---|
| GET | Returns the details of the room identified by the given room-id and located in the given flat. |
| PUT | Update the room identified by the given room-id and located in the given flat. |
| DELETE | Delete the room identified by the given room-id and located in the given flat. |
Example Requests
GET http://www.mydog.com/api/v1/environment/flats/flat/rooms/kitchen
{% include accordion-header.html %} {% include open-accordion-item.html panelTitle='Example Response (JSON)' panelCount='23' %}
{% include restapi/get-environment-single-room.json %}
{% include close-accordion-item.html %} {% include accordion-footer.html %}
PUT http://www.mydog.com/api/v1/environment/flats/flat/rooms/kitchen
{% include accordion-header.html %} {% include open-accordion-item.html panelTitle='Request Body' panelCount='24' %}
{% capture xml %}
{% include restapi/put-environment-single-room.json %}
{% endcapture %}
{{ xml | escape }}
{% include close-accordion-item.html %} {% include accordion-footer.html %}
DELETE http://www.mydog.com/api/v1/environment/flats/flat/rooms/kitchen
Updated on Thu, 2013-11-08 API version 1.0
|----------------|------------------| |Authentication |None| |Response Format|xml or json| |HTTP Methods|GET or POST| |Resource family|rules| |Response Object|Array [ Rule ]| |API Version|v1.0|
Represents the rules registered in Dog. By using this resource, it is possible to get all the existing rules or add a new rule.
Currently, all the responses and the requests are in XML format.
URL: /rules/
| Method | Description |
|---|---|
| GET | Returns all the existing rules. |
| POST | Add a new rule to the current rules set. If the rule already exists, it will be overwritten. |
Example Requests
GET http://www.mydog.com/api/v1/rules
{% include accordion-header.html %} {% include open-accordion-item.html panelTitle='Example Response (JSON)' panelCount='25' %}
{% include restapi/get-rules.json %}
{% include close-accordion-item.html %} {% include open-accordion-item.html panelTitle='Example Response (XML)' panelCount='26' %}
{% capture xml %}
{% include restapi/get-rules.xml %}
{% endcapture %}
{{ xml | escape }}
{% include close-accordion-item.html %} {% include accordion-footer.html %}
POST http://www.mydog.com/api/v1/rules
{% include accordion-header.html %} {% include open-accordion-item.html panelTitle='Request Body' panelCount='27' %}
{% capture xml %}
{% include restapi/post-rules.xml %}
{% endcapture %}
{{ xml | escape }}
{% include close-accordion-item.html %} {% include accordion-footer.html %}
Updated on Thu, 2013-11-08 API version 1.0
|----------------|------------------| |Authentication |None| |Response Format|xml or json| |HTTP Methods|GET, PUT or DELETE| |Resource family|rules| |Response Object|Rule| |API Version|v1.0|
Represents an existing rule registered in Dog. By using this resource, it is possible to update or delete an existing rule.
Currently, all the responses and the requests are in XML format.
URL: /rules/{rule-id}
| Method | Description |
|---|---|
| GET | Returns the details of the rules identified by rule-id. |
| PUT | Update the rule identified by rule-id. |
| DELETE | Remove the rule identified by the given rule-id. |
Example Requests
GET http://www.mydog.com/api/v1/rules/onToOn
{% include accordion-header.html %} {% include open-accordion-item.html panelTitle='Example Response (JSON)' panelCount='28' %}
{% include restapi/get-single-rule.json %}
{% include close-accordion-item.html %} {% include open-accordion-item.html panelTitle='Example Response (XML)' panelCount='29' %}
{% capture xml %}
{% include restapi/get-single-rule.xml %}
{% endcapture %}
{{ xml | escape }}
{% include close-accordion-item.html %} {% include accordion-footer.html %}
PUT http://www.mydog.com/api/v1/rules/consumptionToHigh
{% include accordion-header.html %} {% include open-accordion-item.html panelTitle='Request Body' panelCount='30' %}
{% capture xml %}
{% include restapi/put-single-rule.xml %}
{% endcapture %}
{{ xml | escape }}
{% include close-accordion-item.html %} {% include accordion-footer.html %}
DELETE http://www.mydog.com/api/v1/rules/onToOn