What am I not understanding about REST?

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?

Solution 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 ;) )

Solution 2:

I suggest you read this post by Roy Fielding.

A highlight:

• A REST API should spend almost all of its descriptive effort in defining the media type(s) used for representing resources and driving application state, or in defining extended relation names and/or hypertext-enabled mark-up for existing standard media types. Any effort spent describing what methods to use on what URIs of interest should be entirely defined within the scope of the processing rules for a media type (and, in most cases, already defined by existing media types). [Failure here implies that out-of-band information is driving interaction instead of hypertext.]

• A REST API must not define fixed resource names or hierarchies (an obvious coupling of client and server). Servers must have the freedom to control their own namespace. Instead, allow servers to instruct clients on how to construct appropriate URIs, such as is done in HTML forms and URI templates, by defining those instructions within media types and link relations. [Failure here implies that clients are assuming a resource structure due to out-of band information, such as a domain-specific standard, which is the data-oriented equivalent to RPC's functional coupling].

You certainly can be successful using a RPC-like approach as you describe and it's easier to grasp than a 'proper REST API'. The most misunderstood aspect of REST is that, once defined, it should automatically work, you should not define go to this URI using this method to get that answer, that should all be implied by the media types you are delivering plus a means to let clients know where to find the relevant resources.