Official website

Thursday, August 18, 2016

Consuming RESTful data, create widgets and more

A common way to offer server-generated data to browsers, so that it can be used in client-side JavaScript is by formatting the data as JSON, and making it accessible through its own URL. A web server that respects itself, even a lightweight like Jubito, should conformed with these standards.

Until now, the core of Jubito was loading data from the server using a HTTP GET request over jQuery.get(). The return type was a simple html. In fact, still used and applied when mode is set to html (i.e. http://localhost:8080/www/?cmd=<commands>&mode=html). By default is text, or by setting mode to text. In case of html, the only element presented is the '<br />'. The main "disadvantage" is that there is no object to handle and each command need its own call, or a manipulation of the result in case of multiple commands (e.g. splitting the breaks '<br />').

In this post, I'm going to present native APIs for consuming data from the framework and the web. That way we'll be able to customize Jubito by creating widgets and UIs.

Before we begin, let's do some REST style examples from the browser in order to understand the behavior. URI has a typical structure and addressed like this:
http://<host>:<port>/www/?cmd=<sequence of commands as parameters delimited by ampersand>&<mode=json> 
e.g.: http://localhost:8080/www/?cmd=judo%20serial%20state%&%judo%20server%20state&%whereami%&%whoami%&mode=json


Explaining the functionality of each command:
judo serial state is an API call that returns the state/status of the serial port.
judo server state is an API call that returns the state/status of the web server.
%whereami% is a built-in function that returns the user status.
%whoami% is a built-in function that returns the user login.

Parameters in API respond:
1. Pair name - A simplified name of the requested command
2. Key - Represents the requested command
3. Value - Result of the requested command

For more information about built-in functions and API please visit Wiki

Next step is to create a jQuery.ajax() request and see how to consume the response data. It provides a simple process of fetching and parsing JSON data through Ajax. An ideal and straightforward way to achieve our goal for tailor made widgets and UIs.

Sample HTML:
<!DOCTYPE html>
<html>
 <head>
  <meta charset="utf-8" />
  <title></title>
  <script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/2.2.2/jquery.min.js"></script> 
 </head>
 <body>
  <script type="text/javascript">
   $(document).ready(function() {
    getData();
   });
   
   setTimeout (function () {
    $("#data").empty();
    getData();
   }, 10000);
   
   function getData () {
    $.ajax({
     type: 'GET',
     contentType: 'application/json; charset=utf-8',
     dataType: "json",
     // requested built-in functions: %whereami% %whoami% %todayconditions% %todaylow% %todayhigh% %about%
     // request on judo API: judo server state
     // wiki https://github.com/jambelnet/janet-framework/wiki
     // uri form: <host>:<port>/www/?cmd=<sequence of commands as parameters>&<mode=json>
     url: "http://localhost:8080/www/?cmd=%whereami%&%whoami%&%todayconditions%&%todaylow%&%todayhigh%&judo%20server%20state&%about%&mode=json",
     }).done(function (data) {
      var template = 'Status: ' + data.whereami.Value + '<br/>User: ' + data.whoami.Value + '<br />';
      template += 'Conditions: ' + data.todayconditions.Value + '<br />';
      template += 'Low: ' + data.todaylow.Value + 'C&deg;<br />';
      template += 'High: ' + data.todayhigh.Value + 'C&deg;<br />';
      template += 'Server status: ' + data.judo_server_state.Value + '<br />';
      template += 'About: ' + data.about.Value + '<br />';
      
      $("#data").append(template);
     }).fail(function() {
      alert( "Oops!" );
     });
    }
  </script>
  
  <pre id="data"></pre>
 </body>
</html>
http://hilite.me/

The sample above will serve a simple page with data displayed and refreshed every 10 seconds:


Another powerful feature which you may find interesting, is the HTTP GET request supported by the API. It provides raw data from any endpoint.
judo http get <endpoint>


An example of its use can be found here on how to send and read data from RaZberry Z-Wave controller.

So, to recap, there is a lot of new things to expect, but till then, you should probably start honing your skills and finally create your own UI or a widget to the existing.


I tried to describe this post as much as possible less technical, in order to be understood by beginners.