Hacker News Reader

Comment by _stephan | Hacker News Reader

Could maybe someone give a concise definition of what makes an API RESTful and explain why the AWS Query API is not RESTful and how a RESTful API would be better?

View on HN

Take a look at Wikipedia's description, for example:

http://en.wikipedia.org/wiki/Representational_State_Transfer...

Applying this to one of Vambenepe's examples of an AWS method--

"AWS mostly uses RPC over HTTP. You send HTTP GET requests, with instructions like ?Action=CreateKeyPair added in the URL..."

you can see that it's not RESTful. A RESTful version of this method would have something like "KeyPairs" in the URL path rather than in the query string, and it would use POST rather than GET to signify a create operation.

URLs really have very little to do with REST beyond uniqueness, even though it is popular in "RESTful" APIs to encode objects in URLs. A POST /keypair/create or whatever could just as well be POST /1234567890123. The important bits of REST are representations, state(lessness) and relationships or links.

I think the best place to start from would be the Fielding dissertation: http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch....

Thank you, it's nice to have another member in the REST sanity brigade: http://searchyc.com/comments/%252Brest+hypertext

Thanks for the pointer. I read the Wikipedia page, but I found the explanation of the general concept too abstract. The definition of a RESTful web service further down the page is much clearer.

However, does it really make any practical difference whether the API makes full use of all the HTTP methods (GET, PUT, POST, DELETE)? Sure, it may be a bit of an abuse of the protocol to encode everything as a GET, but since you usually don't want any caching when using such an API, does it really matter?

Yes, because when you don't play by the standard rules, it's hard to find others to play with you. Cache servers are just one example. Another example: web browsers. Note that web browsers are still useful against REST services, even if they don't have good support for PUT or DELETE.

In general, REST provides discoverability and interoperability that you don't get without a uniform interface.

I'm designing a RESTful api at the moment and using get, post, put, and delete to represent select, insert, update, and delete gives users a clear pattern when new features are added. Right now say there are just photos in my app. Post json or XML to /photos to create a new one, put to /photos/123/ to update. Now I announce that I'm adding videos. The pattern is exactly the same, the URL is just / videos. But I suppose you're right, I could achieve the same effect with ?object=video&action=createNew, but why make users learn a new vocabulary?

Reply on news.ycombinator.com