architecture - What am I not understanding about REST?

Question

I'm building a framework and want developers who build with it to have the ability to allow parts of it to both share data with other sites and allow other sites to add/edit/delete data.

For example, if someone makes a site that has book reviews, authors, quotes, code examples, comments, etc. the developer could make e.g. "book reviews" read-only for other sites and "comments" readable by other sites and writable by certain sites/users. The idea is to use the framework to build applications that can easily be interconnected with other applications.

I envision enabling all interaction with the site via POST and GET which would look something like this:

• /books.php?category=ruby (returns an XML collection of books about ruby)
• /books.php?id=23 (returns the XML for a specific book)
• /books.php?action=add&title=AdvancedRuby&description=....&securityId=923847203487
• /books.php?action=delete&id=342&securityId=923847203487

Other applications could also "discover and consume" what a certain site has to offer by doing this:

• /discover.php (returns XML of all public classes and actions available)

Really this is all I need to enable the framework to be a way for developers to quickly create loosely connected sites.

What I want to know is, before I begin implementing this, are there significant/interesting parts of REST that I do not yet understand which I should be building into the framework, e.g.:

• REST requires GET, POST, PUT and DELETE. Why would I ever need "PUT" and "DELETE"? Am I locking myself out from taking advantage of some standard if I dont' use these?
• My "discover.php" file functions similarly to a WSDL file in web services. I am surprised in descriptions of REST there seems to be no standardized way of discovering the services that a RESTful service offers, or is there?
• If a client website tries to e.g. add a book to a server website and does not get any "success" response back, it would simply try again until it got a response. The server website would simply not add the same book twice. This is my understanding of data integrity in REST, is there more to it than this?

• eventually I want to have multiple sites that have the same rich classes e.g. "BookReview" so that a client site would be able to execute code such as this:

  $bookReview = new BookReview("http://www.example.com/books.php?id=23"); $book->informAuthor("a comment about your book review was posted on our site...");

and the server site would send an e-mail off to the author of that review. Is this type of type interaction a component of the RESTful philosophy or is REST simply the exchange of data via XML, JSON?

Answer 1

Am I locking myself out from taking advantage of some standard if I dont' use these?

You are yourself locking out from the HTTP standard. Of course you can use GET parameters to do the same thing. It's just not REST then, but something RPC-Like.

May I suggest the book RESTful Web Services by Leonard Richardson and Sam Ruby? It's quite fun to read and shows differences between the different approaches.

To answer your questions in a bit more detail: It's up to you to decide which way you go. In theory you can do all the same stuff with both RESTful and RPC-like approaches. With RESTful you use the underlaying HTTP protocol to be the protocol. With RPC you use HTTP just as a means of transportation and hide the work orders somewhere in the transported data. That leads to (unrequired) overhead.

Just look at two of your examples:

• /books.php?action=add&title=AdvancedRuby&description=....&securityId=923847203487
• /books.php?action=delete&id=342&securityId=923847203487
  • There's POST and PUT or DELETE, why have action=add and action=delete?
  • There's HTTP authentication. Why invent a - possibly less secure - securityId?
  • BTW: You shouldn't allow changes to data via GET. That's just something that shouldn't be done (another topic, though ;) )