Vishful thinking…

Why is it important to follow RESTful principles when developing a REST API

Posted in Uncategorized by viswaug on September 8, 2008

When developing a RESTful API, it is important to follow the REST principles as much as possible. Sometimes it may not be apparent as to why, hopefully the following will illustrate the importance of following the REST principles. The web by itself is RESTful, REST treats everything as a resource and it has set of verbs or HTTP methods mapped to the operations that can be performed on resources.

Fetch the resource – HTTP GET
Insert a new resource – HTTP POST
Update a resource – HTTP PUT
Delete a resource – HTTP DELETE

And when you are writing your own REST API to perform one of the above operations on a resource, it is good practice to always to use the corresponding HTTP method to do so. Why is this important and when will you run into problems following the above principle? Well, let’s say that you have a HTTP GET URL endpoint that takes an identifier for a resources and actually deletes the resource instead of just fetching it. I can’t remember which one but one of the wiki implementations out there had beed doing the same where they were deleting web pages in the wiki when a HTTP GET request was made to an URL. And one fine night, the “GoogleBot” (Google’s web spider or crawler) came along and started making HTTP GET requests to that URL hoping to index the resource at that URL. This resulted in most of the web pages in the wiki being deleted and in a huge loss of information. So, your REST API will also be susceptible to such disasters if the REST principles are not followed strictly.

Following the REST principle, might be a problem when you need to send in a lot of information in the query string of the HTTP GET URL. For example, if you want to be able to fetch all the parcels inside a polygon, a representation of the polygon needs to be passed into the HTTP URL GET endpoint to be able to perform the query. In these cases, the length of the URL could become a problem. Normally, it is not a good idea to let the length of your URL exceed 1024. A lot of organizations might restrict the length of the URLs by using tools like UrlScan (this feature is built right into IIS 7.0). In these cases, you might have to end up POSTing the information to the URL, or in other words using a HTTP POST instead of HTTP GET. Actually, this is exactly what the ESRI REST API does. The JS API actually examines the length of the URL and if the length is larger than a certain number (the default is 2000), they POST the information to REST server instead of using GET(via a proxy, which i will write about soon). The ArcGIS REST server actually accepts both GETs and POSTs at the same URL endpoint since they are implemented as HTTPHandlers. Currently, the REST support in WCF does not allow the developer to accept both GETs and POSTs at the same URL endpoint.

When a different HTTP method is being used instead of the correct method, it is a good practice to do so while also adding the “X-HTTP-Method-Override" header to the HTTP request. Here is how Google uses this technique to get past some restrictive firewalls.

Why is a HTTP GET better than a HTTP POST? Well, your browser only caches the outputs from HTTP GET requests and never from a HTTP POST request. And the developer can gain control over how long the browser cache will be valid by setting the “Cache-Control” and the “Expires” headers in the HTTP response.

Updated post with the correct HTTP method operation after Sean Gillies pointed it out.

Tagged with: ,

5 Responses

Subscribe to comments with RSS.

  1. Rachel said, on September 8, 2008 at 6:35 pm

    Oh my God, I LOVE pedantic standard arguments, i LIVE for them. Usually this fun only happens on Slashdot.
    I’m checking my planet geospatial feeds and Sean Gillies says you’ve got yer methods crossed silly:

    Dude, it’s not an endpoint, it’s a resource! crazy microsoft speak.
    And while we’re at it I don’t wanna hear any talk of this this SOA, this isn’t SOAP man! It’s REST.
    ROA – Resources Oriented Architecture, –learn the TLA’s (three letter acronyms).

    You are like so NOT allowed to do RPC-REST hybrid! that is so not cool.

    Let me throw my hat into the ring:

    HTTP GET: Retrieve a representation of a resource
    HTTP PUT: (to a new URI): Create a new resource
    HTTP PUT: (to an existing resource): Modify an existing resource
    HTTP POST: (to an existing URI): Create a new resource
    HTTP DELETE: Delete an existing resource
    (contrary to Sean’s blog, i guess if you don’t like it complain to Leonard Richardson & Sam Ruby)
    Complaints can be directly addressed to Leonard and Sam.

    Also last I checked POST append or process is neither safe or idempotent no matter if used as append or process… like think posting to a factory resource URI, restful – yes, post(a) – yes, safe if posted to twice by mistake? – hell no.

    Monday was getting boring there.

  2. viswaug said, on September 8, 2008 at 11:33 pm

    Hi Rachel,

    How would you handle HTTP GET requests that have large amounts of data? I think that is just a limitation and all the solutions are going to be workarounds. And I don’t think picking one workaround over the other is any better since both are not quite right.


  3. Brad Cooper said, on February 11, 2009 at 8:40 pm

    Just wondering if there was any follow-up/finalization to this post. I’m actually working with the 9.3 REST API and I need to submit a faily large (>1024) where clause to one of my REST enabled service. After creating a web page, placing it under the same domain, and then updating the HTML code to be HTTP POST based, and then having it submit to my endpoint (ie. /ArcGIS/rest/services/XXXXXXX/MapServer/1/query) doesn’t seem to work.

    B. Cooper

  4. sandrar said, on September 10, 2009 at 10:14 pm

    Hi! I was surfing and found your blog post… nice! I love your blog. 🙂 Cheers! Sandra. R.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: