Should I RESTify my RPC calls over HTTP?

Question

We have HTTP webservices that are RPC. They return XML representing the object the either retrieved or created. I want to know the advantages (if any) of "restifying" the services.

• POST http://www.example.com/createDoodad
• GET http://www.example.com/getDoodad?id=13
• GET http://www.example.com/getWidget?id1=11&id2=45
• POST http://www.example.com/createWidget
• POST http://www.example.com/createSprocked

One thing I see is that we don't need representations for EVERY resource and we don't need to support all operations (GET, PUT, POST, DELETE) on all resources either. Basically my question is this.

Convince me that I should be using restful services instead of RPC over HTTP and what would those restful services should be?

Answer 1

For one it's all about semantics, a URI is a Uniform Resource Indicator. HTTP provides methods to GET, POST, PUT, and DELETE a resource. HTTP headers specify in which format I want to recieve or send the information. This is all readily available through the HTTP protocol.

So you could reuse the same URL you use for HTML output to get XML, JSON in a way that HTTP was meant to be used.

XML-RPC and SOAP are based on calling methods that are described by an XSD or WSDL file whilst REST is based on getting/modifying resources. The difference is subtle but apparent. The URL solely describes the resource and not the action as is often the case with SOAP and XML-RPC.

The benefits of REST are that you can utilize HTTP verbs to modify a resource as supposed to a method call that could be named create/new/add, etc. Meaningful HTTP status codes instead of different kinds of error responses and being able to specify different formats on the same resource in a standard way.

You also don't have to accept ALL the verbs on a RESTful resource, for example if you want a read-only resource just return a 405 status code Method Not Allowed on any verb which isn't GET.

Should you redo your RPC calls to REST ? No, I don't think so. The benefits don't outweigh the development time. Should you learn REST when setting up a new Webservice ? Yes, I personally do think so, consuming a REST resource will feel a lot more natural and can grow much more rapidly.

EDIT

Why I feel REST wins over XML-RPC/SOAP is that when developing websites you already aggregate all the neccessary data for the output to HTML, you also write validating code for POST bodies. Why should you change to a different protocol just because the transport markup changes?

This way when you design a new website (language agnostic) if you really think of URI's as resources you basically use your URI's as method calls with the HTTP verb prefixing the method call.

That is, a GET on /products/12 with an HTTP header Accept: application/json; basically (imaginary) translates to getProducts(12,MimeType.Json).

This 'method' then has to do a couple of things

1. Check if we support JSON as a MIME type. (Validate request)
2. Validate request data
3. Aggregate data for product 12.
4. Format to JSON and return.

If for some reason in the next 4 years YAML is going to be the next big craze and one of your consumers wishes to talk to you in that way this MIME type is plugged in a lot easier than with regular web services.

Now product 12 is a resource you most likely also want to accept HTML MIME types on to display said product, but for a URI like /product/12/reviews/14/ you don't need an HTML counterpart, you just want your consumers to be able to post to that URL to update(PUT)/delete(DELETE) their own review.

In thinking of URIs strictly as resources, not just a location of a web page, and these resources in turn combined with the HTTP request to method invocations on the server side leads to clean (SEO friendly) URLs and (more importantly?) ease of development.

I'm sure there are frameworks in any language that will automatically do the mapping of URIs to method invocations for you. I can't recommend one since I usually roll out my own.

ASP.NET MVC also works on the same principle, but in my opinion it doesn't produce RESTful URIs. ASP.NET MVC makes the verb part of the URI by default having said that it's good to note that by no means does ASP.NET MVC force this (or anything for that matter) upon you.

If you're going to choose a framework at the very least they should:

1. Bind URI's to methods on the server
2. Support Object to JSON/XML, etc. serialization. It's a pain if you have to write this yourself although, dependent on the language, not neccessary all too difficult.
3. Expose some sort of type safe request helpers to help you determine what was requested without parsing the HTTP headers manually.

Answer 2

Try taking the verbs out of your URLs:

• POST http://www.example.com/Doodad
• GET http://www.example.com/Doodad/13
• GET http://www.example.com/Widget/11/45
• POST http://www.example.com/Widget
• POST http://www.example.com/Sprocked

Answer 3

Query strings shouldn't be used for accessing a resource in a hierarchical, non-query manner. Query strings are usually ignored when caching, which is dangerous and slow.