User Tools

Site Tools


webserviceinterface21

This is an old revision of the document!


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 latest mySmartGrid image to your device.

Request Message Structure

URL

https://api.mysmartgrid.de:8443/<object>[/<id>[?<parameters>]] … [<body>]

Part Description
<object> The entity being affected by the invocation
<id> The object id
<parameters> The list of parameters of the operation
<body> 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 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/<device id>
Extra Headers
  X-Digest: <string(32) - the message digest, using the device key>
Request Body
{
  key:         <string(32) - SHA-1 key used for device authentication>,
  description: <string(60) - the description of the device (optional)>,
  memtotal:    <integer - total RAM in MB (optional)>,
  memcached:   <integer - total cache memory in MB (optional)>,
  membuffers:  <integer - total buffer memory in MB (optional)>,
  memfree:     <integer - total free memory in MB (optional)>,
  uptime:      <integer - total time the device has been up and running, in seconds>,
  reset:       <integer - number of times the device has been reset (optional)>,
  version:     <integer - deprecated field, currently being ignored by the server>,
  firmware:    (optional) { 
    version:     <string(11) - firmware version, using the
                               format: 9.9.9-9, for example: 2.3.1-1>,
    releasetime: <string(14) - firmware release date and time, using the
                               format: YYYYmmmdd_HHii, for example: 20120524_1158>,
    build:       <string(40) - firmware release identifier,
                               for example: f0ba69e4fea1d0c411a068e5a19d0734511805bd>,
    tag:         <string(32) - firmware release tag in Git repository,
                               for example: flukso-2.0.3-rc1-19-gf0ba69e>
  },
  type: <the device type (flukso2, vzlogger, libklio, raspberrypi)
        (mandadory if firmware is informed)>
}
Response Body
{
  upgrade:   <integer  - flag to indicate whether or not there is a pending firmware upgrade>, 
  timestamp: <unixtime - server current time>
}


Device Removal

Removes a device and all its related data from the server.

Method DELETE
URL https://api.mysmartgrid.de:8443/device/<device id>
Extra Headers
  X-Digest: <string(32) - the message digest, using the device key>
Response Body
{
  response: <string(2) - "ok">
}
Error Response Body
{
  response: <string(200) - the error message>
}


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/<device id>
Extra Headers
  X-Digest: <string(32) - the message digest, using the device key>
Request Body The field 'config' is included only if the Flukso changed its configuration due to the information from the last heartbeat.
{
  description: <string(60) - the description of the device (optional)>,
  memtotal:    <integer - total RAM in MB (optional)>,
  memcached:   <integer - total cache memory in MB (optional)>,
  membuffers:  <integer - total buffer memory in MB (optional)>,
  memfree:     <integer - total free memory in MB (optional)>,
  uptime:      <integer - total time the device has been up and running, in seconds>,
  reset:       <integer - number of times the device has been reset (optional)>,
  version:     <integer - deprecated field, currently being ignored by the server>,
  firmware:   (optional) { 
    version:     <string(11) - firmware version, using the
                               format: 9.9.9-9, for example: 2.3.1-1>,
    releasetime: <string(14) - firmware release date and time, using the
                               format: YYYYmmmdd_HHii, for example: 20120524_1158>,
    build:       <string(40) - firmware release identifier,
                               for example: f0ba69e4fea1d0c411a068e5a19d0734511805bd>,
    tag:         <string(32) - firmware release tag in Git repository,
                               for example: flukso-2.0.3-rc1-19-gf0ba69e>
  },
  config:     (optional) {
    network:    (optional) {
      lan:        (optional) {
        enabled:  <integer>,
        protocol: <string(6)  - either static or dhcp>,
        ip:       <string(15) - iff protocol is static>,
        netmask:  <string(15) - iff protocol is static>,
        gateway:  <string(15) - iff protocol is static>,
        nameserver: <string(15) - iff protocol is static>
      },
      wifi:       (optional) {
        enabled:  <integer>,
        essid:    <string(60)>,
        enc:      <string(5)  - one of open,wep,wpa,wpa2>,
        psk:      <string(60) - iff enc is wep, wpa or wpa2>,
        protocol: <string(6)  - either static or dhcp>,
        ip:       <string(15) - iff protocol is static>,
        netmask:  <string(15) - iff protocol is static>,
        gateway:  <string(15) - iff protocol is static>,
        nameserver: <string(15) - iff protocol is static>
      }
    }
  },
  type: <the device type (flukso2, vzlogger, libklio, raspberrypi)
        (mandadory if firmware is informed)>,
}
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:   <integer     - flag to indicate whether or not there is a pending firmware upgrade>,
  timestamp: <unixtime    - server current time>,
  support: {
    user:       <string(60)  - username for the reverse SSH connection>,
    host:       <string(60)  - hostname for the reverse SSH connection>,
    port:       <integer     - port where SSH is running on host>,
    tunnelport: <integer     - port bound to the device localhost:22>,
    devicekey:  <string(700) - a Base64-encoded DSA key to be used by the device
                               for SSH authentication>,
    techkey:    <string(700) - the technician DSA key to be added to 
                               file authorized_keys on the device>,
    hostkey:    <string(700) - the host RSA key to be added to the file
                               known_hosts on the device>
  },
  config:     (optional) {
    network:    (optional) {
      lan:        (optional) {
        enabled:  <integer>,
        protocol: <string(6)  - either static or dhcp>,
        ip:       <string(15) - iff protocol is static>,
        netmask:  <string(15) - iff protocol is static>,
        gateway:  <string(15) - iff protocol is static>,
        nameserver: <string(15) - iff protocol is static>
      },
      wifi:       (optional) {
        essid:    <string(60)>,
        enc:      <string(5)  - one of open,wpa,wpa2>,
        psk:      <string(60) - iff enc is wpa or wpa2>,
        protocol: <string(6)  - either static or dhcp>,
        ip:       <string(15) - iff protocol is static>,
        netmask:  <string(15) - iff protocol is static>,
        gateway:  <string(15) - iff protocol is static>,
        nameserver: <string(15) - iff protocol is static>
      }
    },
    sensors: [
      <string(64) - id>,
      ...
      <string(64) - id>
    ]
  }
} 


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/<device id>
Extra Headers
  X-Token:     <string(32) - access token, configured by the user on the web site>
  X-Digest:    <string(32) - the message digest, using the device key>
