REST, AJAX, JSON, Microformats

Scott Chapman

Mischko Systems

This document is copyright © Scott Chapman, 2006 (scott@mischko.com).  All rights reserved.  Please contact me if you desire to use it.

What we will cover

We are going to discuss the design behind the Web. There is one and it's very rarely mentioned in books on web development. This relates very closely to the new trend in web development which is AJAX. We'll discuss AJAX is and how it relates to REST. We'll also briefly discuss a simple data transfer format called JSON and a system of standardized HTML classes called Microformats.

Understand the design

REST (Representational State Transfer) is the architectural style behind the Hypertext Transfer Protocol. It's the understanding of how the protocol was designed to be used, as presented by the designer, Roy Fielding. He introduced the term in his doctoral dissertation. This understanding is critical if you want to do your job right as a Web developer.

I heard a great quote at the Open Source Convention up in Portland this year: "Understand one layer of abstraction below the one you’re working in."

Web developers must have a solid understanding of Hypertext Transfer Protocol, not just the stuff that goes over the top of it.  Can you answer the question, "How do I properly I name my web pages?" or, "What’s the difference between the Hypertext Transfer Protocol methods, GET, PUT, POST, and DELETE and how do I use them?"  When we’re done with this presentation, you’ll be able to answer these questions better.  There is a "right" way to do this. You won't read about it in most books on web development but I hope that changes in the future.

Representational State Transfer

When you deal with web pages, the way to think of it is that you're dealing with "representations of resources".  A resource is only a concept, such as a person (represented by their information in an address book) or a performance by a local band (represented by a poster on a bulletin board).  So you're transferring the current state of these resources around, and modifying their state.  That’s essentially what’s meant by "Representational State Transfer".

Resources and Methods

The Hypertext Transfer Protocol allows you to:

As we've seen, a resource is a noun - a person, place, thing, or idea. We identify them on the Web with http://server.com/something - a resource indicator.

We view or modify these resources with the different methods in the protocol.

HTTP - like a database

For those familiar with SQL and databases, these are the same things you do with a database:

SQL DatabaseHypertext Transfer Protocol Method
INSERTPOST
SELECTGET
UPDATEPUT
DELETEDELETE

Bad example - Verb Resource :(

I have an address book with three addresses in it and I want the third one.

I could have a URI like this:

http://site.com/getAddress?id=3 <== wrong

"getAddress" is a verb, not a noun

Good example - Noun Resource - Verb Method :)

It should be:

http://site.com/addresses/3

Use the Hypertext Transfer Protocol the way Roy intended:

There are other methods as well. We won't cover them here.

Repeatable GET's

GET must not change anything in the state of the resource. It's "safe".  It is designed to be "idempotent", meaning you can repeat it endless numbers of times and always get the same results. 

Google released their Google Web Accelerator - a proxy service which grabbed all the links on a web page and cached them. www.37signals.com did not make their web site with Idempotent GETs.  Some of those links used GET to deleting records from databases on the server. Imagine explainging that to your boss!

Use the correct Result Codes

When you GET a web page from a web server, the response headers include a a result code. Typically it’s 200 meaning the server was able to fulfill the request for you.

If you send a POST method in your request, the response includes a 201 response, meaning the server created the resource you requested.

There are also result codes, such as the ubiquitous 404, indicating things didn’t go well.

Web browsers don't do Hypertext Transfer Protocol?

...not all of it, anyway.

AJAX

It used to be that a person submitted a web form and got an entire new page back.  This is like old-time "batch processing"; submit your pile of punched cards and get back a big printout some time tomorrow afternoon.  That is, the browser POST'd the form data to the server. The server dealt with the form data then redirected the client to a new page.  This is Hypertext Transfer Protocol under the browser’s control.

Now, a user can click a button and javascript turns the form into a data format (such as XML or JSON) and sends it to a server.  Content is received back from the server and some portion of the current page is updated accordingly. Have you been to Google and had it suggest things you are looking for as you type?  It is sending keystrokes to the server periodically and getting suggestions back, virtually in real-time, and you can keep typing while it does this.  This is Hypertext Transfer Protocol under Javascript’s control. AJAX gives web developers more control over the Hypertext Transfer Protocol.

AJAX gives users a more interactive experience.

AJAX stands for stands for "Asynchronous Javascript and XML", which is not terribly accurate. The transfer can be done synchronously and XML is not required. A better way to understand it might be "Javascript Controlled Data Transfer".

Asynchronous vs. Synchronous

Asynchronous means things can be done in non-sequential order. More than one can be going at the same time. Synchronous means, "in order". One has to finish before the next one starts.

Javascript

Javascript does the work. A paradigm shift is occuring here as Javascript is becoming the application, not just a way of doing special effects.

Javascript uses an XMLHTTPRequest object to control the HTTP data transfers. Microsoft invented XMLHTTPRequest in 1999.

XHR can only transfer data to and from the web server that the Javascript came from.

You can not access local files with Javascript, therefore, you can't upload files to the server using XHR. Must be done the old way.

Hypertext Transfer Protocol

You don't have to do anything to the infrastructure to make use of it.  It uses existing Hypertext Transfer Protocol so it uses existing Hypertext Transfer Protocol security, caching, cookies, etc.  With AJAX the Hypertext Transfer Protocol is under Javascript’s control rather than the browser’s.

Data Transfer

