The basics of building a RESTful service

The term REST originated with Roy Thomas Fielding in his paper on Architectural Styles and the Design of Network-based Software Architectures. In this paper he described a way to leverage the basic principles behind the web and apply those to business applications. He argues that the World Wide Web is in fact one of the largest applications used by millions of people every day and one that, despite frequent predictions to the opposite, has managed to scale very well.

If the web as we know it is such an immensely scalable and quite reliable application when why don’t we build our own distributed systems with the same architecture?

Where are a couple of reasons here as I see it:

  • The standardized SOAP protocol has become quite popular over the last few years. The promise of a standard based messaging approach is very appealing because it promises a lot if interoperability. And the fact it’s standards based made it easy for vendors, like Microsoft, IBM or Oracle to name a few, to implement API’s around it. And with them having put a lot of work in it they tend to push people to using their products.
  • The architecture of the web is actually quite poorly understood by a lot of people. Sure they use their browsers and read websites. And most likely they use even more of the web without realizing it. But they don’t know how it really works, just sort of.
  • The people who do know how the web works usually didn’t think of it as appropriate for their applications. After all the web is such a massively big thing. As a result it’s architecture can’t possibly be useful for a much smaller business application.


Well it turns out the last group was wrong Sad smile


As Roy describes in his paper the web is actually build around a very limited set of relatively simple technologies that have proven themselves over the years. And with an understanding of these basic technologies it isn’t hard to incorporate the same basic architecture into our own applications Smile 


Of course that doesn’t mean that SOAP is wrong and REST is right.

Like all architectures REST has it strengths and weaknesses. Using an architecture like REST blindly will lead to problems as there are numerous cases when SOAP will be more appropriate.


Some of the differences between SOAP and REST are:




Style Operation centric Resource centric
Addressing Single URL for each service, no matter how many operations A URL points to a resource. Different resources have different URI’s.
Transport Doesn’t care, it’s just a means of getting bits from A to B. No real use of transport features. HTTP only. Uses as many of the HTTP standard features as possible.
Request meta information Passed in the SOAP header as part of the request body. Passed as HTTP Message Headers.
Action to perform Passed as part of the SOAP header in the message. Uses the HTTP Method to determine what action to perform.
Message formats Always XML using a well defined envelope containing a header and the body. Often XML of JSON but the developer is free to choose whatever format is most appropriate at the time. The same resource(=UR) can be represented with different formats depending on the clients needs. The client can use the standard HTTP Accept header to specify the format required using MIME Media Types.
Result status Using faults as part of the message body. Uses HTTP Status Codes to indicate the result status of a request.
Caching Only with custom code. Responses can be cached using standard web infrastructure.
Standards Lots of standards around different action. Commonly grouped together as the WS-* specification. Besides HTTP there are a few standard like AtomPub that are commonly used. However these are not a requirement for building Restful services.
Tooling Lots of tooling support like Add Service Reference in Visual Studio Due to the lack of standards there is very little specific tooling support.


So I guess it boils down to that SOAP want to do everything over any transport with lots of, sometimes complex, standards while REST is much less formal and uses as much as possible from the HTTP standard but leaves the developer much more flexibility.

Both approaches have their strong and weak places so you should take a good look at what is best suited in your situation.





Leave a Reply

Your email address will not be published. Required fields are marked *