Best Practices for RESTful JSON Web Services

Posted by Mark Little on May 11, 2009

Sections

Architecture & Design,

Enterprise Architecture

Topics

REST ,

SOA ,

Web Services

Tags

JSON

Edwin Khodabakchian, once one of the key people behind the Collaxa BPEL product that subsequently found itself part of the core of Oracle's SOA strategy, has been working independently for several years on Feedly which "weaves twitter and Google Reader into a magazine like experience". Recently Edwin posted an experience-based cookbook on best practices for building JSON-based Web Services. No doubt this is a work in progress, but so far the guidelines it provides include:

Phase 1 – Defining a simple resource/service | Take a sample resource such as Customer Information, model it as JSON. Build a simple servlet where PUT creates a new customer, GET returns the customer information based on the customer key, DELETE deletes the customer and POST updates the customer information. Make sure that PUT returns the right information regarding the URL of the newly created resource. In our case, we have a framework which maps JSON to our Java Model and use hibernate to persist that model in a MySQL database. The important things for this phase are to the JSON representation right and the base url formatting simple and clean.

And:

Phase 3 – Adding validation | Change your service implementation to add some data validation to the JSON resource which is being received during PUT and POST. Learn how to use HTTP error code to define and transfer exception information. Learn how to handle those exceptions on the client side. The important thing for this phase is to make sure that you know the existing HTTP error codes, reuse them when it makes sense and create new one which are compliant with HTTP when needed.

At the time of writing there are 7 distinct phases, ranging from the first we've already mentioned, through authentication and to lifecycle. It's always good to see guidelines that are driven by real-world experience and Edwin tries to cover things that have no doubt caused them problems in the past, such as:

There are hundreds of libraries which help you abstract XMLHTTPRequest. Pick one that is cross browser. Pick one that is transparent enough to let you see the GET, POST, PUT and DELETE operations you are calling.

Or:

Defining the right granularity for the business event and the right typing is hard. You might have to iterate a few time to get this right. My advice is to not over engineer it: keep it as simple as possible and re-factor as new use cases appear.

Of course there are references to various aspects of REST that most proponents simply take for granted, such as:

Phase 5 – Adding caching | The web infrastructure offers rich caching mechanisms (last modified information, cache duration, eTag). Learn about those mechanism and see if you can leverage them to improve the performance and scalability of your service

Edwin also covers some highly practical approaches that may at first appear to go against the REST/HTTP rules themselves:

Some servers do not allow DELETE, in that case you need to learn how to do POST with an method overwrite.

According to Edwin they are considering open sourcing some of their back-end infrastructure. Until then documentation for the FriendFeed API is available. With the popularity of JSON+REST on the rise, this is an interesting cookbook for developers to consider and leverage.

1. Back to top

   Thanks

   by Edwin Khodabakchian

   Hi Mark. It has been a long time. I hope that you are doing well. Thanks for the post.

   Reply

2. Back to top

   Re: Thanks

   by Mark Little

   Hi Edwin. Great blog entry so thanks for that too :-) Keep 'em coming.

   Reply

3. Back to top

   Lack of HATEOAS

   by Mike Kelly

   As far as I can make out - there is no standard for representing hyperlinks in JSON
   
   This is a significant limitation for JSON as a hypermedia format, for obvious reasons. It certainly not something that cannot be overcome, however.
   
   Maybe the JSON community will make efforts to fix this?

   Reply

4. Back to top

   Re: Lack of HATEOAS

   by Dan Diephouse

   Ummm, isn't it as simple as { "myLink" : "http://foo.com" } ?
   
   Dan Diephouse | mulesource.com

   Reply

5. Back to top

   Re: Lack of HATEOAS

   by Manish Bhatt

   I agree with Dan. I use { "myLink" : "http://foo.com" } for all my JSON representations. So far no issues.
   
   Manish

   Reply

6. Back to top

   Re: Lack of HATEOAS

   by Stefan Tilkov

   Well, one could argue that there's no standardized "<link rel='...' ref='...' />" element in JSON. Then again, there's none in XML either :-)

   Reply

7. Back to top

   Re: Lack of HATEOAS

   by Mike Kelly

   A client would need to evaluate the value of any pair to establish whether or not it was a hyperlink (by checking for 'http://' at the beginning of the value?!) - or it would have to have prior knowledge of the data structure; which would cause some coupling and reduce discoverability.
   
   How would your solution work for relative links?
   
   Here's an alternative..
   
   { "link": { "$href" : "a/relative/link" } }

   Reply

8. Back to top

   Re: Lack of HATEOAS

   by Dan Diephouse

   You have to have prior knowledge of the datastructure... I hear ya on the whole <link> element thing, but that's one of the tradeoffs of going with JSON. No namespaces. But it's a hell of a lot simpler. Pick your poison!
   </link>

   Reply

9. Back to top

   Minor remark: POST/PUT semantic

   by Thierry Boileau

   Hi,
   
   I think that PUT means: "create the targeted resource if it does not exist yet, or update it otherwise".
   That is to say: you already know the resource's URI, there is no need to return it.
   
   POST is more generic and can also be used to create another resource having another URI... For example, you can POST "/items" in order to create "/items/123". In this case, that's a good pratice to return the URI of the created resource.
   
   best regards,
   Thierry

   Reply

10. Back to top

    Re: Minor remark: POST/PUT semantic

    by David Tkaczyk

    Hi,
    
    I think that PUT means: "create the targeted resource if it does not exist yet, or update it otherwise".
    That is to say: you already know the resource's URI, there is no need to return it.
    
    POST is more generic and can also be used to create another resource having another URI... For example, you can POST "/items" in order to create "/items/123". In this case, that's a good pratice to return the URI of the created resource.
    
    best regards,
    Thierry

    
    
    Yes, yes, yes... this is much more correct than what the article proposes!!!

    Reply

• Older >