My sympathies go out to Dr. Roy T. Fielding. He conceptualized an architecture for network-enabled applications. Then, he formalized that in his doctoral dissertation. Then, some marketers got a hold of his term, REST, and started applying it willy-nilly as marketers do. This led to a dilution of the meaning of REST. When Dr. Fielding attempted to clarify why some services complied with REST and others didn’t, detractors accused him of grasping at purist ideals that no one could realize in “real-world situations.” He vented his spleen in a post entitled “Specialization”.

Before last week, I, too, had an improper understanding of REST. I read Architectural Styles and the Design of Network-based Software Architectures more than once. I thought about it a lot. Then, I started programming Rails, didn’t think beyond its definitions, and failed to continue my analysis. If I had continued, then I wouldn’t have been throwing around the term “REST” so loosely.

I want to change that because, after the little experiment I wrote on my fork of philipmat’s webmvc, I think I now understand the power of REST in all its glory. Moreover, I understand the limitation of browsers to bridge the gap between Rich Internet Applications and the REST-shaped services they consume.

I found that the effort to bridge that gap took just a little of my own JavaScript (EcmaScript, whatever) which, in turn, used the following fairly standard libraries:

• jQuery
• JSON2
• knockout.js
• underscore.js
• uri-template (browserified)

I’ll spend the remainder of this post explaining BORAX in a little more detail and, then, the components of a BORAX-compliant Web application. Tomorrow, we can spend some time reviewing code to figure this out.

Just what is “xeri-programming?”

I thought, “Hey, AJAX was the last best thing. What can I call my thing?” Not too long after that, the word “borax” appeared in my mind. Then, I had to retrofit the letters into a meaningful statement.

I don’t care about XML (the “X” in AJAX). And, funny enough, not that many words begin with the letter “X”. However, the greek prefix “xeri-“, meaning “arid” or “dry”, jumped out at me from the dictionary. DRY means something in this wacky world of programming! So, instead of DRY, I went with xeri. I know, goofy; but, hey, I like to indulge myself every now and then.

So, altogether, “bidirectional operative RESTful asynchronous xeri-programming” just means that the communication goes both ways in a non-blocking manner that doesn’t repeat itself and complies with REST.

And, BORAX is funny.

application/json describes a format, not a media type.

I harped on this fact in my last post, but I think it bears worth repeating. Part of the beauty of REST stems from the fact that messages bear a description about the type of content they contain. Because Dr. Fielding grew the definition of HTTP to meet the demands of REST, we can use a Web browser as a good example. When your browser receives a message with the type…

text/html : it renders it as Hypertext Markup Language

image/png : it renders it as a bitmap image

application/vnx.ms-excel : it opens a save dialog for you to save the bits coming at you because the browser doesn’t know how to render the media type application/vnx.ms-excel in its own window.

The cool thing about most modern browsers: they allow you to write and install add-ons to extend their functionality. In some cases, those addons teach your browser how to handle new media types. Some examples of that:

Adobe Reader Plugin : Allows your browser to view PDF documents (media type application/pdf).

Adobe Flash Plugin : Allows your browser to view Flash movies (media type application/x-shockwave-flash)

JSONView : Allows Firefox to render JSON-formatted data in the browser

Unfortunately, when we serve the representation of a resource of a URL (i.e., serve a page), and return JSON with the mime-type application/json, we don’t give the browser any information on how to handle that content.

“No problem,” you think. “I have JavaScript that will handle the JSON for the browser!”

I would agree with you, except that JSON can contain anything. So, when you make an AJAX request to http://host/some/cool.json, you have to have the information about the structure of that JSON before you receive the response from the Web server. REST demands that the message have all the description it needs to handle the information. Your JavaScript expects something of a certain structure which you cannot verify with the only description of the content type as application/json. What we need are other media types that describe the content of the message and, if that implies that the server arranged the bits in the body of the response into a JSON-compliant format, so much the better.

The format JSON just means I can parse it with a call to JSON.parse. A media type has semantic meaning about how the receiving application should render the content. Media types don’t just let an application parse the content, it gives meaning to the structure of the parsed content.

Returning text/html all the time fixes this most of the time, but…

… that doesn’t work for JavaScript-only browser APIs like the ones for canvas and WebGL. Then, we have the same problem that we did, before.

And, to philipmat‘s point, since we programmers find embedding strings in our code, then templating languages like HAML or Mustache should elicit the same disdain.

We need a generic media type (or two) for the common forms of RIA communication

I expect that most Rich Internet Applications have the following usage pattern:

1. Visitor GETs a main page of the application; visitor can’t access page and login form is shown
2. Visitor POSTs credentials to server
   • On failure: response contains login page (go to parent step)
   • On success: response contains redirect to original page (go to next step)
3. Visitor GETs page of application
4. Broswer makes GETs and POSTs on behalf of visitor for information
   • Responses most often contain media types text/html, text/xml, or application/json
   • For text/html, JavaScript plops new content into DOM
   • For text/xml, JavaScript or browser applies stylesheet and plops transformed content into DOM
   • For application/json, JavaScript using out-of-band information generates something to plop into the DOM or affect the current items in the DOM
5. Visitor interacts with application by GETting and POSTing to various URLs
6. Visitor POSTs to logout URL (go to first step)

Also, usually, all of the return codes from the server equal 200.

The primary problem with all of this comes with the out-of-band information needed to handle the JSON-formatted content of some responses. If we could have some media type that unites the data+templating needs of most of the Web applications in existence, we could finally say, “Hey, that application uses a REST architecture!”

Like the ways that JSONView handles application/json and Adobe Flash Player handles application/x-shockwave-flash, we want a way that we can extend the browser for new media types that we can distribute through REST architectures.

BORAX attempts to provide this extensibility

BORAX wants to provide a way to do this that would not disappoint Dr. Fielding and his supporters. In short, we want to use REST over HTTP to take advantage of its strengths and provide the media types that will service the majority of an RIA’s interaction with the services it consumes.

BORAX in review {: class=clearnone}

BORAX is not a framework. BORAX barely constitutes a toolkit. It really just sits between your normal Web application and services out in the Wild Wild Web to form a REST architecture.

BORAX takes the browser and treats it like a miniature operating system.

• IO through AJAX or websockets;
• High-level drawing to a graphics buffer through rendering HTML/CSS, images, canvas, and SVG;
• Thread/work scheduling through Web workers and setTimeout/setInterval; and,
• Storage through session- and local-storage as well as remote storage through REST services.

Your BORAX-enabled application runs atop this.

Tomorrow, I will spend time working through the different functionality of BORAX by walking through the RIA steps above. Each step should provide you with a clearer understanding of REST and the limitations of this fair browser.