<frink>How does a _person_ use REST?</frink>

March 16, 2006 2:40 PM

Help me understand REST.

I searched my little heart out, but I'm afraid my (mis)understanding of the topic is skewing my results.

I believe I've got the basics down. URIs describe resources. To create something, you POST (XML-formatted) data to a resource's URI. To update it, you PUT data. To delete, DELETE. And to display something, you GET. Ok, cool.

Who or what exactly can use a RESTful interface? If make a database application, and I want to update a record, how to I PUT something to it? I can't use my web browser--it only supports GET and POST. What can I use to PUT or DELETE something, or must I lobby another resource to PUT or DELETE it on my behalf?

posted by deadfather to computers & internet (11 comments total)

Oof, that title totally worked in preview. And it was funny, then, too.
posted by deadfather at 2:42 PM on March 16, 2006

One way to do it would be to have Javascript (aka AJAX) do the PUT and DELETE for you. Here's an article that covers DELETE, so that should be a start.
posted by breath at 2:49 PM on March 16, 2006

The Restful Web columns on xml.com are helpful if you read them in order from the bottom to the top. I've yet to actually do anything with REST yet, but after reading several of these I finally understood (mostly) what was going on.
posted by togdon at 3:08 PM on March 16, 2006

What's your programming language of choice? In about ever major (and most minor) languages, there will be a library that implements a HTTP client. You would use this library in your programs typically to programmaticaly retrieve some content via HTTP. With that said, most of these libraries will allow you to set the HTTP Verb to all the acceptable ones so that let's you handle those other cases.
posted by mmascolino at 3:28 PM on March 16, 2006

You can't use REST from a web browser. It's for writing APIs that communicate over the HTTP protocol. You need a client that will interact with the server for you. While it is possible to implement a REST-compatible client in Javascript and HTML, REST has very little to do with HTML and web pages and browsers. It's purely about using the HTTP protocol to send and retrieve any data from another computer.

A good example of a REST API is the Atom Publishing Protocol. A desktop blogging client interacts with your blog's webserver to rerieve, create and update blog entries by sending a mix of HTTP requests to particular URLs.
posted by cillit bang at 3:34 PM on March 16, 2006

Is there any chance that web browsing clients will begin supporting PUT and DELETE? I think I understand now the current use of REST as a way to retrieve and manipulate data, but to me, it would seem that being able to interact in a RESTful manner from a web form on an HTML page would be immensely useful. Or am I still missing something?
posted by deadfather at 3:43 PM on March 16, 2006

You're still missing something. Interacting with a REST API from directly in a web browser makes no sense. Let's do a GET by typing a URL, but then what? You just have a lump of data (eg a blog entry in Atom XML) loaded into a browser. How are you going to edit it? How are you going to POST it back? etc etc. Remember, you don't have forms since all you loaded was pure XML data.

You need a client between you and the data, even if it's just simple Javascript.
posted by cillit bang at 4:07 PM on March 16, 2006

It sounds like you might be more interested in WebDAV than REST.
posted by scottreynen at 4:15 PM on March 16, 2006

"You can't use REST from a web browser."
"Interacting with a REST API from directly in a web browser makes no sense. Let's do a GET by typing a URL, but then what? You just have a lump of data (eg a blog entry in Atom XML) loaded into a browser."

This is giving the wrong picture because browser can do REST. Sure it's true that most useful software involves a more extended session when the client+server chat back and forth, and that'd require more than just HTML, but it's also true that some software uses REST and it doesn't need much chatter. Some software is just input+config=output.

For more complex examples a browser can still be capable REST client when its scripted with Javascript. Here the problems are whether Javascript makes it as easy and offers the same facilities as other programming languages. For some REST software it may, for others it might not. The general rule is that browsers work work for some situations, and for more you'll need something better than Javascript.

Your original question about browsers only supporting GET/POST is interesting. In Javascript you typically can do more. Although it's more correct to use the DELETE/PUT verbs you could just GET/POST. It's not appropriate use but lots of people do it and it's better than using SOAP. As GET isn't supposed to be destructive (it's not supposed to change the server) you could POST instructions to delete, and POST to update data.

When you talk about POST and GETing files rather than data it confuses the issue a little and starts to head into WebDAV. WebDAV is basically FTP over HTTP -- so it's file transfer with rename, move, etc. It's an API though it's not for Web Services (unless the service is just supposed to transfer files because that's all WebDAV does). REST has designed URLs, WebDAV has a file system. They're related through HTTP and I like both of them but they're not competing unless you want something like FTP.

ps. I think you understand REST and how you make URLs your interface, so some other web service techniques you might like to read about are Hessian (rules) and JSON (drools).
posted by holloway at 4:58 PM on March 16, 2006

