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

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.

Advertisement