Sunday, February 24, 2008

REST API vs Query API

I think I have finally grasped the concept of the term "REST API"! Here is the article from AWS that helped me finally understand.

Unfortunately, for a long time I considered an API available via HTTP requests to be a RESTful API. I always new that the basics of REST were centered around placing the intention of your request in the HTTP headers via PUT, GET, POST, DELETE, etc. But when I would see APIs like GoogleBase, AmazonSQS, Facebook API, etc. I just reused the term "REST API" to describe them because I'd never heard it explained in another way.

Today it became clear to me the difference as I came across the term "Query API". A query API doesn't try to convey intention using HTTP headers like a RESTful API does. A query API simply says "hey put all the information you need for this request in the request itself". Personally, I prefer query APIs. Lets look at a simple example:

I want to perform the action User.delete() and my only parameter is the user_id. Here is how each type of API would handle such a request:

REST API:

http://api.myservice.com/user/123978
...along with this uri request the HTTP header would be set to DELETE

Query API:

http://api.myservice.com/user/delete/123978
or
http://api.myservice.com?action=user.delete&user_id=123978
etc.