(weird... my alt-tab menu fixes the frink elements but my window title doesn't..)
posted by holloway at 5:02 PM on March 16, 2006

Your browser is capable of doing REST. It did it when you loaded this page, it does it when you go to Google. Your browser can't get enough REST, it just RESTs all over the place.

REST is the Web, it is how it works, and (some say) why it has been so successful. REpresentational State Transfer. Web pages are a representation of a resource. This page is represented by HTML which your browser renders in a pleasant way. You move from page (state) to page (state) by following links (that's the transfer part).

REST is not about Remote Procedure Calls (RPC), Application Programming Interfaces (APIs), or Web Services. It's orthogonal to XML, to Javascript, to HTML, and to SOAP. Yes, it is orthogonal to SOAP. The "SOAP vs REST" debate is not a well-founded one (or, rather, it's not a well named debate. There are reasonable things to be said).

So what is REST? REST is what I said above. You have resources, which are a truly abstract idea. A resource could be a bit on a hard drive, a row in a data base, an abstract noun (e.g. Terrorism), whatever. Resources are sort of these ephemeral shadows that you can never truly see.

Resources make themselves known to the world through Uniform Resource Identifiers (URIs). Every resource has a URI. Using a URI you can retrieve, via HTTP, a representation of the resource. In the case of the WWW, as we usually use it, the most common representation is HTML. However, images are common too. As is XML.

You mentioned HTTP and its classic verbs: GET, POST, PUT, and DELETE. HTTP was designed, in part, by the guy who coined the term REST and as such it has REST in mind. You use these verbs and the other machinery of HTTP to interact with resources using URIs and their representations.

For example. I want to build a RESTful interface to my bookstore. It'll work as follows. You can GET http:/mybooks.com. If you pass along an Accept header of 'text/xml' I will send you back an XML file with XLinks to various categories (Computers, Home Repair, etc). If you send along any other Accept header I'll just send you boring old HTML, and assume you are a browser.

Now, say the link to Computer books from the above XML is at this URL: http://www.mybooks.com/computers/. A GET on that URL returns more XML with XLinks to subcategories. Maybe one of those categories is Ruby, now we have: http://www.mybooks.com/computers/ruby. A GET on that URL will return a bunch of XLinks to Ruby books.

Maybe there are a billion Ruby books, way too many XLinks to return. Oh well, lets use the HTTP Specification and pass along a Range header to say we only want a subset.

Moving on, lets say one of those XLinks is to a particular Ruby book: http://www.mybooks.com/computers/ruby/41234. When we do a GET on that URL maybe we'll get some RDF metadata about the book, or maybe we'll get Plain Old XML (POX) with more XLinks or whatever, it's up to the programmer.

Now, that's all find and dandy for retrieving information but what about updating it? Well, that's possible to. Maybe you POST some key/value pairs to the above Book URL to update its price. Or, say you write a Ruby book, and you PUT a complete RDF description of the book on the site. Or a book goes out of print and you DELETE it.

So, that's the general idea. You navigate and discover information using HTTP. You move from one resource to the next via URIs. URIs can be stored any old way, XLink is just one way. Your URIs could be a text value in an XML file, an attribute in an element, the return value of a Javascript function, the metadata on a JPEG file, whatever. As long as the URI is there and the consumer of the information knows where to find it. (BTW, URIs have a specific format, but they're just text. Anywhere you can store text you can store a URI).

This is the Zen of why SOAP and REST are not incompatible. SOAP is an XML based message passing specification. It turns out message passing is a good way to deal with Object Oriented stuff (look at Smalltalk). So I assume someone had the idea to crudely approximate it by encoding messages in a specific XML format called SOAP (which used to stand for Simple Object Access Protocol, but now it doesn't stand for anything). With REST your representation of a resource can be XML (usually people say POX for Plain Old XML), jpegs, HTML, Javascript, YAML, JSON, or even SOAP messages.

You mentioned above that browsers do not do PUT and DELETE. You're right, most don't. However, this is not a problem. There is an implicit amount of shared understanding amoung RESTful clients about who and what will be consuming and creating representations of resources. These clients are usually custom written code and so you'd expect that this code can handle PUT or DELETE. If your client is a web browser then you'll have to make sure you design your RESTful interface to not rely too heavily on PUT and DELETE. A lot of people tunnel PUT and DELETE over POST, when necessary.

I am sure I missed a lot of important points. Like, in REST, things should always remain stateless. Having a URI should be enough to say where you are in the system and where you can go next. REST is realized for mere mortals as HTTP, but the idea is more general than HTTP. However, when people say REST they really mean "use HTTP as it was designed to be use".

Having said that, things that are unRESTful are things that involve state. Cookies are unRESTful b/c you need a URL plus one or more cookies to retrieve a resource. Cookies are just fine as far as HTTP goes, but they are not RESTful. Also, not RESTful would be a website that drops a Flash bomb on you and expects you to navigate through a Flash interface. Flash is very unRESTful because you can't even get URLs to individual pages (i.e. resources).

An important point, mentioned above, is that REST is really about "HTTP as it was meant to be used". Yes, the web could technically work if all data transfer happened with POST. Or everything worked with GET (i.e. GET only, no POST). You could somehow shoe horn all of HTTP and its semantics into the query parameters of some bad ass URL. However, that'd be stupid and unRESTful. It turns out when you follow the design principles behind REST that things turn out to be easier to manipulate and process in a decentralized and distributed fashion.

You asked "What can use RESTful interfaces?". Generally, when people are using REST to do web services-like things, the clients are custom written code. For example, Flickr has a (bad) REST API which assumes you'll write some kind of client to manipulate your images via REST.

However, REST is realized rather perfectly on accident in the case of regular old websites. Even big-bad websites that use lots of AJAX and cookies, while not purely RESTful, are not totally unRESTful either. This is why RESTafarians often get away with saying that REST is as old as the web and is already deployed everywhere and works great, because the WWW with browsers as the client is the original web service.

Web Services stuff like SOAP (with WS-*) and XML-RPC are not very RESTful, usually. Usually they fail to be RESTful because they ignore HTTP's inherent power and just tunnel their data over it. For example, take Web Services with SOAP. Assume I wanted to talk to you on the phone. So I plug my modem into the phone jack and you do the same. Then we have our computers call each other and set up a Voice over IP link and we talk that way. Well, that sucks, why didn't we just skip all the layers of crap and use the phone directly? Or, in the case of web services, why not just use HTTP, why send complicated XML envelopes that wrap your message?

And, finally, REST is a style not a protocol or a format or a framework or an API or a library. REST is a way of using HTTP to maximize HTTP's power and, ultimately, your ability to manage resources in a distributed manner. And it just happens to be that HTTP when used right is way better at web services than everything else, almost by definition.
posted by mto at 9:40 PM on March 16, 2006