===== Web Service Interface (Version 2.1) ===== This page specifies the web service interface used by all users and software clients (including Flukso V2 devices) to communicate with the mySmartGrid server. The mySmartGrid API adopts the RESTful model, and therefore relies on the HTTP protocol and the JSON standard. All the communication is performed over HTTPS, using a server certificate issued by the mySmartGrid CA. Despite some similarities, the mySmartGrid API is different from the Flukso.net API in many important aspects. So, if you want to switch from the Flukso.net platform to mySmartGrid, we strongly recomend you to flash the [[http://openwrt.mysmartgrid.de/flm02/atheros|latest mySmartGrid image]] to your device. ==== Request Message Structure ==== === URL === %%https://api.mysmartgrid.de:8443%%/[/[?]] ... [] ^ Part ^ Description ^ | | The entity being affected by the invocation | | | The object id | | | The list of parameters of the operation | | | A JSON object provided by all POST messages | === HTTP Methods === ^ Name ^ Purpose ^ | GET | object retrieval | | POST | object update and creation | | DELETE | object removal | === HTTP Common Headers === ^ Name ^ Description ^ | X-Version | The minimum version supported by this API (currently, 1.0) | | Accept | The response data type: application/json | | User-Agent | The name of the client software, performing the request, for example: Flukso 2 | \\ ==== Response Structure ==== The HTTP status code is used to inform the client of the request execution result. Further information is returned in the response body. Successful requests return JSON objects, as seen in the following section, and failed requests return the default MochiWeb HTML error page. In all cases, clients should primarily check the HTTP status code in order to properly interpret the response. === HTTP Status Codes === ^ Code ^ Status ^ Description ^ | 200 | OK | The request has been successfully processed by the server. | | 301 | Moved Permanently | This and all future requests should be directed to the given URL. | | 400 | Bad request | The request cannot be fulfilled due to bad syntax. Please check the message structure. | | 401 | Unauthorized | The user is not authorized to access the requested resource, because it has not been successfully authenticated. Please check the object id, device key, and token. | | 403 | Forbidden | The user is not authorized to access the requested resource, even if authenticated. Please check the URL and object id. | | 404 | Not Found | The requested resource does not exist on the server. Please check the object id used. | | 405 | Method Not Allowed | Method not supported by resource, for example, using GET on a resource that supports only POST. | | 406 | Not acceptable | The resource identified by the request is only capable of generating response entities which have content characteristics not acceptable according to the accept headers sent in the request. Please check the message structure, and use the headers as described in this page. | | 470 | Invalid Timestamp | The request cannot be fulfilled because it contains invalid timestamps. Please check your message data and be sure your system clock is up-to-date. | | 471 | Invalid Unit | The request cannot be fulfilled because it contains an invalid unit. Please have a look at the list of supported units below.| | 472 | Invalid Measurement | The request cannot be fulfilled because it contains invalid measurement values. Please check the message structure. | | 473 | Invalid Object Type | The request cannot be fulfilled because it contains invalid object type. Please check the message structure. | | 474 | Invalid Object Id | The request cannot be fulfilled because it contains invalid object id. Please check the message structure. | | 475 | Invalid Key | The request cannot be fulfilled because it contains invalid key. Please check the message structure. | | 476 | Invalid Time Period | The request cannot be fulfilled because it contains invalid time period. Please check the message structure. | | 477 | Invalid Event | The request cannot be fulfilled because it contains invalid an invalid event id. Please check the message structure. | | 478 | Unupgradable Firmware | The current device firmware can not be upgraded via the API. Please, flash the [[http://openwrt.mysmartgrid.de/flm02/atheros|latest mySmartGrid image]] to your device manually. | | 479 | Invalid Sensor External Id | The request cannot be fulfilled because it contains invalid sensor external id. Please check the message structure. If the problem persists, the id might be taken. In this case, please inform a new one. | | 480 | Invalid Characters | The request cannot be fulfilled because it contains a string with non-printable characters. | | 481 | Invalid Network Configuration | The request cannot be fulfilled because it contains invalid network configuration properties. Please check the message structure. | | 499 | Client Closed Request | The connection has been closed by client while the server is still processing its request, making server unable to send a status code back. | | 500 | Internal Server Error | The request was aborted due to an unspecified error on the server. This incident has been reported to the mySmartGrid team. | | 501 | Not Implemented | The server does not provide the requested operation. Please check the X-Version header and the URL structure. | \\ ==== Measurement Units ==== The table below shows the list of measurement units supported by the API. Use their ids to inform the unit arguments of some requests. ^ Name ^ Symbol ^ Id ^ | Watt | W | Watt | | Kilowatt-hour | kWh | kWh | | Kilowatt-hour per year | kWh / year | kWhPerYear | | Watt-hour | Wh | Wh | | Degree Celsius | °C | degC | | Hectopascal | hPa | hPa | | Relative Humidity | %r.h. | rh | | Internal Control Unit | _hsbs | _hsbs | \\ ==== Messages Reference ==== === Device Registration === Requests the registration of a device on the server. ^ Method | POST | ^ URL | %%https://api.mysmartgrid.de:8443%%/device/ | ^ Extra Headers | X-Digest: | ^ Request Body | { key: , description: , memtotal: , memcached: , membuffers: , memfree: , uptime: , reset: , version: , firmware: (optional) { version: , releasetime: , build: , tag: }, type: } | ^ Response Body | { upgrade: , timestamp: } | \\ === Device Removal === Removes a device and all its related data from the server. ^ Method | DELETE | ^ URL | %%https://api.mysmartgrid.de:8443%%/device/ | ^ Extra Headers | X-Digest: | ^ Response Body | { response: } | ^ Error Response Body | { response: } | \\ === Device Heartbeat === Sends a life signal to the server, which contains information about the device environment. ^ Method | POST | ^ URL | %%https://api.mysmartgrid.de:8443%%/device/ | ^ Extra Headers | X-Digest: | ^ Request Body | The field 'config' is included only if the Flukso changed its configuration due to the information from the last heartbeat. { description: , memtotal: , memcached: , membuffers: , memfree: , uptime: , reset: , version: , firmware: (optional) { version: , releasetime: , build: , tag: }, config: (optional) { network: (optional) { lan: (optional) { enabled: , protocol: , ip: , netmask: , gateway: , nameserver: }, wifi: (optional) { enabled: , essid: , enc: , psk: , protocol: , ip: , netmask: , gateway: , nameserver: } } }, type: , } | ^ Response Body | The field 'support' is included only if the user requests device remote support on the web application. The block 'config' is only included if the configuration on the server differs from the configuration of the device. { upgrade: , timestamp: , support: { user: , host: , port: , tunnelport: , devicekey: , techkey: , hostkey: }, config: (optional) { network: (optional) { lan: (optional) { enabled: , protocol: , ip: , netmask: , gateway: , nameserver: }, wifi: (optional) { essid: , enc: , psk: , protocol: , ip: , netmask: , gateway: , nameserver: } }, sensors: [ , ... ] } } | \\ === Device Query === Queries the device properties and its list of sensors. Either header X-Token or X-Digest should be informed for authentication. ^ Method | GET | ^ URL | %%https://api.mysmartgrid.de:8443%%/device/ | ^ Extra Headers | X-Token: X-Digest: | ^ Response Body | { description: , type: , sensors: [ { meter: , function: }, ... { meter: , function: } ] } | \\ === Firmware Upgrade File Download === Downloads a firmware upgrade file. The server responds with HTTP error 404 if there is no pending upgrade for the device. ^ Method | GET | ^ URL | %%https://api.mysmartgrid.de:8443%%/firmware/ | ^ Extra Headers | X-Digest: | ^ Request Body | { } | ^ Response Body | { data: } | \\ === Device Event Notification === Notifies the server of the occurrence of a device event. ^ Method | POST | ^ URL | %%https://api.mysmartgrid.de:8443%%/event/ | ^ Extra Headers | X-Digest: | ^ Request Body | { device: } | ^ Response Body | { timestamp: } | The list of possible events is shown bellow. ^ Code ^ Name ^ Description ^ | 104 | Brownout | The device has detected a brownout event. | | 105 | Firmware Upgraded | The device has successfully performed a firmware upgrade. | | 106 | Failed Firmware Upgrade | The device has failed to performed a firmware upgrade. | \\ === Sensor Configuration === Registers or updates a device sensor. This message must be preceded by a device registration message. ^ Method | POST | ^ URL | %%https://api.mysmartgrid.de:8443%%/sensor/ | ^ Extra Headers | X-Digest: | ^ Request Body | { config : { device: , externalid: , function: , class: , voltage: , current: , constant: , description: , unit (optional): , port (optional): } } | ^ Response Body | { timestamp: } | \\ === Sensor Configuration Query === Queries the current configuration of a sensor. This message must be preceded by a device registration message. ^ Method | GET | ^ URL | %%https://api.mysmartgrid.de:8443%%/sensor/ | ^ Extra Headers | X-Digest: | ^ Response Body | { config : { device: , externalid: , function: , unit: , class: , voltage: , current: , constant: , type: , description: , port (optional): } } | \\ === Sensor Measurements Registration === Reports sensor measurements to the server. The measurement values are saved in RRD files in Wh (Watt-hour). ^ Method | POST | ^ URL | %%https://api.mysmartgrid.de:8443%%/sensor/ | ^ Extra Headers | X-Digest: | ^ Request Body | { measurements: [ [ , ], ... [ , ] ] } | ^ Response Body | { response: } | ^ Error Response Body | { response: } | \\ === Sensor Removal === Removes a sensor and all its related data from the server. ^ Method | DELETE | ^ URL | %%https://api.mysmartgrid.de:8443%%/sensor/ | ^ Extra Headers | X-Digest: | ^ Response Body | { response: } | ^ Error Response Body | { response: } | \\ === Sensor Measurements Query === Queries measurements performed by a sensor. Either header X-Digest or header X-Token must be informed for authentication. ^ Method | GET | ^ URL | %%https://api.mysmartgrid.de:8443%%/sensor/? | ^ Extra Headers | X-Token: X-Digest: | ^ Attributes | start = end = resolution = unit = interval = | ^ Response Body | { measurements: [ [ , ], ... [ , ] ] } | \\ In the following, two examples are given of how this operation can be invoked from a Linux shell, using curl. The sensor id and token are from a demo device and should be replaced by real values. **Query 1: ** Measurements performed during the past 1 hour, in minute resolution, and in watt. curl -k -v -X GET \ -H "X-Version: 1.0" \ -H "X-Token: d3a16238d92456bb0f6727743275dce0" \ -H "Accept: application/json" \ "https://api.mysmartgrid.de:8443/sensor/5715a57b0c8ec958727ab3bb206d8b6e?\ interval=hour&unit=watt" **Query 2: ** Measurements performed between 05.10.2011 00:00:00 GMT+2:00 and 05.10.2011 17:00:00 GMT+2:00, in 15-minute resolution, and in euros per year. curl -k -v -X GET \ -H "X-Version: 1.0" \ -H "X-Token: d3a16238d92456bb0f6727743275dce0" \ -H "Accept: application/json" \ "https://api.mysmartgrid.de:8443/sensor/5715a57b0c8ec958727ab3bb206d8b6e?\ start=1317765600&end=1317826800&resolution=15min&unit=eurperyear" Notes: The argument "-k" allows curl to overlook server certificate validation and work in an insecure mode. If you want to be sure you are connecting the right server, you need the mySmartGrid CA certificate installed in your system. Please take the following steps to install the certificate in a Debian/Ubuntu distribution. - Download the [[https://www.mysmartgrid.de/files/msg-ca/msg_CA.crt|mySmartGrid CA certificate file]]. - Move the file to /usr/local/share/ca-certificates. You may change the file name, but the extension must remain crt. - Run the command "sudo update-ca-certificates". You should see a message like: "1 added, 0 removed; done". After that, if you omit the argument "-k", the server certificate will be validated, and the command output should contain the following section. Server certificate: subject: C=DE; O=Fraunhofer-Gesellschaft; OU=ITWM; CN=api.mysmartgrid.de start date: 2013-05-13 09:13:45 GMT expire date: 2023-05-11 09:13:45 GMT common name: api.mysmartgrid.de (matched) issuer: C=DE; O=Fraunhofer-Gesellschaft; OU=ITWM; CN=mySmartGrid CA SSL certificate verify ok. The message "SSL certificate verify ok" means that you are connecting to the right server. Otherwise, you would see messages like "SSL certificate problem", "host name does not match", or "expired certificate". If you are unable or unwilling to install the CA certificate in your system, inform the location of the CA file by adding "--cacert /path/to/msg_CA.crt" to the command.