Towards a better RESTful service

REST web services allows disparate network to communicate on the internet using a predetermined format.  While this comes with faster performance, scalability, reliability and re-usability; designers must be wary of some pitfalls.  Some of them are mentioned below:

a) Designers must be careful not to confuse RESTful thinking with domain process.  For example, if you need two functionalities – payment and shipping of an order.  A designer may combine the two functionalities into a request using HTTP PATCH method:

This violates the DRY principle. These are different transactions and should consider using different URLs, like so:

This second approach makes it clearer, validating and authorizing the transactions in two ways.

b) Prevent accidental leakage of user supplied data in URIs.  Also, if the data is one with an ampersand, IIS will have difficulty handling such requests.  IIS might consider it to be dangerous and not handle it.  Here’s an example of such URL:

One approach is to encode the URL.  Would this work?  Not quite!  The encoded URL is part of the request path and not a query string.  The issue here is a matter of dangerous URL not encoding.

A better approach is to internally map “rocks & scissors” to an id, that can be requested like so:

PUT /api/foo/20

This makes it almost impossible to guess the URL and API consumers can follow the links rather than guess a URL.  This makes API more secure and compliant with IIS routing rules.  In addition, your API can get closer to Level 3 model of “restful maturity” as clearly defined by Martin Fowler of ThoughtWorks.