webserviceinterface
Differences
This shows you the differences between two versions of the page.
|
webserviceinterface [2012/06/19 17:47] elyoliveira |
webserviceinterface [2013/06/18 14:35] (current) elyoliveira |
||
|---|---|---|---|
| Line 2: | Line 2: | ||
| ===== Web Service Interface ===== | ===== Web Service Interface ===== | ||
| - | This page is under construction. We intend to specify here the web service interface used by all users and Flukso V2 devices to communicate with the mySmartGrid server. | + | 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 it relies on the HTTP protocol and the JSON standard. Regarding security, all the communication is performed over HTTPS, using a server certificate issued by the mySmartGrid CA. Additionally, both request and response bodies are encrypted using the device individual SHA-1 key, which only the server and the device know. | + | 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. | 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. | ||
| Line 28: | Line 30: | ||
| == HTTP Headers == | == HTTP Headers == | ||
| - | ^ Name ^ Description ^ | + | ^ Name ^ Description ^ |
| - | | X-Version | The device firmware version | | + | | X-Version | The API version (currently supported: 1.0) | |
| - | | X-Digest | The message digest, using the device key | | + | | X-Digest | The message digest, using the device key | |
| + | | Accept | The response data type: application/json | | ||
| \\ | \\ | ||
| Line 43: | Line 46: | ||
| | 301 | Moved Permanently | This and all future requests should be directed to the given URI. | | | 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. | | | 400 | Bad request | The request cannot be fulfilled due to bad syntax. | | ||
| - | | 403 | Forbidden | The user is not authorized to access the requested resource. | | + | | 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. | | | 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. | | | 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. | | | 501 | Not Implemented | The server does not provide the requested operation. | | ||
| Line 97: | Line 103: | ||
| ^ Response Body | The field 'support' is included only if the user requests device remote support on the web application. | ^ Response Body | The field 'support' is included only if the user requests device remote support on the web application. | ||
| { | { | ||
| - | upgrade: <string(32) - whether or not there is a pending firmware upgrade>, | + | upgrade: <integer - flag to indicate whether or not there is a pending firmware upgrade>, |
| - | timestamp: <unixtime - server current time>, | + | timestamp: <unixtime - server current time>, |
| support: { | support: { | ||
| user: <string(60) - username for the reverse SSH connection>, | user: <string(60) - username for the reverse SSH connection>, | ||
| Line 112: | Line 118: | ||
| \\ | \\ | ||
| - | == Device Configuration File Download == | + | == Firmware Upgrade File Download == |
| - | Downloads a pending configuration file for a device. | + | Downloads a firmware upgrade file. The server responds with HTTP error 404 if there is no pending upgrade for the device. |
| - | ^ Method | GET | | + | ^ Method | GET | |
| - | ^ URL | %%https://api.mysmartgrid.de:8443%%/file/<device id> | | + | ^ URL | %%https://api.mysmartgrid.de:8443%%/firmware/<device id> | |
| + | ^ Request Body | | ||
| + | { | ||
| + | } | ||
| + | | | ||
| ^ Response Body | | ^ Response Body | | ||
| { | { | ||
| - | data: <string - the Base64-encoded file content> | + | data: <string - the Base64-encoded shell script to be executed on the device> |
| } | } | ||
| | | | | ||
| Line 142: | Line 152: | ||
| | | | | ||
| \\ | \\ | ||
| + | |||
| + | 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 == | == Sensor Configuration == | ||
| Line 173: | Line 192: | ||
| == Sensor Measurements Registration == | == Sensor Measurements Registration == | ||
| - | Reports sensor measurements to the server. The measurement values are saved in RRD files in Ws (Wattseconds). | + | Reports sensor measurements to the server. The measurement values are saved in RRD files in Wh (watt-hour). |
| ^ Method | POST | | ^ Method | POST | | ||
| Line 181: | Line 200: | ||
| measurements: [ | measurements: [ | ||
| [ <unixtime - timestamp of the first measurement>, | [ <unixtime - timestamp of the first measurement>, | ||
| - | <integer - consumed power in kW/h (ever increasing value), measured at the first timestamp> ], | + | <integer - consumed energy in Wh (ever increasing value), measured at the first timestamp> ], |
| ... | ... | ||
| [ <unixtime - timestamp of the measurement n>, | [ <unixtime - timestamp of the measurement n>, | ||
| - | <integer - consumed power in kW/h (ever increasing value), measured at the timestamp n> ] | + | <integer - consumed energy in Wh (ever increasing value), measured at the timestamp n> ] |
| ] | ] | ||
| } | } | ||
| Line 202: | Line 221: | ||
| == Sensor Measurements Query == | == Sensor Measurements Query == | ||
| - | Queries measurements performed by a sensor. | + | 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 | | ^ Method | GET | | ||
| ^ URL | %%https://api.mysmartgrid.de:8443%%/sensor/<sensor id>?<attributes> | | ^ URL | %%https://api.mysmartgrid.de:8443%%/sensor/<sensor id>?<attributes> | | ||
| - | ^ Headers | | + | ^ Extra Headers | |
| - | Accept: application/json | + | X-Token: <string(32) - sensor token> |
| - | X-Version: <integer - device firmware version> | + | |
| - | X-Token: <string(32) - sensor token> | + | |
| | | | | ||
| ^ Attributes | | ^ Attributes | | ||
webserviceinterface.1340120855.txt.gz · Last modified: 2012/10/30 10:37 (external edit)
Page Tools
Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Noncommercial-Share Alike 3.0 Unported
