User Tools

Site Tools


webserviceinterface

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

webserviceinterface [2012/06/12 10:53]
elyoliveira [Web Service Interface]
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. The API relies on protocol HTTPS, and the JSON standard. All date/time values are Unix timestamps.+This page is under construction. We intend to specify here the web service interface used by all users and software clients (including Flukso V2 devicesto communicate with the mySmartGrid server.
  
 +The mySmartGrid API adopts the RESTful model, and therefore relies on the HTTP protocol and the JSON standard. 
  
-=== Message Structure ===+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 == == URL ==
Line 24: 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     | 
 + \\  
 + 
 + 
 +=== 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. |
  \\   \\ 
  
Line 34: Line 60:
 == Device Registration == == Device Registration ==
  
-Requests registration of a device on the server.+Requests the registration of a device on the server.
  
 ^ Method       | POST                                                    | ^ Method       | POST                                                    |
 ^ URL          | %%https://api.mysmartgrid.de:8443%%/device/<device id>  | ^ URL          | %%https://api.mysmartgrid.de:8443%%/device/<device id>  |
-^ Body         |+Request Body |
   {   {
-    key: <SHA-1 key (32 bytes long) used for device authentication>+    key:       <string(32) - SHA-1 key used for device authentication>
   }   }
 | |
-^ Response     +^ Response Body 
   {   {
-    upgrade:   <flag (0, 1) to indicate whether or not there is a pending firmware upgrade>,  +    upgrade:   <integer  - flag to indicate whether or not there is a pending firmware upgrade>,  
-    timestamp: <server current time>+    timestamp: <unixtime - server current time>
   }   }
  
 \\  \\ 
 +
  
 == Device Heartbeat == == Device Heartbeat ==
Line 57: Line 84:
 ^ Method       | POST                                                    | ^ Method       | POST                                                    |
 ^ URL          | %%https://api.mysmartgrid.de:8443%%/device/<device id>  | ^ URL          | %%https://api.mysmartgrid.de:8443%%/device/<device id>  |
-^ Body         +Request Body | 
   {   {
-    memtotal:   <total RAM>, +    memtotal:   <integer - total RAM in MB>, 
-    memcached:  <total cache memory in MB>, +    memcached:  <integer - total cache memory in MB>, 
-    membuffers: <total buffer memory in MB>, +    membuffers: <integer - total buffer memory in MB>, 
-    memfree:    <total free memory in MB>, +    memfree:    <integer - total free memory in MB>, 
-    uptime:     <total time the device is up and running>,  +    uptime:     <integer - total time the device has been up and running, in seconds>, 
-    reset:      <number of times the device has been reseted>, +    reset:      <integer - number of times the device has been reset>, 
-    version:    <device version>, +    version:    <integer - this field has been deprecated, and is currently being ignored by the server>,
     firmware:   {     firmware:   {
-      version:      <firmware version, for example: 2.3.1-1 >, +      version:      <string(11) - firmware version using format: 9.9.9-9, for example: 2.3.1-1>, 
-      releasetime:  <firmware release date and time using format: YYYYmmmdd_HHii, for example: 20120524_1158>, +      releasetime:  <string(14) - firmware release date and time using format: YYYYmmmdd_HHii, for example: 20120524_1158>, 
-      build:        <firmware release identifier, for example: f0ba69e4fea1d0c411a068e5a19d0734511805bd>, +      build:        <string(32) - firmware release identifier, for example: f0ba69e4fea1d0c411a068e5a19d0734511805bd>, 
-      tag:          <firmware release tag in Git repository, for example: flukso-2.0.3-rc1-19-gf0ba69e>+      tag:          <string(32) - firmware release tag in Git repository, for example: flukso-2.0.3-rc1-19-gf0ba69e>
     }     }
   }   }
 | |
-^ Response     | 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:     <flag to indicate whether there is a pending upgrade>, +    upgrade:    <integer     - flag to indicate whether or not there is a pending firmware upgrade>, 
-    timestamp:   <server current time>,+    timestamp:  <unixtime    - server current time>,
     support: {     support: {
-      user:      <username for the reverse SSH connection>, +      user:       <string(60)  - username for the reverse SSH connection>, 
-      host:      <hostname for the reverse SSH connection>, +      host:       <string(60)  - hostname for the reverse SSH connection>, 
-      port:      <port for the reverse SSH connection>, +      port:       <integer     - port where SSH is running on host>, 
-      devicekey: <a Base64-encoded DSA key to be used by the device for SSH authentication>, +      tunnelport: <integer     - port bound to the device localhost:22>, 
-      techkey:   <the technician DSA key to be added to file the authorized_keys on the device>, +      devicekey:  <string(700) - a Base64-encoded DSA key to be used by the device for SSH authentication>, 
-      hostkey:   <the host RSA key to be added to the file known_hosts on the device>+      techkey:    <string(700) - the technician DSA key to be added to file the authorized_keys on the device>, 
 +      hostkey:    <string(700) - the host RSA key to be added to the file known_hosts on the device>
     }     }
   }    } 
Line 90: Line 118:
 \\  \\ 
  
-== Device Event Notification ==+== Firmware Upgrade File Download ==
  
-!!Not yet verified or tested!!+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/<device id> | 
 +^ Request Body |  
 +  { 
 +  } 
 +
 +^ Response Body | 
 +  { 
 +    data:       <string - the Base64-encoded shell script to be executed on the device> 
 +  } 
 +
 +\\  
 + 
 +== Device Event Notification ==
  
 Notifies the server of the occurrence of a device event. Notifies the server of the occurrence of a device event.