Response Body
{
  description:  <string(60) - the device description>,
  type:         <the device type (flukso2, vzlogger, libklio, raspberrypi)>,
  sensors: [
    { meter:    <string(32) - sensor id>,
      function: <string(16) - sensor name> },
    ...
    { meter:    <string(32) - sensor id>,
      function: <string(16) - sensor name> }
  ]
}


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/<device id>
Extra Headers
  X-Digest: <string(32) - the message digest, using the device key>
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.

Method POST
URL https://api.mysmartgrid.de:8443/event/<event id>
Extra Headers
  X-Digest:  <string(32) - the message digest, using the device key>
Request Body
{
  device:    <string(32) - device id>
}
Response Body
{
  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

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/<sensor id>
Extra Headers
  X-Digest: <string(32) - the message digest, using the device key>
Request Body
{
  config : {
     device:      <string(32) - device id>,
     externalid:  <string(64) - sensor id given by the client>,
     function:    <string(16) - sensor name>,
     unit:        <string(16) - sensor unit>,
     class:       <string(10) - sensor class (either analog or pulse)>,
     voltage:     <integer    - sensor voltage in Volts (only if class is analog)>,
     current:     <integer    - sensor current in Amperes (only if class is analog)>,
     constant:    <integer    - sensor constant in pulses/kWh (only if class is pulse)>,
     description: <string(64) - a user defined description of the sensor>
  }
}
Response Body
{
  timestamp: <unixtime - server current time>
}


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/<sensor id>
Extra Headers
  X-Digest: <string(32) - the message digest, using the device key>
Response Body
{
  config : {
     device:      <string(32) - device id>,
     externalid:  <string(64) - sensor id given by the client>,
     function:    <string(16) - sensor name>,
     unit:        <string(16) - sensor unit>,
     class:       <string(10) - sensor class (one of analog, pulse)>,
     voltage:     <integer    - sensor voltage (iff class is analog and type is electricity)>,
     current:     <integer    - sensor current (iff class is analog and type is electricity)>,
     constant:    <integer    - sensor constant (iff class is pulse)>,
     type:        <string(16) - sensor type (one of electricity, water, gas)>,
     description: <string(64) - a user defined description of the sensor>
  }
}


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/<sensor id>
Extra Headers
  X-Digest: <string(32) - the message digest, using the device key>
Request Body
{
  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 Body
{
  response: <string(2) - "ok">
}
Error Response Body
{
  response: <string(200) - the error message>
}


Sensor Removal

Removes a sensor and all its related data from the server.

Method DELETE
URL https://api.mysmartgrid.de:8443/sensor/<sensor id>
Extra Headers
  X-Digest: <string(32) - the message digest, using the device key>
Response Body
{
  response: <string(2) - "ok">
}
Error Response Body
{
  response: <string(200) - the error message>
}


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/<sensor id>?<attributes>
Extra Headers
  X-Token:  <string(32) - access token, configured by the user on the web site>
  X-Digest: <string(32) - the message digest, using the device key>
Attributes
start      = <unixtime - first timestamp of a period of time>
end        = <unixtime - last timestamp of a period of time>
resolution = <the resolution of the measurement results
             (minute, 15min, hour, day, week)>
unit       = <the unit in which the measurement results will be shown>
interval   = <an alternative way of representing a period of time that ends right now
             (15min, hour, day, week)>
Response Body
{
  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, 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.

  1. Move the file to /usr/local/share/ca-certificates. You may change the file name, but the extension must remain crt.
  2. 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.

webserviceinterface21.1421157535.txt.gz · Last modified: 2015/01/13 14:58 by paalsteek