What is REST?

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.

What is SOAP?

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.

<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 Body element contains all the information that is to be delivered to the application. The Header is mostly used to provide quality of service (QoS) like WS-Addressing, WS-Security, WS-ReliableMessaging, and other related standards.

REST vs. Web services

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.

How WSDL 2.0 enabled the marriage of REST and Web services

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.

WSDL 2.0 rules for HTTP binding

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 type attribute of the <Binding> to http://www.w3.org/2006/01/wsdl/http.

<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.

Contents of the messages and the payloads are defined either in MessageReference or 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.

Internationalized Resource Identifier style

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, such as xs:choice.
• The sequence must contain only local element children. These child elements may contain the nillable attribute.
• The localPart of the document element's QName must 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:simpleType and must not be of the type or derive from xs:QName, xs:NOTATION, xs:hexBinary. or xs:base64Binary.

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.

<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 City and Country elements, then there's no way you can serialize this to request parameters without defining complicated rules.

Defining HTTP binding in WSDL

Now you'll see how an HTTP binding can be defined for a Web service 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:methodDefault and the separator for query parameters using whttp:queryParameterSeparatorDefault.
• Operation element— For each and every operation you have the option of defining following parameters.
  1. 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.
  2. method— The HTTP method that can be used to invoke this operation. Value should be one of GET, POST, PUT, or DELETE.
  3. inputSerialization— How data should be serialized in sending a request to the service. This is defined by providing the proper content type.
  4. outputSerialization— How the response will be serialized to be sent. This is defined by providing the proper content type.
  5. faultSerialization— If a fault occurs, this is the serialization mechanism for that.
  6. queryParameterSeparator— The separator for query parameters.

The following are the default input and output serialization values available for GET and POST operations.

Does WSDL 2.0 enable REST?

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.

Resources

Learn

• Read "WSDL 2.0 HTTP Binding Extension" for a complete HTTP binding extension from WSDL 2.0 adjuncts.
  
  
• Learn more about the HTTP 1.1 Specification
  
  
• Read "Architectural Styles and the Design of Network-based Software Architectures," a PhD dissertation by Roy T. Fielding describing more about REST.
  
  
• The 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 applications.
  
  
• The 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 Safari bookstore.
  
  
• 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.
  
  

Discuss

• Participate in the discussion forum.
  
  
• Get involved in the developerWorks community by participating in developerWorks blogs.
  
  

About the author

Eran Chinthaka is a pioneering member of the Apache Axis2, Axiom, and Synapse projects, and he is a member of WSDL 2.0 and WS-Addressing working groups.

Rate this article

Comments

Back to top

Table of contents

• What is REST?
• What is SOAP?
• REST vs. Web services
• How WSDL 2.0 enabled the marriage of REST and Web services
• Does WSDL 2.0 enable REST?
• Resources
• About the author
• Comments

Next steps from IBM

Rational Tester for SOA Quality is an automated web services testing and SOA testing tool that supports Web services SOAP, HTTP(S), JMS, WS-Security, UDDI, and RESTful standards.

---

• Try: The no-charge Rational Service Tester for SOA Quality helps quality assurance professionals validate web service based SOA application..
• Article: See the whats new with Rational Service Tester for SOA Quality, and its Generic Service Client, which provides a single client to interact with any SOA service type.
• Tutorial: Get hands-on experience with this Transport for SOAP feature tutorial using Rational Tester for SOA Quality.
• Buy: Rational Service Tester for SOA Quality

Dig deeper into SOA and Web services on developerWorks

IBM SmartCloud trial. No charge.

Unleash the power of hybrid cloud computing today!

---

Public and private solutions in one trial.

Special offers