REST Service - the two words that make no sense

It's been bothering me for like ages and I finally decided to put a blog post about it. Let's start with a couple of definitions:

WebService - a way of servicing someone (like "giveMeSomething" sort of way) over the web

REST - Representational state transfer. We're transferring a representation of the state (of someone) - not servicing anybody.

To see why is this so damn important first let's see what classic SOAP web services look like in practice. They consist of 3 things:

1. WSDL / XSD (description)
2. Endpoint (URL)
3. XML (data)

In fact there's one most important thing to note: the "endpoint" is/has usually a verb: "go get some flowers", "fetch history", "make me pretty" - you get the idea, right?

Now on the other hand REST has nothing to do with verbs - REST deals with nouns: people, cars, addresses, gasoline, money... So how do you make a person give money for gasoline for their car to allow them to get to a certain address they are heading?

WebService: MySuperDuperWebService.makeHimPay(Double money)
REST      : GET /person/54623445/account/1/balance (get the current balance)
            PUT /person/54623445/account/1/balance + current balance

The difference here is you're not giving a REST place orders other than update, delete, retrieve.

So the next time you'll be tempted to say REST service please bear in mind there's no such thing. What is however named as a "REST service" is a URL, that responds (usually) to POST (cuz that's so damn easier to pass data to) that has no predefined schema (usually..) and that instead of giving you back XML hands you over JSON (possibly using JSONP). That my friends is a definition of a JSON Service and has nothing, absolutely nothing to do with REST whatsoever. Even worse is the term RESTful web service. My God is that a horrible thing to say. It seems like the service being referred to rusts in peace and should never ever be called.

Make the world better for a change!

jQuery and posing JSON data to the server

Today a good friend of mine asked me how to post JSON data to the json-rest-api plugin using jQuery. As it turned out using $.post() doesn't do the trick...

Well it's not impossible but very inconvenient if you have to do it a lot. First you need to use the $.ajax() method, not the $.post() one. Secondly you need to specify the contentType parameter for the receiver to be notified that the data is in that format. And last but not least it is crucial to properly serialize your object to string.

The last part can be done using JSON.stringify() but writing this over and over again is painful. Here's a gist (raw) you can use that adds a sister version of $.post called $.postJSON that does exactly the same thing as the original one but sends data in JSON format instead of form post.

Parameters are exactly the same with the single difference that the default expected data format is "json", which makes sense if you're working with JSON services.

Happy coding!

ASP.NET MVC and different output formats

Hi there,

I wanted to mimic the nice behavior of Ruby on Rails that allows you to render different content based on the extension passed on in the URL. Here are a couple of examples:

http://localhost/people/list.json <- list of people in JSON
http://localhost/people/show/1.json <- person with id=1 in JSON
http://localhost/people/list.xml <- list of people in XML
http://localhost/people/show/1.xml <- person with id=1 in XML

The part I was not able to figure out right away was the routing configuration. Here's how I finally did it:

routes.MapRoute(
   "ActionWithFormat",
   "{controller}/{action}.{format}"
);

routes.MapRoute(
   "ActionWithFormatAndId",
   "{controller}/{action}/{id}.{format}"
);

routes.MapRoute(
   "Default",
   "{controller}/{action}/{id}",
   new {
       controller = "Home",
       action = "Index",
       id = UrlParameter.Optional,
       format = "html"
   }
);

As you can see here I've added 2 additional routes (ActionWithFormat and ActionWithFormatAndId) that contain the additional parameter distinguished by "." (dot) instead of "/" (forward slash). I've also took the liberty to modify the Default route so that when no format is passed the default "html" format is what you'd get passed to the action.

Now suppose you'd like to make use of it in the PersonController's Show action:

public ActionResult Show(String id, String format)
{
    var person = new { FirstName = "John", LastName = "Doe" };
    switch (format)
    {
        case "json":
            return Json(person, JsonRequestBehavior.AllowGet);
        default:
            return View(person);
    }
}

Sure that the RoR's version is shorted, nicer, purer and all that but this little fellow here does the trick as good as the RoR's :)

The key here is that the format is just a string so if you'd like to come up with (let's say) a PdfActionResult then using it in an action is just dead simple!

I hope you'll find it useful!