Best Practices for building JSON REST Web Services

A few of our friends have been asking us what are some of the best practices we learnt over the last two years designing and implementing RESTful Web Services as the back-end of the feedly service. Here is a quick/high level brain dump:

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. [Update: see some additional clarification regarding the use of PUT versus POST for creation and update at the end of this document]

Phase 2 – Implementing a client | Learn how to build a simple Javascript client which interacts with the service you built in phase one. This is AJAX 101. 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. JQuery is a great candidate. Some servers do not allow DELETE, in that case you need to learn how to do POST with an method overwrite.

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.

Phase 4 – Complex resources | More services evolve over time into resources which are more complex/composite. This will have impact on your URL hierarchy. It will also have impact on the way you marshal those composite JSON resources into domain objects. Try extending the customer resource to include [1…N] address resources. Make sure that the new “service” allows you to get a customer with all its addresses but also allows you to get one address or add/edit/delete an address.

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. In the back end, learn about Memcached and see how you can leverage it to reduce the load on our service. This is all the more important when you start dealing with sets of large composite resources which are expensive database-wise to build but are not updated often (in those cases, it might be worth to building the resource once and asking the client to cache it if you know when it is going to expire or ask memcached to cache it you do not.

Phase 6 – Adding Authentication | Learn who to leverage your existing web authentication frameworks to for the user to login and validate credential before the service is accessed. Look at how you could use Open Id and OAuth if you are building a consumer centric service. Here again use existing HTTP error codes when possible.

Phase 7 – Publishing Business Events | Often, changes to resource require different types of back end processing. When possible try to avoid creating a monolithic service, instead, save the resource and fire a business event. 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. For example, if you want to have some processing to send a new welcome email to each customer, define a ON_NEW_CUSTOMER event with a payload which includes the customer URI and instrument our service to fire that event each time a new customer is created.

Phase 7 – Adding Lifecycle | If your resource includes a life-cycle (example Order), your can model that life-cycle as part of the resource and use the state for the the validation in phase 3 and the published business events (state transitions are usually good candidates for business events).

We will try to add more as our back end evolves. We are also looking at taking some of our back-end infrastructure and open sourcing it. We should know more in the next few months. If you have any suggestions you would like to share please post them in the comments or send me an email to and I will update this list. Thanks!

Update/May 27th, 2009: There has been some great comments regarding the use of PUT versus POST. So I did some additional research and found this interesting post.

The crux of the issue comes down to a concept known as idempotency. An operation is idempotent if a sequence of two or more of the same operation results in the same resource state as would a single instance of that operation. According to the HTTP 1.1 specification, GET, HEAD, PUT and DELETE are idempotent, while POST is not. That is, a sequence of multiple attempts to PUT data to a URL will result in the same resource state as a single attempt to PUT data to that URL, but the same cannot be said of a POST request.

After that discussion, a more realistic mapping would seem to be:

  • Create = PUT iff you are sending the full content of the specified resource (URL).
  • Create = POST if you are sending a command to the server to create a subordinate of the specified resource, using some server-side algorithm.
  • Retrieve = GET.
  • Update = PUT iff you are updating the full content of the specified resource.
  • Update = POST if you are requesting the server to update one or more subordinates of the specified resource.
  • Delete = DELETE.

Update July 8th 2009. Here is a great presentation from LinkedIn on how they use RESTful APIs for high performance integration. Great watch.

Related posts:
InnovationDesign and Abstractions
REST+JSON facade to

Author: @feedly

Read more. Know more.

49 thoughts on “Best Practices for building JSON REST Web Services”

  1. Nice article.

    My preference is to use POST for creating a new resource within a collection. PUT for creating a resource at a specific location. POST for other non-crud stuff.

    Wouldn’t use POST for edit always use PUT.

  2. In my opinion, JSON is not hypertext, e.g. no standard way to represent links, so it can’t be “completely” restful.

  3. @Erik Thanks. Do you have a 5-min intro video of what it takes for a developer to build a service using datanucleus (if not, you should)

    @ander there is no formal way to represent hypertext, but there are several ways you can include URL and URI in JSON structures so not completely restful in the eyes of the most radical ones but significantly better than XML and SOAP is you are building real applications.

    1. would you be able to elaborate more or share some helpful tips into including URLs in a JSON structure? I don’t see much literature on any standardized ways of doing this.

      1. Hi Watts. Have you had the chance to look at the Facebook Open Graph API. It is a really great example of JSON+REST pattern, with URL encoding of filtering and paging as well as some batch processing. A lot of good lessons to be learnt.

        1. There is no such thing as JSON+REST since REST is not a ‘thing’. The only form of JSON that can be used in a web service and be called RESTful is HAL+JSON. If your web service is not based on hypertext, then your web service is RPC, not REST.

  4. Hi Jesper. Thanks for the links. This week is a little crazy but will try to carve out some time next week or the week after to review django-piston and provide feedback.

  5. I’m with Jim. PUT for create (known location) or update, POST to factory/collection for create at unknown location, or for none-of-the-above situations.

    Nice suggestion about back-end business events.

  6. Edwin, you’ve just mixed up PUT and POST in phase 1. A typo, perhaps. POST is usually for creating subordinate resources, (which returns the URL of the created resource in the Location response header). GET is used to get that resource and PUT is used to store a modified version of that resource.

    Since you’ve been linked from InfoQ, it would be a great help to newbies understanding REST if phase 1 were corrected in the text above…

    1. Hi Erik. I updated the post to clarify how developers should use idempotency to determine when to use PUT and POST when it comes to creating and changing resources. Let me know if you have a different perspective.

  7. Does this method still work? I can create the custom class and format the page as json, but trying to call the page from outside of salesforce by passing in a un and pw doesn’t seem to work. Authentication fails every time. Is there something else that has to configured to use this?

  8. All this is excellent advice. It’s so easy to make architecture mistakes during the initial buildout phase that back you into a corner later on. I especially like the advice about decoupling the business events; I can’t tell you how many times I have seen this exact problem, stuff just jammed into a long, complex method call as an afterthought.

  9. I have been doing the same stuff before, but is it truly web service?

    The important things for this phase are to the JSON representation right and the base url formatting simple and clean

    1. Actually implementing own codec for decode and encode, is one solution to make the true web service, provide true JSON binding. As for restful, it may still need to resolve to url mapping.

    1. Hi MartinI come here because I am midlly curious about the idea of making money from one’s blog, but it seems to me that what drives readers to blogs is content, and so I was hoping for a bit more. Something to drive people back?Aurelius

  10. Just came across this whilst thinking about refactoring an existing project to use a core web service-based system. Thanks for the succinct explanations :-)

  11. What should be a generic way of representing URI for say thousands of resources that are created in a hierarchy?

  12. If you are going for most excellent contents like myself, just
    visit this web site everyday since it gives feature contents, thanks

  13. Aw, it was quite a great post. In notion I’ve to place in writing comparable to this moreover – taking time and actual effort to produce a genuinely good article’¦ but what can I say’¦ I procrastinate alot and also by no indicates appear to go completed.

  14. Fantastic website. A lot of helpful info here.

    I am sending it to several buddies ans also sharing in delicious.
    And naturally, thanks for your sweat!

  15. Great blog here! Also your website loads up fast!
    What web host are you using? Can I get your affiliate link to your host?
    I wish my site loaded up as fast as yours lol

  16. download this tool to easyly hack facebook password in one click. … Facebook Hack Password Hack 2013 Download In Description Facebook … hack any facebook password account, that you need. Online email & password facebook is simple and will take few …

    Additional tags:

    facebook cheat, facebook cheats, facebook code, facebook codes, facebook hack, facebook hack by Hexozus, facebook hack in, facebook hacker, facebook hacker download, fb hack password, hack facebook accounts, hack facebook password, hack facebook profile, hack fb password, hacking facebook, hacking to facebook, how can i hack a facebook account, How to hack facebook account, how to hack facebook password, passwords facebook

  17. Thanks a lot for sharing this with all of us you actually understand
    what you are talking approximately! Bookmarked. Kindly also visit my web site =).

    We may have a hyperlink trade contract between us

  18. Hi there! Do you know if they make any plugins to assist with Search Engine Optimization?
    I’m trying to get my blog to rank for some targeted keywords but I’m not seeing very
    good gains. If you know of any please share. Kudos!

  19. Next repeat this same process but this time don’t workout. However, such meals are impossible to maintain for months on end. Step 1: Incorporate local grown food into your daily intake.

  20. Through some combination of Gates withdrawing his influence
    of pride in the brand to the point of arrogance, and Ballmer introducing the business common sense that customers should be kept happy
    if it can be done affordably, Microsoft was able to understand how much Vista sucked, and how much
    they had sucked up until then. There exists now $20 from the pot,
    and its $10 to call up, so you might be finding two:one (33%) on your own facebook poker chips, and
    therefore the odds of earning your hand are about 11:one or 8%.
    To the accomplished hacker or to any computer expert in general,
    hacking can be a relatively basic action that can be accomplished with minimum

  21. It is made up of water means that you have to keep the basement in a
    dry mold exposure area or you can hire experts to do the remediation.
    Initially, the source of the leak, replacing leaky roof
    vents, removing old caulking and replacing it with
    new, and repairing damaged seams.

  22. Hi i am kavin, its my first occasion to commenting anyplace,
    when i read this paragraph i thought i could
    also create comment due to this good post.

  23. Very great post. I just stumbled upon your blog and wished to mention that I’ve truly enjoyed surfing around your weblog
    posts. In any case I’ll be subscribing for
    your rss feed and I’m hoping you write once more soon!

  24. Touche. Great reduxil discussions. Maintain the amazing work.

    This kind of information comment-498191 is priceless.

    When will I read more?

  25. Incredible points. Great link points. Continue the great effort.

    This post here is worth everyone’s attention. Where can
    I garner more information?

  26. Hello, 254 I just wanted to say, I enjoyed this post p25308.
    It actually was helpful p13515. Continue publishing!

Comments are closed.