RESTful Web Services

RESTful web services

This article is about consuming WCF REST services using a javascript library and perform CRUD (Create Retrieve Update Delete) operations with a backend MV database. I have been using ScarletDME which means it also works with OpenQM.

Acknowledgements

The concepts behind this document are attributed to Shahriar Iqbal Chowdhury 15 Sep 2011 in his article at http://www.codeproject.com/KB/scripting/wcf-rest-service-with-js.aspx

Introduction

Representational state transfer (REST) is a style of software architecture for distributed hypermedia systems such as the World Wide Web. The thing about REST is that it is not tied to any particular technology or platform. The term is often used in a looser sense to describe any simple interface which transmits domain-specific data over HTTP without an additional messaging layer such as SOAP or session tracking via HTTP cookies. A REST web service is a simple web service implemented using HTTP and the principles of REST. Such a web service can be thought about as a collection of resources. The MIME type of the data is supported by the web service. This is often JSON , XML or YAML but can be anything. The set of operations are supported by the web service using HTTP methods. An easy option for the MV world is to choose JSON (Javascript Object Notation).

JSON is text - {Eur:"Eur Euro",Gbp:"Gbp Uk Pound",Huf:"Hungarian Forint",Usd:"Usd Dollar"} - is a JSON object. This was constructed by a routine in an MV database from “LIST CURRENCY DESCRIPTION” . The triviality of the transformation demonstrates that this puts text based MV right back in the game.

When we consider these RESTful services, it becomes clear that the service is something provided by the database server and the presentation becomes the domain of the web builder. From the database server perspective, we need to deliver entry points for the services that we are offering.

For example – a webpage might look like this

    <html>
    <head>
    <script>
         function doAjax() {
           dojo.xhrGet({ url : "getdata_LIST+CURRENCY+DESCRIPTION.qmw",
             load : function(resp) {
                  var o = dojo.fromJson(resp);
                  for (var attr in o){
                  var node = dojo.byId(attr);
                  if (node) {
                       node.innerHTML = attr + "--" + o[attr];
                       }}}});}
    </script>
    </head>
    <body onLoad="doAjax();">
       <div id="ajaxResponse"></div>
       <table border="0">
         <tr><td id="Gbp"></td></tr>
         <tr><td id="Huf"></td></tr>
       </table>
    </body>
   </html>

(note: this is scripted with javascript library ‘dojo’ and some of its script requirements have been removed for clarity)

This will deliver the following to the browser

Gbp--Gbp Uk Pound
Huf--Hungarian Forint

Let us examine what has happened here. The script at line 005 has requested a service "getdata_LIST+CURRENCY+DESCRIPTION.qmw" with a method of GET. This is a URL to the service provision and, in that service provision, the structure is known. The how is not important but you will notice that it has an extension of “.qmw” which delivers this request to the correct service process. The URL can be parsed by the service process and the result delivered. The URL could be changed for the service to deliver different results and the web page remains unchanged.

Notice that the returned JSON has four currencies but only two are displayed. This is because, at line 009 the script is locating the id and, if found, populating the innerhtml of that node in line 011. It is worth noting that the script is using objects delivered from a text response. If the URL is changed to "getdata_LIST+CURRENCY+RATE.qmw", the response is

Gbp--1.0000
Huf--306.7082

The presentation on the browser is now divorced from the database and changes need only occur when a different service is selected. The term is abstracting the data from the presentation.

Rest Services and their methods

There are 9 methods defined in the standards but we do not need to implement them all for all of our services. The method is delivered in the environment variable REQUEST_METHOD.

||Method||Description|| ||GET|| Requests a specific representation of a resource || ||PUT|| Update a resource with the supplied data|| ||DELETE|| Deletes the specified resource|| ||POST|| Create a resource with the supplied data|| ||HEAD|| Similar to GET but only retrieves headers and not the body|| ||OPTIONS|| Returns the methods supported by the identified resource|| ||TRACE|| Not implemented|| ||CONNECT|| Not implemented|| ||extension|| The URL structure is understood by the server||

When examining the method, we need to take care about GET because we could get that from any web page activity, not just our service. In the MV world PUT and POST are the same whereas in the SQL you would need to differentiate between insert and update.

With PUT, DELETE and POST the web requested will expect a response indicating success or failure and the web programmer will expect this. This is simply handled by sending a suitable http response code in the status field.

PRINT "Status: 503 Database Unavailable"
PRINT

When a service request is received we have the following information to help identify what the database should do.

||FIELD|| Information|| ||HTTP_REFERER|| The name of the page that issued the request|| ||REQUEST_METHOD|| See above|| ||HTTP_X_REQUESTED_WITH|| Is this an AJAX call?|| ||CONTENT_TYPE|| Populated by the ContentType var|| ||QUERY_STRING|| Data passed to the service|| ||PATH_INFO|| The name of this page|| ||URL|| The address that called the service||

This article is not intended as a tutorial for building a web site. However, it is the start of a process to abstract the data from your MV source. This means that the web site can be developed by an engineer with no knowledge of the database and, similarly, the back end routines developed without any knowledge on how the data will be deployed.

Currently, I am aware of dojo, jquery and jeasyui as contenders for the javascript library for web presentation. However, be warned, they all implement REST in different ways and without, neccessarily, following the standards. Also, be aware, that the JSON that is requested is different and dependent on how you write the javascript code or deploy the javascript librarry

RESTful Web Services

Contents