Getting real with REST

Question

I browser around for a decent example of a simple, fully REST API, to no avail. Checked on stackoverflow as well. The best I've seen is this post. Despite this, I still don't get the point. Let's take an example of an application that we all know: wikipedia.

Suppose we want to create a REST API for wikipedia. We expect the following verbs:

GET /wiki/Article_name: obtains a specified page
DELETE /wiki/Article_name: deletes the page
POST /wiki/Article_name: creates a new page
PUT /wiki/Article_name: updates a page.

Fact is: when you use wikipedia with your browser, you don't use a REST interface to navigate it. I am pretty sure that when you update a page, you never use PUT (although you are technically creating a new revision of a page, so POST makes sense). Similarly, when you delete a page, the browser does not send a DELETE.

My questions are:

• is REST also an interface "for the browser" or just for scripts ?
• should we see the HTTP world exclusively through the eyes of a REST representation? are things like GET /foo/?page=bar&action=delete still a valid point of view, or horrible mistakes of the past never to be done again ?
• should the web access and the REST interface be intermingled or separate? For example, suppose you have a AddressBook application. You can browse the address book with GET /people/, and with GET /people/1523 you obtain that single person information on the browser, maybe in a nice printable HTML. If you want to modify his card, you would do (RESTfully) PUT /people/1523, or instead have like PUT /api/v1.0/people/1523 ?
• could anyone please convince Roy Fielding to get human and provide a "5 years old child" example for a decent (in his opinion) REST API, instead of complaining about what is not RESTful (in his opinion), so that all the world can follow through?

Answer 1

EDIT1: As I see the world, for most programmers REST as a concept is going to be a consideration when creating APIs. So REST is on your to-do list when you're creating an API for consumption by machines; NOT when you're talking about webpages that humans will interact with through a browser. EDIT2: And that does not imply that the browser isn't RESTful (it is). I merely mean that where the current action is, where most of the worlds programmers (those who don't work for a browser maker) can benefit from REST is mostly in web services.

Let's take an example of an application that we all know: wikipedia.

OK, but it's not the best example -- Wikipedia is a rich website, i.e. it has rich content made for humans not computers.

GET /wiki/Article_name: obtains a specified page

DELETE /wiki/Article_name: deletes the page

POST /wiki/Article_name: creates a new page

PUT /wiki/Article_name: updates a page.

Your datastructure is based on the human usage model for Wikipedia, hence the confusion.

I'm providing a quick example of an API for Wikipedia below, hopefully it will help illustrate my point. It's made very quickly; and I do not claim it to be a good API design. :-)

Note 1: In the below API example, I'm using JSON. As far as "RESTfulness" is concerned, it does not have to be JSON, any data format that can be meaningfully exchanged via HTTP is fine. So other examples could be XML, TXT, JPEG, AVI. Broadly speaking, "RESTfulness" applies to the URL and HTTP headers, not to the page body -- the body is left free for the specific implementations needs.

Note 2: I'm pretending that Wikipedia has a internal, structured data format that gets transformed to HTML pages -- just for the sake of illustrating my view, as Wikipedia isn't really the best example to work with...

A first shot at a RESTful API for Wikipedia could be something like:

api.wikipedia.com/search/keywords

Takes a GET with search words in the URL, returns a JSON dataset of page IDs, page titles, URLs, and relevancy scores.

api.wikipedia.com/article/id/

Takes a GET, DELETE, POST, PUT, and will operate on the article with internal ID equal to "id" in the URL. Depending on the HTTP method of the request, it will:

1. GET; return article (in Wikipedia's predefined, JSON based data format.)
2. DELETE; delete article
3. POST; create new article (article must be in the request body, in the predefined JSON format)
4. PUT; update article (and whole page must be sent anew in the body)

api.wikipedia.com/media/id/

As the "article" endpoint above, but for CRUD of media such as images. .. and so forth, until all the needs of this imaginary Wikipedia API are met.

A quick glance at the imaginary API above reveals a number of problems .. and that's the beauty of REST; it is simple and does not get in the way of visualizing the data exhange.

is REST also an interface "for the browser" or just for scripts ?

EDIT3 Original text was: It is not intended for the browser, it is only for APIs intended for consumption by other clients or services that are 'machines'.

I'd like to change this to: The browser is RESTful. It is also a given, i.e. with the installed base, and the extreme amount of time it takes to get IE6 replaced, it is clear that the browsers we have today are going to be with us for a long time. And current browsers don't do anything with special with microformats or sites with XHTML for page rendition and XHTML for data transfer, they leave all that for you to do yourself via Javascript.

Thus, with current technologies, most of the new development that applies REST is in building better web services APIs. And practical considerations will make people choose to put their web service API on a different URL than their main website.

Relative to other web service technologies, REST has a significant advantage in the ease of debugging. You can just fire up a client on your PC, send a URL, and see the response right away. (OK, the same applies to some extent to many of the XML based web services; but machine-generated XML is impractical for me to 'read'.)

should we see the HTTP world exclusively through the eyes of a REST representation?

Ehh, no. The browser handles, what, 97% of today's website traffic on average?

should the web access and the REST interface be intermingled or separate?

Separate, in the example above I used api.wikipedia.com to illustrate that it's completely separate from the regular Wikipedia site. For practical considerations, such as load balancing, different release schedules, different business requirements.