Line 98: Line 141:
 ^ Method       | POST                                                    | ^ Method       | POST                                                    |
 ^ URL          | %%https://api.mysmartgrid.de:8443%%/event/<event id>    | ^ URL          | %%https://api.mysmartgrid.de:8443%%/event/<event id>    |
-^ Body         |+Request Body |
   {   {
-    device: <device id>+    device:    <string(32) - device id>
   }   }
 | |
-^ Response     +^ Response Body 
   {   {
-    timestamp: <server current time>+    timestamp: <unixtime   - server current time>
   }   }
 | |
 \\  \\ 
 +
 +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 116: Line 168:
 ^ Method       | POST                                                    | ^ Method       | POST                                                    |
 ^ URL          | %%https://api.mysmartgrid.de:8443%%/sensor/<sensor id>  | ^ URL          | %%https://api.mysmartgrid.de:8443%%/sensor/<sensor id>  |
-^ Body         |+Request Body |
   {   {
     config : {     config : {
-       device:    <device id>, +       device:   <string(32) - device id>, 
-       function:  <sensor name>, +       function: <string(16) - sensor name>, 
-       class:    <electricity,...>]+       class:    <string(10) - this field has been deprecatedand is currently being ignored by the server>, 
-       [ type    <analog,s0,...>]+       voltage <integer    - this field has been deprecatedand is currently being ignored by the server>, 
-       [ function: <name>]+       current <integer    - this field has been deprecated, and is currently being ignored by the server>, 
-       [ voltage 230]+       phase   <integer    - this field has been deprecated, and is currently being ignored by the server>
-       [ current <int]>, +       constant: <integer    - this field has been deprecated, and is currently being ignored by the server>, 
-       [ constant: <int>]+       type    <string(16) - this field has been deprecated, and is currently being ignored by the server>, 
-       enable:   <0,1>], +       enable:   <integer    - this field has been deprecatedand is currently being ignored by the server>
     }     }
   }   }
 | |
-^ Response     +^ Response Body 
   {   {
-    timestamp: <server current time>+    timestamp: <unixtime - server current time>
   }   }
 | |
Line 140: Line 192:
 == Sensor Measurements Registration == == Sensor Measurements Registration ==
  
-Reports sensor measurements to the server.+Reports sensor measurements to the server. The measurement values are saved in RRD files in Wh (watt-hour).
  
 ^ Method       | POST                                                    | ^ Method       | POST                                                    |
 ^ URL          | %%https://api.mysmartgrid.de:8443%%/sensor/<sensor id>  | ^ URL          | %%https://api.mysmartgrid.de:8443%%/sensor/<sensor id>  |
-^ Body         |+Request Body |
   {   {
-    measurements: [[<timestamp1>,<value1>][<timestamp2>,<value2>], ... ,[<timestamp n>,<value n>]]+    measurements: [ 
 +      [ <unixtime - timestamp of the first measurement>, 
 +        <integer  - consumed energy in Wh (ever increasing value)measured at the first timestamp> ], 
 +      ... 
 +      [ <unixtime - timestamp of the measurement n>, 
 +        <integer  - consumed energy in Wh (ever increasing value), measured at the timestamp n> ] 
 +    ]
   }   }
 | |
-^ Response     +^ Response Body 
   {   {
-    response: ok+    response: <string(2) - "ok">
   }   }
 | |
-^ Error Response |+^ Error Response Body |
   {   {
-    response: <error message>+    response: <string(200) - the error message>
   }   }
 | |
 \\  \\ 
-timestamp: unix timestamp (long) 
- 
-value: consumed power (increasing value) kW/h 
- 
-values are save in rrd-file as Ws (Wattseconds) 
  
 == 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: <device firmware version> +
-  X-Token:   <sensor token>+
 | |
 ^ Attributes   |  ^ Attributes   | 
-  resolution  the resolution of the measurement results (minute, 15min, hour, day, week) +  start      = <unixtime - first timestamp of a period of time> 
-  unit        the unit in which the measurement results will be shown (watt, kwhperyear, eurperyear) +  end        = <unixtime - last timestamp of a period of time> 
-  start       first timestamp of a period of time +  resolution = <the resolution of the measurement results (minute, 15min, hour, day, week)> 
-  end         last timestamp of a period of time +  unit       = <the unit in which the measurement results will be shown (watt, kwhperyear, eurperyear)> 
-  interval    an alternative way of representing a period of time that ends right now (minute, 15min, day, week)+  interval   = <an alternative way of representing a period of time that ends right now (minute, 15min, day, week)>
 | |
-^ Response     +^ Response Body 
   {   {
-    measurements: [[<timestamp1>,<value1>], [<timestamp2>,<value2>], ... ,[<timestamp n>,<value n>]]+    measurements: [ 
 +      [ <unixtime - timestamp of the first measurement>, 
 +        <integer  - consumed power measured at the first timestamp> ], 
 +      ... 
 +      [ <unixtime - timestamp of the last measurement>, 
 +        <integer  - consumed power measured at the last timestamp> ] 
 +    ]
   }   }
 | |
 \\  \\ 
  
- +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. 
-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. **Query 1: ** Measurements performed during the past 1 hour, in minute resolution, and in watt.
webserviceinterface.1339491185.txt.gz · Last modified: 2012/10/30 10:42 (external edit)