===== Web Service Interface ===== This page is under construction. We intend to specify here 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. In addition, both request and response bodies are encrypted using the device individual SHA-1 key, which only the server and the device know. 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 Headers == ^ Name ^ Description ^ | X-Version | The API version (currently supported: 1.0) | | X-Digest | The message digest, using the device key | | Accept | The response data type: application/json | \\ === 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. | | 301 | Moved Permanently | This and all future requests should be directed to the given URI. | | 400 | Bad request | The request cannot be fulfilled due to bad syntax. | | 401 | Unauthorized | The user is not authorized to access the requested resource, possibly because it is not authenticated. | | 403 | Forbidden | The user is not authorized to access the requested resource, even if it is authenticated. | | 404 | Not Found | The requested resource does not exist on the server. | | 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. | | 500 | Internal Server Error | The request was aborted due to an unspecified error on the server. | | 501 | Not Implemented | The server does not provide the requested operation. | \\ === Messages Reference === == Device Registration == Requests the registration of a device on the server. ^ Method | POST | ^ URL | %%https://api.mysmartgrid.de:8443%%/device/ | ^ Request Body | { key: } | ^ Response Body | { upgrade: , timestamp: } | \\ == 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/ | ^ Request Body | { memtotal: , memcached: , membuffers: , memfree: , uptime: , reset: , version: , firmware: { version: , releasetime: , build: , tag: } } | ^ Response Body | The field 'support' is included only if the user requests device remote support on the web application. { upgrade: , timestamp: , support: { user: , host: , port: , tunnelport: , devicekey: , techkey: , hostkey: } } | \\ == 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/ | ^ 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/ | ^ 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/ | ^ Request Body | { config : { device: , function: , class: , voltage: , current: , phase: , constant: , type: , enable: } } | ^ Response Body | { timestamp: } | \\ == 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/ | ^ Request Body | { measurements: [ [ , ], ... [ , ] ] } | ^ Response Body | { response: } | ^ Error Response Body | { response: } | \\ == Sensor Measurements Query == Queries measurements performed by a sensor. The header X-Digest is not informed, since authentication is based on the sensor token, informed in header X-Token. ^ Method | GET | ^ URL | %%https://api.mysmartgrid.de:8443%%/sensor/? | ^ Extra Headers | X-Token: | ^ 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. The sensor id and token are fictitious 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: dvd1mtm1tktktktktktktktktktktkt1" -H "Accept: application/json" "https://api.mysmartgrid.de:8443/sensor/dvd1mtmtmtmtmtmtmtmtmtmtmtmtmtm1?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: dvd1mtm1tktktktktktktktktktktkt1" -H "Accept: application/json" "https://api.mysmartgrid.de:8443/sensor/dvd1mtmtmtmtmtmtmtmtmtmtmtmtmtm1?start=1317765600&end=1317826800&resolution=15min&unit=eurperyear"