RESTful Web Services

Appendix A. Some Resources for REST and Some RESTful Resources

The World Wide Web is the largest distributed application ever created, consisting of billions of resources. I’ve spent this book showing you how to seamlessly integrate a few new resources into this global application. Now I’m going to create a few links of my own. This appendix is a bit of hypermedia that connects this book to other discussions of REST, and to real live web services.

Standards and Guides

These are just a few of the sites that have helped me make sense of the programmable web.

HTTP and URI

• The HTTP standard (RFC 2616).

• The URI standard (RFC 3986).

• The WEBDAV standard (RFC 2518), if you’re interested in extensions to HTTP’s uniform interface.

• The Architecture of the World Wide Web introduces concepts like resources, representations, and the idea of naming resources with URIs (http://www.w3.org/2001/tag/webarch/).

• Universal Resource Identifiers—Axioms of Web Architecture.

RESTful Architectures

• The Fielding dissertation: Architectural Styles and the Design of Network-Based Software Architectures.

• The very active rest-discuss mailing list.

• The RESTwiki.

• Joe Gregorio’s “REST and WS” compares the technologies of REST to those of the WS-* stack while showing how to create a RESTful web service interface; if you don’t care about the comparison part, try “How to create a REST Protocol” by the same author.

• Joe Gregorio has also written a series of articles on REST for XML.com.

• Duncan Cragg’s The REST Dialogues: This series of weblog entries is a thought experiment that re-envisions an RPC-style application as a web of interconnected resources (though it doesn’t use those terms).

• Paul Prescod’s Common REST Mistakes.

Hypermedia Formats

• The XHTML standard, which is just a set of small changes on top of the HTML standard.

• The microformats web site and wiki.

• The URI Templates draft.

• The Web Applications 1.0 standard, which forms the basis of the forthcoming HTML 5. I think the most interesting part of the standard is Web Forms 2.0, which greatly improves HTML’s hypermedia capabilities.

• The WADL standard, maintained at the development site for the Java WADL client.

Frameworks for RESTful Development

• As I showed in Chapter 7, Ruby on Rails makes it easy to expose RESTful resources. The second edition of Agile Web Development with Rails by Dave Thomas et al. (Pragmatic Programmers) is the canonical reference for Rails.

• David Heinemeier Hansson’s keynote at Railsconf 2006 shows how Rails moved from a REST-RPC philosophy to one based on RESTful resources.

• The Restlet framework for Java can model any RESTful architecture, not just the resource-oriented web services covered in this book. As I write this, a Java standard for RESTful web services has just begun development as JSR 311.

• Django for Python: As of the time of writing, a free Django book was in development.

Weblogs on REST

The REST community is full of eloquent practitioners who argue for and explain RESTful architectures on their weblogs. I’ll give out links to just a few. You can find more, in true REST fashion, by following links.

• Mark Baker

• Benjamin Carlyle

• Joe Gregorio

• Pete Lacey

• Mark Nottingham

• RESTful Web Services co-author Sam Ruby

Services You Can Use

The web is full of RESTful resources, but some are more technically interesting than others. Behind every RSS and Atom feed, behind every weblog and podcast, is a RESTful resource: an addressable, stateless “target of a hypertext link” that’s full of links to other resources. You might think it’s cheating to count these as RESTful web services. It’s not. The world is full of Big Web Services that could be, or have been, replaced with a set of syndication feeds.

But you’re probably not looking in this appendix for a list of interesting syndication feeds. You’re probably interested in services that have more architectural meat to them. In this section I focus on RESTful web services that let the client create and modify resources. Read-only resource-oriented services are very common and fairly well understood. So are read/write REST-RPC hybrids. Read/write RESTful services are relatively rare, and those are the ones I want to showcase.

Service Directories

If you’re trying to write a client, and you want to see whether there’s a web service that does what you need, I refer you to one of these directories. You might find a RESTful resource-oriented service that works for you, or you might find an RPC-style or REST-RPC service you can use.

• ProgrammableWeb is the most popular web service directory. It tracks both the APIs that make up the programmable web, and the mashups that combine them. Its terminology isn’t as exact as I’d like (it tends to classify REST-RPC hybrids as “REST” services), but you can’t beat it for variety.

• By contrast, servicereg.com hardly has any services registered with it. But I think it’s got promise, because it’s not just a web service directory: it’s also a web service. The list of web services is exposed as a “collection” resource that speaks the Atom Publishing Protocol.

• MicroApps focuses on RESTful applications which are designed to be used as components in other applications, like Amazon S3.

Read-Only Services

As I said earlier, read-only RESTful services are very common and not very interesting architecturally. I’ll just give three examples of read-only services that do especially interesting things. You can find many more examples on ProgrammableWeb.

• irrepressible.info exposes a set of syndication feeds that help disseminate material censored by various governments.

• Audioscrobbler exposes a large dataset about music and people who listen to it.

• The Coral Content Distribution Network offers a simple interface to a distributed cache of web resources. It would also have been RESTful to have implemented this service with the interface of an HTTP proxy cache, but resource-oriented designs are more popular.

Read/Write Services

The Atom Publishing Protocol (covered in Chapter 9) is the most popular model for read/write RESTful services. There’s a partial list of APP service and client implementations at http://www.intertwingly.net/wiki/pie/Implementations, which includes existing services and software that expose services when you install them. I’d like to call out some APP services explicitly so you can see the variety.

• Many of Google’s web sites expose an APP extension called GData. Blogger, Google Calendar, Google Notebook, and other web applications also expose resources that conform to the GData protocol.

• The applications hosted on Ning expose the APP. See http://documentation.ning.com/sections/rest.php for details.

• 43 Things exposes a list of life goals as an APP collection. (It also exposes a REST-RPC hybrid service.)

• Blogmarks is a del.icio.us-like social bookmarking service that exposes lists of bookmarks as APP collections.

• Lotus Connections and Lotus Quick expose resources that respond to the APP.

There are also many public read/write services that don’t use the APP. Rather, they expose some custom set of RESTful resources through a uniform interface.

• Amazon S3, which I covered in detail in Chapter 3, lets you store data on Amazon’s server and have it serve it via HTTP or BitTorrent. Amazon charges you for storage space and bandwidth. S3 probably has the most robust business model of any web service out there: companies are using it, saving money, and making money for Amazon.

• Amazon does it again with another low-level service. Simple Queue Service lets you decouple two parts of a system by having one part put messages in a queue, and the other part read messages from the queue (http://www.amazon.com/Simple-Queue-Service-home-page/b?ie=UTF8&node=13584001&me=A36L942TSJ2AJA). You get to choose the message formats.

• The BlinkSale API exposes a set of RESTful resources for managing invoices.

• The Stikkit API exposes read/write resources for short notes to yourself.

• CouchDb is a “document database” that you access through a RESTful web service.

• The Object HTTP Mapper is a client and a server for exposing Python objects as RESTful resources.

• The Beast forum package is a Rails application that exposes an ActiveResource-compatible web service. An enhanced version of Beast, geared toward project collaboration, is called Dev’il.

• linkaGoGo is another social bookmarking site. Its resources are nested folders that contain bookmarks.

• OpenStreetMap is a project to build a freely available set of map data, and it provides a RESTful interface to a road map of Earth. Its resources aren’t images or places: they’re the raw points and vectors that make up a map. If the fantasy map service from Chapter 5 piqued your interest, you might also be interested in this real-world service and the project behind it.

• The Numbler web service exposes resources for spreadsheets, the cells inside them, and cell ranges. Its use of PUT could be a little more resource-oriented, but that’s just me being picky.

• The NEEScentral Web Services API is a rather ominous-sounding web service for earthquake engineers, hosted by the Network for Earthquake Engineering Simulation. It exposes resources for Experiments, Trials, SensorPools, SimilitudeLawGroups, and so on. I don’t know anything about earthquake engineering and I have no idea what those resources correspond to in the real world, but I understand the interface.

• Fozzy is an installable application that exposes a RESTful interface to full-text search. You can set up a Fozzy installation and then integrate search into any other application or service.

• Tasty does something similar for tagging.

• The MusicBrainz web service maintains metadata about albums of music, such as artist and track names. Unlike the other services in this section, it doesn’t use HTTP’s full uniform interface. It substitutes overloaded POST for PUT. It’s still resource-oriented, though. A client changes the state of a MusicBrainz resource by POSTing to the same URI it uses when GETting the state—not to some unrelated URI that designates an RPC-style operation.

• Many modern version control systems like Subversion and Arch operate through a resource-oriented HTTP interface. They go in the other direction from services like MusicBrainz, adopting extensions to the standard HTTP methods, defined by standards like WebDAV and DeltaV. These services have a richer uniform interface: up to 26 methods per resource (including COPY and CHECKOUT), as opposed to HTTP’s standard 8. The downside is that they’re on a different Web from the rest of us, because they don’t use the same methods. Note, though, that Arch can work using just the standard HTTP methods.