Guidelines on Restful Web Services

| Comments

Guidelines to get Restful Web Services right

Uniform Resource handling

  • Allow discoverability of new resources. Similar to adding new link to existing page (resource) to allow access to new page (new resource).
  • Take advantage of intermediary components between client and server. ( Caches, Proxies, Firewalls etc)
  • Follow consistent approach to view/modify/create operations on any resource.
  • Make conscious trade-offs between cache-ability, discoverability, performance and convenience

Safe Methods

  • Client requests are readonly.
  • Client can make duplicate requests without causing unintended side-effects. Similar to loading the page again in browser.
  • Does not mean server will respond with same response to the new requests. Similar to reloading(F5) a page in browser may get different/modified response (new data) on dynamic web page.

Idempotent Methods

  • Client can replay the request if client is not certain server has processed the request due network failure or other errors.

Follow HTTP standards

  • Use Request Methods as defined by HTTP

    • Get, Head, Options methods
      • should be safe (readonly) i.e. should not cause side effects on resource representation.
    • Get, Head, Options, Put, Delete
      • should be idempotent i.e. replay of request (due to network failure or uncertainty) should not cause issues
    • Post
      • Can cause side-effects and does not guarantee safety or idempotent
    • Use Request MIME Types to encode representation
    • Use HTTP status code for responses status
    • Keep Restful Services Stateless — maintain state in client.

  • URL of the resource

    • Url of the resource represents the hierarchy.
    • For example : www.school.com/class/<1>/subject//
      • In the above example school has classes
      • classes has subjects

Frequently Asked Questions :

  • Is PUT Request for Creation and POST for updating ?

    • Both PUT and POST can be used for Creating new resource or Updating an existing resource.

  • Deference between PUT and POST ?

    • PUT is idempotent and client can be replay the request if network failure or system error without causing issues on server. Use PUT to completely replace existing resource representation or create new resource representation.
    • POST is not idempotent and general purpose method without restrictions and corresponding benefits. Use POST when other verbs don’t fit.

  • When to use POST ?

    • POST is general purpose method which can be used when other HTTP verbs don’t fit well.


[Using] POST only becomes an issue when it is used in a situation for which some other method is ideally suited:
e.g., retrieval of information that should be a representation of some resource (GET), complete replacement of 
a representation (PUT), or any of the other standardized methods that tell intermediaries something more valuable
than “this may change something.” The other methods are more valuable to intermediaries because they say something
about how failures can be automatically handled and how intermediate caches can optimize their behavior. POST does
not have those characteristics, but that doesn’t mean we can live without it. POST serves many useful purposes in
HTTP, including the general purpose of “this action isn’t worth standardizing.”
                    --- Roy T. Fielding (http://roy.gbiv.com/untangled/2009/it-is-okay-to-use-post)

  • How does HTTP Safety and Idempotent work during concurrent requests?

    • Safety and Idempotent are defined in non concurrent condition.
      • Good analogy to understand is load a web page in browser and on reloading the page browser can get new version of the page. Server could also deny GET request if agreed number of requests has been reached. User should not worry about making duplicate requests.
    • For example,
      • A replay GET request can return new representation if resource is modified by another request.
      • A replay GET request can return modified representation like updated hit/access count.
      • A failed GET request after allotted number of calls are made to a given resource, does not violate Safety rule.
      • Get request with authentication token can fail on second request. Safety does not grantee same response every time.

  • Can a single GET request return two or more different resources? Can a resource contain other resources?

    • Yes, they can but it comes at the cost of cache-ability.
    • For example:–

    Car Resource

    GET /car/:licenceNumber

    {
    make : 'Toyota',
    model : 'Rav4',
    color : 'Red',                              
    owner : {
                link : '/car/:licenceNumber/owner',
                firstName : 'John',
                lastName : 'Smith',
                address : {
                                streetName : '300 Boylston Ave E'
                                city : 'SEATTLE',
                                state : 'WA',
                                zipcode : '98102'
                                country : 'USA'
                        }
            }
}

The above GET request for resource Car given a license number will return information on car, owner and owner address. Server might expose owner and owner address as resources as-well. As shown below.

Car Owner Resource

GET /car/:licenceNumber/owner

{
    firstName : 'John',
    lastName : 'Smith',
    address : {
                link : '/car/:licenceNumber/owner/address',
                streetName : '300 Boylston Ave E'
                city : 'SEATTLE',
                state : 'WA',
                zipcode : '98102'
                country : 'USA'
             }
}

Car Owner Address Resource

GET /car/:licenceNumber/owner/address

{
    streetName : '300 Boylston Ave E'
    city : 'SEATTLE',
    state : 'WA',
    zipcode : '98102'
    country : 'USA'
}

In this case, Car Resource contains Owner resource which in turn contains owner address resource. But Server exposes two other end point for owner and owner resource.

Comments