What is the meaning of RESTful Web Services? 

Explain RESTful web service with examples.

Compare SOAP-based Web Services and RESTful Web Services.

I will talk about

  • basics of REST and REST web services
  • REST vs Soap
    • data type
    • scalability
    • implementation ease
    • specific application need

There are many nice articles talk about the basics of REST. Here I would like to highlight the key points and illustrate with my hands on experience.


REST, representational state transfer is an architectural style, which suggest constraints include Client- Server, stateless, Cacheable, Layered System, Uniform interface and Code on demand. Restful refers to services that conform with the REST constraints.

REST is not a simple concept. The major idea be resources.-oriented.

A Resource can be essentially any coherent and meaningful concept that may be addressed, captured in a representation which is typically a document that captures the current or intended state of a resource. Basic CRUD operations are supported.

Client- Server:
clients and servers are separated by an uniform interface. With separate of concerns of client/server, the client / server is more portable and easier to be replaced.

REST allow Stateless at server side.  servers process requests and return appropriate responses. Requests and responses are built around the transfer of representations of resources.

Client is always be either in transition between application states or “at rest”. State change associates with sending requests.The representation of each state contains links that can be reused for later new state transition. A client in a rest state is able to interact with its user, but creates no load and consumes no per-client storage on the set of servers or on the network.

REST Web Service

A common misunderstanding of REST is that it is limited with HTTP protocol and web services. It is true that REST are mostly implement and described in the context of HTTP.  The author, Roy Fielding is also one of the principal authors of the HTTP specification versions 1.0 and 1.1. However, it is possible to apply REST in other architectural context and other application layer protocols.

REST Web Services is emerging in recent years. It is a collection of resources, with following defined aspects [Wikipedia]

  • the base URI for the web service, such as
  • the Internet media type of the data supported by the web service. This is often JSONXML or YAML but can be any other valid Internet media type.
  • the set of operations supported by the web service using HTTP methods (e.g., GET, PUT, POST, or DELETE).
  • The API must be hypertext driven.


REST intended to increase scalability by supporting caching which improve response time and save bandwidth and server loading. Not necessary of keep connectivity alive reduce loading further. Also different server can handle the same request

Also, it simplifies component implementation.

According to Fielding,  REST enables intermediate processing by constraining messages to be self-descriptive: interaction is stateless between requests, standard methods and media types are used to indicate semantics and exchange information, and responses explicitly indicate cache ability.

REST also try to re-use existing vocabulary, as in GET/PUT/POST/DELETE for case of HTTP. However there was no way to specify a form method other than GET or POST which make other requests twisted into a POST one. With PUT/DELTE in form supported by HTML 5, the web can be more RESTful. It is also not necessarily to require other discovery mechanism with URI.


Twitter is a classic exmples of REST Web Service (also for Ruby on Rails).  Its API is based on REST.

For example,

GET statuses/show/:id  will returns a single status, specified by the id parameter below.

while POST statuses/destroy/:id destroys the status specified by the required ID parameter.


Again, the advantage and popularity of REST is brought to us by awesome frameworks.

Ruby on rails is the major one, while other examples include Play!.

They adapt Restful and “conventions over configurations”, to make applications much more clear and greatly reduce the time of development



Since the very beginning, SOAP has been considered heavy weight, as in this test. 

First of all, SOAP envelope constitutes the overhead

Also ,it is speculated that the SOAP protocol is introducing a lot of extra overhead in the serialization and deserialization of data which is simply unacceptable for large payload sizes.

SOAP’s performance relative to http is disturbing: since SOAP uses HTTP as its transport one would expect that their performance would converge as the payload size increased

While REST end point is also stateless, state is also being transfer?

Data Type

in SOAP, all communication is in XML. web services are not tied to any one operating system or programming language.

However this can also be achieve in other format, such as JSON. In REST there is no such limitation to use XML only. XML is heavy weight and increase the overhead of messages.

Atom Publishing Protocol for publishing to blogs is considered a canonical RESTful protocol.

The possibility to use JSON allow REST to be more light weight. Also end to end integration of technologies like javascript, jsonp to document-oriented database design such as clouchDB is easier. One application to illustrate


For Soap, HTTP is used which is proxy-server or firewall friendly and easy to deploy. REST shared the same when HTTP it in use.

As mentioned REST is mostly with HTTP, however it is possible to implement with other application layer protocol, as long as it is possible to transfer meaningful representational state. It can also be extended to Message queue system. Read Restful Queue from ActiveMQ. Soap is a protocol while REST is a style of programming, in the later one there is much more flexibility.

In SOAP, WSDL work as a formal description to define machine to machine interaction. In WSDL 1.1 the http binding is inadequate to describe REST, however WSDL 2.0 can now be used to describe REST as well.

Implementation ease

In traditional web application such as Java EE EJB with SOAP, when there is need to add or modify some parameters, change are often cascading. From UI, ajax and other requests to back-end Java Bean, entries in DB. Although Jsp provide mechanism to render bean, with modern ajax it is not that useful.

The deeper problem with SOAP is strong typing. WSDL use XML Schema and strongly typed messages, which may be  a bad choice for loosely coupled distributed systems.

With REST no special agent is required, standard curl request which can done in browsers. With SOAP usually there is dedicated Library for access. In terms of API upgrade for public web service it is more complex client applications may need new agents to be deployed.

One of the goal of REST is to make web applications more intutitve to develop. Generally true for most cases. Since programmer time is expensive, this is a definitive advantage.

With Restful, there is better forward/backward compatibility since the contract is simpler (involving resource name and allow CRUD) and  less likely to change. The end to end flow  follows convention and adapt to changes. A good read on this will be The Beauty of REST 2004.

REST is simple?

REST based on standard verbs and URI which is intuitive. However, with REST it is sometimes difficult to express resources in a folder-like structure

Also it is hard to model complicate request on resources, e.g. query with different parameters

There are more existing code/ API that  use soap and they are more production-ready. However rest is catching up.

Consider this example  from the JIRA REST API


which search for JIRA issues. one example is /rest/api/2/search?jql&startAt&maxResults&fields&expand

First of all it may not be that intuitive to identify search as a resources. Then there is need to specify a list of parameters, which is similar to non restful WS. Also since there is no side-effect, it supposed to be a get operation, however we can see  that the API itself suggestedIf the JQL query is too large to be encoded as a query param you should instead POST to this resource.”, which is obviously due to limitation of HTTP get request.

SOAP RPC over HTTP, on the other hand, encourages each application designer to define new and arbitrary verbs that suit the usage e.g. getUser. It can be considered more Method-oriented.

Specific Application need

Here suggest that as Soap does retain state and this gives it a special advantage over REST for services that need to preform transactions where multiple calls to a service are need in order to complete a task.

Also  SOAP is more suitable for enterprise level services that implement standard exchange formats in the form of contracts while not supported by REST currently, and SOAP is more reliable with WS-Security, WS-AtomicTransaction and WS-ReliableMessaging.

Both SOAP and REST support SSL but WS-Security more features. Transaction in REST is not fully ACIDic. There is also no built in reliability with SOAP. However, since SOAP message is serialized, it is pass by value instead of reference, which may create synchronization errors and need special care.


In my opinion, REST is becoming more prevailing for most use cases in the world wide web. Meanwhile SOAP should also be in considerations as it may better suit some specific application need.


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s