Friday, March 31. 2006
Architectural Styles and Reviews
This I think is going to be the biggest thing coming out of the Hi/Low REST debate: the understanding that REST is an architectural style. It is a method of designing your web services. Just as you can Design your building(be it a house, mall, skyscraper...) in any style you like, the same goes with how you are going to design your web application.
And because we are talking about an architectural style, it means you are free to break the rules if you like. Do you want to store state as a session ID and throw it around in a cookie? Fine! Go to! Call it "REST+Cookie State" (or perhaps, "REST - statelessness") if you like. But its style, which means the designer has latitude as to how much he or she takes from that style depending on their needs.
So with the concept of REST as an architectural style, lets take a peek at some web services: (Thanks to pwb who gave me the idea in the comments of my entry about Lo and Hi REST)
A RESTful evaluation of some webservices.
this is not a value judgement, but it is rather a way to define REST by talking about which constraints they break, and the implications of breaking each constraint.
When going through these services, it is important to note that all of these services maintain the state of the application on the client. So all of these services are RESTful to some degree.
Flickr
RESTful
- GET and POST are used properly. You must use POST to the flickr.photos.delete method, but you can GET the info of a photo.
RESTless
- The URI. Everything is handled through a single URI with a query string (like http://www.flickr.com/services/rest/?method=flickr.photos.delete). The URIs need to change to /services/rest/photo/photoid /services/rest/person/personid, etc. In doing so, the results of GET interactions could be cached by clients and proxies properly.
- HTTP Status. Errors return a 200 response code. Preventing proper caching of resources.
Notes
Sticking with POST and GET would still work for flicker, but obviously a DELETE to /services/rest/photo/photoid makes more sense then POST /services/rest/photodelete/photoid
del.icio.us
RESTful
- Good URIs; not great, but good. (http://del.icio.us/api/posts/get). del.icio.us still has the problem of the URI specifying the verb when it doesn't need to.
- Standard use of the HTTP auth.
RESTless
- Everything uses GET and URIs are named after methods. This prevents cachability, and breaks the rule of HTTP where GET methods must be safe.
Notes
No longer claims to be restful, but did at one point. I'm not the first one to point this out either. Delicious makes some use of HTTP status codes (503 if you hit the server too hard), but other times does not.
s3 (amazon)
Pure electric REST sex baby. Not surprising really, Amazon hires some smart people.
Also, Amazons documentation is a perfect example of how to properly document a REST web service.
RESTful
- Proper HTTP status codes
- Proper URIs (http://s3.amazonaws.com/bucket/object)
- Proper verbs on resources (GET, PUT, DELETE on buckets)
- Proper authentication using HTTP auth, and a bonus for exposing that on the query string if the client needs it.
- Excellent use of meta-data in the response header, including E-Tags, and special amazon extensions (prefaced with x-amz-*)
RESTless
Nothing I can see. The S3 REST API is an example of a well defined, well documented REST API.
Bloglines
- Proper use of HTTP status codes
- Proper URIs (http://rpc.bloglines.com/listsubs)
- All actions are retrieval only, and therefore follow the rule of proper verbs on resources (everything with GET)
- Authentication using HTTP auth
RESTless
- The http://rpc.bloglines.com/getitems resource has the potential to mark items as unread when passed a parameter to the query string. Ideally a POST request would be used to mark items unread, and a GET would not. Alternately, a PUT request could be used with a list of items to mark items unread.
Notes
Does not claim to be RESTful, but it mostly is.
Ebay REST API (pdf link)
RESTful
- Semi Proper URIs (http://rest.api.ebay.com/restapi), the URI really only counts for one resource, a set of search results.
- Proper Verb on the Resource (GET).
RESTless
- There is no mention in the documentation as to whether or not the Ebay API properly returns HTTP status codes, but my guess is that it does not. (Does anyone have any information on that?)





While reading Jonnay's Web Service evaluation, I stumbled on to Amazon's S3 Authentication scheme. Hey, there's a lot of similarities...
Tracked: Apr 02, 20:34