In his dissertation, Architectural Styles and the Design of Network-based Software Architectures (see the Resources section for a link), Roy T. Fielding explains REST as this:
"Representational State Transfer is intended to evoke an image of how a well-designed Web application behaves: a network of web pages (a virtual state-machine), where the user progresses through an application by selecting links (state transitions), resulting in the next page (representing the next state of the application) being transferred to the user and rendered for their use."
So, in simple terms, REST is an architectural style for network systems. But let's try to quickly understand what REST is about.
In all of your Web searching, all you're really doing is locating a variety of
artifacts, or resources. When you type
http://ws.apache.org/axis2 into a browser to navigate
the Apache Axis2 Web site, you get an HTML resource on a server. In other words,
you get a representation of a resource located on that server. This
resource representation puts you, accessing the resource, in a state. When
you click a link on that page, you get a representation of another resource. Now
the state of the client (you) is changed; in other words, you undergo a state
transfer. When you continue to access various resources by following the
links, you keep changing state. This is what REST means in simple terms.
It's important to note that REST by itself cannot be considered a standard.
Having understood what REST means, let's try to quickly recap what SOAP is. SOAP (which is considered to be not so simple anymore!) is a messaging protocol defined on top of XML. Two messaging entities can exchange data as SOAP messages, which both entities can understand due to its language independence. Take a look at a typical SOAP message.
Listing 1. Sample SOAP Message
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/03/addressing"> <soapenv:Header> <wsa:MessageID> uuid:920C5190-0B8F-11D9-8CED-F22EDEEBF7E5</wsa:MessageID> <wsa:To> http://localhost:8081/axis/services/BankPort</wsa:To> </soapenv:Header> <soapenv:Body> <axis2:echo xmlns:axis2="http://ws.apache.org/axis2">Hello World </axis2:echo> </soapenv:Body> </soapenv:Envelope>
SOAP messages contain an
Envelope element, which
encapsulates a mandatory
Body element and the optional
Header element. The
element contains all the information that is to be delivered to the application.
Header is mostly used to provide quality of service
(QoS) like WS-Addressing, WS-Security, WS-ReliableMessaging, and other related
Now look at some of the major differences between SOAP and REST:
- REST is resource oriented, while Web services (WS) are service oriented..
- REST mostly uses HTTP as the transport, while SOAP has no restriction in any means on a particular transport. Many people use REST style interactions using HTTP.
- When you use REST, all the QoS parameters must be provided by the transport itself. In WS, there are lots of specifications built to support QoS options, using WS-* specifications.
Both models have their strong and weak points, and sometimes they become complementary. Because REST continuously promotes simplification, it has become sort of a burden on people who define new WS-* specifications to rethink the simplification.
The WSDL 2.0 HTTP binding specification provides all the rules for this marriage. But it's worth noting that even though different people have different perspectives on what REST means, the objective in putting these two together is to support plain old XML (POX) interactions with services over basic HTTP operations like GET, POST, PUT, and DELETE.
Also it's important to keep in mind that we don't have an objective to completely support all of REST. This article covers how services that are exposed as Web services can also be exposed and accessed with REST-style interactions. It defines how to take (certain styles of) an XML Schema and formulate a GET/POST request out of it.
Not all Web services can be exposed with all the various HTTP methods, and these restrictions are defined in the HTTP binding specification.
First, explore how to figure out whether an HTTP binding is available for a
service. According to the WSDL 2.0 HTTP binding specification, the HTTP binding
can be defined by setting the value of a
Listing 2. WSDL binding element with HTTP binding
<description> <binding name="xs:NCName" interface="xs:QName"? type="http://www.w3.org/2006/01/wsdl/http" ..................... ..................... />
When you create messages to be exchanged, you need to concentrate on the different serialization mechanisms. Before you can do that, you need to understand the various content types that are available with HTTP methods. For now, let's focus on the POST and GET methods.
Table 1. Content types supported with HTTP methods
|HTTP Method||Supported Content Types|
|GET||All the parameters come in the request Uniform Resource Identifier (URI). The schema of the message must adhere to Internationalized Resource Identifier (IRI) style|
In addition to this, most of the other content types are also supported with POST method.
Contents of the messages and the payloads are defined either in
InterfaceFault. These elements always refer to an
element in the schema. Depending on the content type, there are restrictions on
the schema of the XML payload, as mentioned in the above table. Now let's try to
understand what IRI style is.
IRI style contains some restrictions that are defined on the schema of the payload, if you try to communicate with a service using GET method. IRI style is defined in the adjuncts of the WSDL 2.0 specification. Take a look at these restrictions:
- The content model of the document element should be defined using a complex type that contains a sequence from XML Schema.
- The sequence must contain only elements. It must not contain other structures,
- The sequence must contain only local element children. These child elements may contain the nillable attribute.
localPartof the document element's
QNamemust be the same as the operations name.
- The complex type that defines the body of the element or its children elements must not contain any attributes.
- If the children elements of the sequence are defined using an XML Schema type,
they must derive from
xs:simpleTypeand must not be of the type or derive from
The IRI style ensures that the parameters you send using your request URI can be converted back in to a valid XML without much trouble. It's easiest to look at an example to understand it.
Try to retrieve user information with only the user's name and age. You need to send the information in Listing 3 to the service.
Listing 3. Sample user information
<GetInformation> <Name>MyName </Name> <Age>22 </Age> </GetInformation>
How can you send this to the service in the request URI itself if you're using the GET method to invoke?
The answer is: http://myserver/PersonInfoService/GetInformation?Name=MyName&Age=22.
IRI style restricts your schema to define an XML sample, like the one above,
because you can't send complicated XML using the GET method. If the
Person element had another subelement,
Address, which in turn has
then there's no way you can serialize this to request parameters without defining
Now you'll see how an HTTP binding can be defined for a Web service operation.
Listing 4. WSDL binding operation
<description> <binding whttp:methodDefault="xs:string"? whttp:queryParameterSeparatorDefault="xs:string"?> <operation ref="xs:QName" whttp:location="xs:anyURI"? whttp:method="xs:string"? whttp:inputSerialization="xs:string"? whttp:outputSerialization="xs:string"? whttp:faultSerialization="xs:string"? whttp:queryParameterSeparator="xs:string"?> </operation> </binding> </description>
An HTTP binding extension is designed to minimize what needs to be explicitly declared for common cases. As you can see, this is achieved by defining default values. Take a look at what the above WSDL fragment tries to express:
- Binding element— You can define the default HTTP method that should be used using
whttp:methodDefaultand the separator for query parameters using
- Operation element— For each and every operation you have the option of defining following
- location— Location of this operation. Most of the time this is a relative URI that needs to be combined with the endpoint base URI (Defined in the Endpoint element of the WSDL 2.0 document) to form a full URI. You can define a template for the URI here. This will be combined with the endpoint base to form a full URI to send the request.
- method— The HTTP method that can be used to invoke this operation. Value should be one of GET, POST, PUT, or DELETE.
- inputSerialization— How data should be serialized in sending a request to the service. This is defined by providing the proper content type.
- outputSerialization— How the response will be serialized to be sent. This is defined by providing the proper content type.
- faultSerialization— If a fault occurs, this is the serialization mechanism for that.
- queryParameterSeparator— The separator for query parameters.
The following are the default input and output serialization values available for GET and POST operations.
Table 2. Default input and output serializations
|HTTP method||Default input serialization||Default output serialization|
The motivation of WSDL 2.0 HTTP binding is that it allows services to have both SOAP and HTTP bindings. The service implementation deals with processing application data, often represented as an XML element, and the service doesn't know whether that data came inside a SOAP envelope, HTTP GET, or HTTP POST. WSDL 2.0 HTTP binding enables you to expose a service as a resource to be invoked using HTTP methods. At the same time, you need to understand that HTTP binding doesn't enable you to implement a full REST style system. This is often debated by a lot of people, and it all depends on how much you believe in what REST can deliver.
Look for Part 2 of this article series, which explores how the above concepts can be used with two open source Web service engines: Apache Axis2/Java and Apache Axis2/C.
"WSDL 2.0 HTTP Binding Extension"
for a complete HTTP binding extension from WSDL 2.0 adjuncts.
- Learn more about the
"Architectural Styles and the Design of Network-based Software Architectures,"
a PhD dissertation by Roy T. Fielding describing more about REST.
SOA and Web services
zone on IBM® developerWorks hosts hundreds of informative articles and
introductory, intermediate, and advanced tutorials on how to develop Web services
IBM SOA Web site
offers an overview of SOA and how IBM can help you get there.
- Stay current with
developerWorks technical events and webcasts.
- Browse for books on these and other technical
topics at the
- Check out a quick
Web services on demand demo.
- Get an
RSS feed for this series.
(Find out more about RSS.)
Get products and technologies
- Innovate your next
development project with
IBM trial software,
available for download or on DVD.
- Participate in the discussion forum.
- Get involved in the developerWorks community
by participating in