Data is transferred to the server and back.  AJAX implies XML for this.  There are good tools to handle and parse XML in virtually all server-side programming languages and in Javascript.  However, parsing XML can be somewhat tedious (just ask your computer) and it’s overkill for most data transfer.

JSON

Microformats

<span class="vevent">
 <a class="url" href="Hypertext Transfer Protocol://www.web2con.com/">
  <span class="summary">Web 2.0 Conference</span>: 
  <abbr class="dtstart" title="2005-10-05">October 5</abbr>-
  <abbr class="dtend" title="2005-10-08">7</abbr>,
 at the <span class="location">Argent Hotel, San Francisco, CA</span>
 </a>
</span>

Another new thing based in mature technology is known as microformats.  Microformats are just that, small chunks of formatting, which make it easier to share information with others.

"Microformats are a way to enable "smart scraping" of web pages, so that you can create tools and scripts that losslessly extract machine-readable information from cleanly-formatted, human-readable HTML."

AJAX caveats.

How do you bookmark your place in an application when the page never changes URI or keep a history so that the Back button works?

How does a blind person deal with this new paradigm?  Their browsers don’t do Javascript.

What about search engines?

"Graceful degradation" now means working in two different paradigms.  In the "old days" of web development we had to keep more than one version of a web site because of browser incompatibilities, but they were in the same paradigm.  Now we have to have an interactive version and a batch-oriented version, essentially.  The AJAX libraries help with this but it’s not pretty.

Kludgeville is complicated

AJAX Toolkits

  • Abstract away Javascript differences
  • Help in handling issues such as bookmarking & history
  • Not always REST compliant.

There are some Javascript toolkits out there that are making life nicer for AJAX developers such as Dojo, Mochikit, script.aculo.us, YUI, Prototype and others.  They help with many of the issues AJAX brings up as well as providing some great functionality. 

I have found that some of them do not support all four of the basic Hypertext Transfer Protocol methods.  This is something to watch out for if you’re intending to make RESTful applications.  They occasionally don’t understand the other 2xx results codes as well.

Demo

Demo

AJAX Client Engine (ACE) - Hypertext Transfer Protocol://lishen.name  (modified to work with 2xx response codes).

JSON Javascript Library - Hypertext Transfer Protocol://www.json.org (modified so it doesn’t extend javascript object prototype.)

Handler.js is from the book Javascript The Definitive Guide - Hypertext Transfer Protocol://examples.oreilly.com/jscript5/

Python – Server side scripting language - Hypertext Transfer Protocol://www.python.org

Simplejson - Python JSON library – Hypertext Transfer Protocol://cheeseshop.python.org/pypi/simplejson

Cherrypy 3.0b2 – Python web server - Hypertext Transfer Protocol://www.cherrypy.org

cp_rest_resource – Cherrypy REST Resource module - Hypertext Transfer Protocol://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/444766 - highly modified.

Sqlite 3 – Great little database that doesn’t require a server but does SQL – Hypertext Transfer Protocol://www.sqlite.org

APSW – Another Python Sqlite Wrapper – Python interface to Sqlite – Hypertext Transfer Protocol://www.rogerbinns.com/apsw.html

Firefox with FireBug and Live Hypertext Transfer Protocol Headers - To debug XHR calls

Wrapup

It's good to have a better understanding of what the designer intended. We think his thoughts after him and thereby stand on the shoulders of others.

Now you can design your Web architecture the right way: URI's are Nouns. The protocol provides the Verbs.

Links

In the handout

REST

Roy Fielding: Hypertext Transfer Protocol://www.ics.uci.edu/~fielding/

Good summary of REST: Hypertext Transfer Protocol://www.peej.co.uk/articles/rest.html

REST Wiki: Hypertext Transfer Protocol://rest.blueoxen.net/cgi-bin/wiki.pl

REST on Wikipedia: Hypertext Transfer Protocol://en.wikipedia.org/wiki/Representational_State_Transfer

Building Web Services the REST Way Hypertext Transfer Protocol://www.xfront.com/REST-Web-Services.html

AJAX

AJAX on Wikipedia: Hypertext Transfer Protocol://en.wikipedia.org/wiki/Ajax_%28programming%29

The article: Hypertext Transfer Protocol://adaptivepath.com/publications/essays/archives/000385.php

Ajaxian: Hypertext Transfer Protocol://www.ajaxian.com/

Mozilla’s page on AJAX: Hypertext Transfer Protocol://developer.mozilla.org/en/docs/AJAX

AJAX Patterns: Hypertext Transfer Protocol://ajaxpatterns.org/

JSON

JSON on Wikipedia: Hypertext Transfer Protocol://en.wikipedia.org/wiki/JSON

RFC 4627: Hypertext Transfer Protocol://tools.ietf.org/html/rfc4627

Douglas Crockford: Hypertext Transfer Protocol://crockford.com/, Hypertext Transfer Protocol://en.wikipedia.org/wiki/Douglas_Crockford

Microformats

Hypertext Transfer Protocol://microformats.org/

Hypertext Transfer Protocol://en.wikipedia.org/wiki/Microformats

Hypertext Transfer Protocol://developers.technorati.com/wiki/MicroFormats

Hypertext Transfer Protocol://www.xml.com/pub/a/2005/03/23/deviant.html

Recommended Reading

"Hypertext Transfer Protocol Developers Handbook" by Chris Shiflett for the details.

RFC 2616 - Hypertext Transfer Protocol://www.ietf.org/rfc/rfc2616.txt