User Tools

Site Tools


jsonpinterface

Differences

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

Link to this comparison view

jsonpinterface [2013/08/07 09:19]
gonium
jsonpinterface [2013/09/25 15:24] (current)
mysmartgrid [Security Considerations]
Line 2: Line 2:
 ===== mySmartGrid JSONP Interface ===== ===== mySmartGrid JSONP Interface =====
  
-This page specifies the [[http://en.wikipedia.org/wiki/JSONP|JSONP]] interface that makes it possible for JavaScript clients from other Web domains to query sensor measurements from mySmartGrid. You can see the [[https://www.mysmartgrid.de/sites/all/modules/logger/demo-chart.html|example we are building here.]]+This page specifies the [[http://en.wikipedia.org/wiki/JSONP|JSONP]] interface that makes it possible for JavaScript clients from other Web domains to query sensor measurements from mySmartGrid.
  
-The HTTP requests can be performed by //<script>// tags or JQueryTheir responses contain JavaScript functions that return JSON arrays, containing pairs of timestamps and values, as seen below. +Below, we describe how the interface can be used to plot measurements on a chart using the [[http://dygraphs.com|Dygraphs library]]You can see the example we are building [[https://www.mysmartgrid.de/sites/all/modules/logger/demo-chart.html|here.]]
- +
-  function getDemoData(){ +
-    return [[1375800420,309.0909090924],[1375800480,310.90909091040004],[1375800540,303.75]]+
-  }+
  
  
 ==== How to Use ==== ==== How to Use ====
  
-Below, we describe how the interface can be used to plot measurements on a chart using the [[http://dygraphs.com|Dygraphs library]]. 
  
-The first step is to declare //<script>// tag in your HTML page, as follows.+The first step is to load the Dygraphs libraries, as follows. 
 + 
 +  <script type="text/javascript" 
 +          src="https://www.mysmartgrid.de/sites/all/modules/logger/js/dygraph/dygraph-min.js"> 
 +          </script> 
 +  <script type="text/javascript" 
 +          src="https://www.mysmartgrid.de/sites/all/modules/logger/js/dygraph/dygraph-canvas-min.js"> 
 +          </script> 
 +  <script type="text/javascript"  
 +          src="https://www.mysmartgrid.de/sites/all/modules/logger/js/dygraph/rgbcolor-min.js"> 
 +          </script> 
 + 
 + 
 +Then, you need to declare the following //<script>// tag in your HTML page.
  
   <script type="text/javascript"    <script type="text/javascript" 
Line 23: Line 31:
  
  
-The URL informed in the //src// attribute must have the following structure:+The response for the HTTP request performed by this //<script>// tag contains JavaScript functions that return pairs of timestamps and values formatted as JSON arrays, as seen below. 
 + 
 +  function getDemoData(){ 
 +    return [[1375800420,309.0909090924],[1375800480,310.90909091040004],[1375800540,303.75]]; 
 +  } 
 + 
 + 
 +The URL informed in the //src// attribute of the //<script>// tag must have the following structure:
  
 **%%https://www.mysmartgrid.de%%/jsonp/sensor/**//<sensor id>//**?**//<parameters>// **%%https://www.mysmartgrid.de%%/jsonp/sensor/**//<sensor id>//**?**//<parameters>//
Line 38: Line 53:
 | **end**          | First timestamp of the query period.     | Unix timestamp                 | Required if **start** is also informed. | | **end**          | First timestamp of the query period.     | Unix timestamp                 | Required if **start** is also informed. |
 | **interval**     | An alternative way of representing a standard period of time that ends right now, for example: the past 1 hour (60 min). | //hour//, //day//, //week// | Required only if **start** and **end** are not informed. Default: //hour// | | **interval**     | An alternative way of representing a standard period of time that ends right now, for example: the past 1 hour (60 min). | //hour//, //day//, //week// | Required only if **start** and **end** are not informed. Default: //hour// |
-| **token**        | The sensor authentication token.            | Please visit the [[https://www.mysmartgrid.de/sensor/mylist|sensors page]] | Mandatory |+| **token**        | The sensor authentication token.            | Please visit the [[https://www.mysmartgrid.de/sensor/mylist|sensors page]] | Required if your website domain is not authorized to query the sensor measurements. See security considerations below. |
 | **data_function** | The name of the JavaScript function that your code will be able to call in order to get the measurements. | A JavaScript function name. | Optional, default: //get<sensor id>// | | **data_function** | The name of the JavaScript function that your code will be able to call in order to get the measurements. | A JavaScript function name. | Optional, default: //get<sensor id>// |
 | **callback_function** | The name of the JavaScript function from your code that will be called, passing the measurements array as argument. | A JavaScript function name. | Optional | | **callback_function** | The name of the JavaScript function from your code that will be called, passing the measurements array as argument. | A JavaScript function name. | Optional |
 \\ \\
-Now the data can be used in your page. Firstly, you need to load the Dygraphs libraries: +Nowthe data can be used in your page. Please, create a //<div>//, where the chart will be placed.
- +
-  <script type="text/javascript" +
-          src="https://www.mysmartgrid.de/sites/all/modules/logger/js/dygraph/dygraph-min.js"> +
-          </script> +
-  <script type="text/javascript" +
-          src="https://www.mysmartgrid.de/sites/all/modules/logger/js/dygraph/dygraph-canvas-min.js"> +
-          </script> +
-  <script type="text/javascript"  +
-          src="https://www.mysmartgrid.de/sites/all/modules/logger/js/dygraph/rgbcolor.js"> +
-          </script> +
- +
- +
-Thenyou create a //<div>//, where the chart will be placed.+
  
   <div id="chartDiv" style="width:400px; height:200px;"></div>   <div id="chartDiv" style="width:400px; height:200px;"></div>
  
  
-Finally, you create the Dygraph object in another //<script>// tag:+Finally, create the Dygraph object in another //<script>// tag:
  
   <script type="text/javascript">   <script type="text/javascript">
Line 89: Line 91:
  
  
-==== Security considerations ====+==== Security Considerations ==== 
 + 
 +The token grants you access to the sensor. Everyone who knows the token can also query your sensor values, so you must protect it. As you can see above, our API only works via HTTPS. In order to protect the token you should not expose it to others, i.e. by embedding the JavaScript from above in unencrypted HTML pages of your application. 
 + 
 +If you do **not** want to expose the token to the user, please go to the [[https://www.mysmartgrid.de/sensor/mylist|sensors page]], edit the sensor, and enter your website domain in the list of domains authorized to query the sensor. After that, mySmartGrid will authorize any query originated from a page loaded from your domain, so that you can omit the token argument from the HTTP request. Click [[https://www.mysmartgrid.de/sites/all/modules/logger/demo-chart-domain.html|here]] to see an example. 
 + 
 +At the moment, this feature is available only for some users. If you want to use it, please send an email to [[msg-support@itwm.fraunhofer.de]]. 
  
  
jsonpinterface.1375859997.txt.gz · Last modified: 2013/08/07 09:19 by gonium