Friday, June 01, 2007

How NOT to do RESTful Web Services

A number of web service toolkits , including Apache Axis2 and Apache CXF, now claim to support REST. But in fact, these systems do NOT support REST. They support non-RESTful POX (plain old XML) over HTTP. Non-RESTful POX services are more accessible than SOAP services, but they don't exhibit the desirable characteristics associated with RESTful resources.

The REST architectural style defines a number of basic rules (constraints), and if you adhere to these rules, your applications will exhibit a number of desirable characteristics, such as simplicity, scalability, performance, evolvability, visibility, portability, and reliability.

The basic rules are:
  • Everything that's interesting is named via a URI and becomes an addressable resource
  • Every resource exposes a uniform interface (e.g., GET, PUT, POST, DELETE)
  • You interact with the resource by exchanging representations of the resource's state using the standard methods in the uniform interface
Non-RESTful POX applications violate these basic rules. First, they don't define a URI for every resource. And second, they don't constrain the interactions to the methods defined in the uniform interface. Instead they define a single URL that represents an operation that can be performed on any number of unnamed resources. Essentially they are tunneling RPC calls through the URL.

Take this example from a recent exchange on the Axis user list:

Q: How do I call a web service operation from a browser having input and output?
My target is end point is http://host/MyService/getInfo and the SOAP body is:

A: http://host/MyService/getInfo?systemName=Administrator&systemPassword="Password123"

Notice that the URL contains a method name (getInfo) and query string containing the method parameters. This is NOT REST!

A RESTful system would define a different URL for each systemName, and you would invoke GET, PUT, POST, and DELETE operations on the individual systemName resources. The GET query would look more like this:


Notice that I haven't included the systemPassword query parameter in a query string. The idea of passing a password via a URL query string simply boggles the mind. More likely you would use HTTP authentication rather than submitting a password as a query parameter.

I've written more about REST in the Burton Group blog, if you're interested.


Davanum Srinivas (dims) said...

Anne, Please see the following article on what we are trying to do in Axis2.


dan said...

Have you ever looked at the CXF RESTful service support? This isn't how it works at all. I posted a follow up on the InfoQ site, so I won't bother to reproduce it here again...

eric said...

Nice post. See reference - mine.

Anne Thomas Manes said...

Here's a link to Eric's post.

Keith Chapman said...

Anne, This is how Axis2 is for the default case. But it does not have to be that way. You may want to look at this post which shows how you could do RESTfull stuff on the Mashup Server. The Mashup Server is built on top of Axis2 so this clearly shows how a RESTfull service can be written in Axis2. I have some ideas in my mind that will make it simpler for Axis2 users though. Will send those to the Axis2 list soon.

Sandeep Aparajit said...

Nice article Anne. An interesting one about REST and POX.

Sandeep Aparajit

abby brock said...

I am so glad this internet thing works and your article really helped me. Thanks for this.

movers in virginia