Monday, February 11, 2013

FR001: Support for RESTful Web Services and JSON in CIOS

Feature Review #001: Support for RESTful Web Services and JSON in CIOS 

Starting with CIOS Version IBM Cast Iron has expanded support for RESTful web services including new activities for parsing the JSON message format.  Web APIs built around RESTful architectural patterns are becoming more and more prevalent in Cloud Based IT Systems.

First a Little bit of Background on REST and JSON


REpresentational State Transfer (REST) is a concept that was laid out by Roy Fielding one of the authors of HTTP in his Ph.D. dissertation.  It is the now ubiquitous architectural pattern that the modern Internet is built around.  Chapter 5 of Fielding's dissertation is the best resource for the clinical definition of REST.  However, REST is an architectural pattern not a protocol and the REST architectural pattern is not limited to the modern interpretation of a RESTful web service.


JavaScript Object Notation is a message format that is derived from the JavaScript syntax for defining objects.  JSON is often used in Web APIs because it is a lightweight human readable alternative to XML which does not require a parser to be interpreted in JavaScript.  Because of those properties it is a very popular message format for Web APIs that are intended to be called from a web browser.

Modern RESTful Web APIs

Whereas SOAP based Web Services strive for interoperability through rigidity, RESTful Web APIs strive for interoperability through simplicity.  Rather than using a complex well defined protocol like SOAP, RESTful Web APIs use simple message formats based on XML or JSON that are exchanged using standard HTTP methods.  This lightweight simplicity grew from necessity, modern Web APIs evolved as a means for building web applications in JavaScript,  so they can easily be called from web browsers and mobile platforms.  Because RESTful APIs use simple HTTP requests and self describing data formats (typically XML or JSON) and because there is as of yet no formal standard for documenting these APIs, working with RESTful APIs is often an autodidactic experience.  If you need to know what fields a call will return you can make the call and see what comes out, etc.

SOAP based Web Service are typically implemented on top of of the HTTP protocol (There are some platforms that support SOAP over JMS or even SMTP, but by nature they are a level on top of the underlying transport).  RESTful Web APIs are implemented at the HTTP layer rather than on top of it.  They allow clients to interact with the server using the features if HTTP, including HTTP methods (GET,  PUT,  DELETE,  POST, HEAD, OPTIONS, etc.), URIs, query strings, headers, etc.
  • URI: Web APIs generally use Uniform Resource Identifiers (URI) to identify resources that a client can interact with.  Addresses are typically hierarchical and are used to identify a class of resources with its name, and a single entity underneath it by its unique identifier.  For example you my have something like /books/{isbn}, or even a deeper hierarchy /library/branches/{branch-id}/books/{isbn}, where branch-id uniquely identifies a branch within a library system and isbn uniquely identifies a book.
  • Methods: Generally, the actions that can be performed on a resource are mapped to HTTP methods.  GET to retrieve a resource, PUT or POST to create or change a resource, DELETE to delete it, etc.  See RFC2616 Section 9 for more details on HTTP/1.1 methods. 
  • Query Strings: Query strings are the standard way to pass parameters in HTTP GET requests.  A query string is the part of the URL between the ? and either a # or the end of the URL.  And typically take the form name=value&name2=value2.  Values passed via query string must be URL encoded.  See RFC3986 for more details on URLs. 

What's New in Version 6.3?

Version 6.3 includes several enhancements to existing activities as well as new activities to better support RESTful Web APIs. 

New Transform Activities for JSON

Read JSON Activity

The Read JSON Activity parses JSON input and converts it to xml.  This new activity works much the same way the Read XML or Read Flat File Activities work.  You select a schema and then you map a flat string into the Map Inputs, the Map Outputs will come in the form that you specified.  For the Read JSON activity you also have the option of specifying a sample JSON or XML message and the activity will determine whether your have specified JSON or XML, parse the sample message and learn the schema.  See below for an example of specifying a sample JSON message:

The sample message functionality also supports sample XML messages.

Write JSON Activity

The write JSON activity converts XML to the JSON format.  Much like the Read JSON activity you can specify either an existing schema in your project or a sample message.  Below is an example of an XML sample message:

New HTTP Activities

Invoke Activities

As you can see above there are a lot more HTTP activities than there were before.  These new activities are not fundamentally different than there counterparts in previous versions of Cast Iron.  However, the new activities retain the functionality that was there before while adding new features that make writing RESTful Web APIs much easier.  The Invoke Request activity is the general HTTP Request activity and functions much like the old HTTP Post Request Activity with some usability enhancements for path parameters, query strings, and HTTP Headers, see the Receive Request below for more details on what the changes look like and how they are used.  The Get Request, Post Request, Head Request, Put Request, and Delete Request all function similarly to Invoke Request, however there is no need to specify the HTTP method as it is implied by the activity name.

Receive Request

The Receive Request activity has been updated to more easily support RESTful Web APIs.  Most of the functionality was there already but there have been a number of usability enhancements that make it easier to support things like path parameters, query strings, and HTTP Headers.  See the screenshots below for examples of the changes and how they are used:

The new configure pane allows users to specify path parameters and query string values as well as allowing the user to choose which methods this activity will listen on.  Here we specify a path parameter isbn, as well as the query parameters title and year.
The Request Headers Pane allows users to specify headers to give easier access to the headers  that clients specify.  Here we add two headers, username and token, which can be specified by clients calling this service.

Finally, putting it all together you can see that the  username and token headers are exposed in the httpheaders section, the isbn path parameter is exposed in the new pathParameters node and the query parameters title and year are exposed in the queryParameters node.  There is no longer a need to write javascript to parse query strings, or xpath expressions to search for headers.

Send Response

The Send Response activity functions much as it did before, with some usability enhancements for setting response headers.

Putting it all Together

These new activities are not major changes to how Cast Iron works, but all in all they provide much needed functionality for RESTful Web APIs.  The HTTP enhancements provide huge usability upgrades that make it much faster and easier to deal with path parameters, query strings, and HTTP headers and methods.  The Read and Write JSON activities supply the necessary tools for dealing with the JSON format which along with XML are the standard message formats in RESTful Web APIs.  All of these small improvements lead to a long awaited major gain in the ability to call and and provide Web APIs.

No comments:

Post a Comment