Skip Headers
Oracle® Fusion Middleware Developer's Guide for Oracle Infrastructure Web Services
11g Release 1 (11.1.1)

Part Number E15184-06
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

8 Developing RESTful Web Services

This chapter introduces Representational State Transfer (RESTful) Web service concepts and describes how to develop and configure RESTful Web services using Java API for RESTful Web Services (JAX-RS).

This chapter includes the following topics:

Overview of RESTful Web Services

Representational State Transfer (REST) describes any simple interface that transmits data over a standardized interface (such as HTTP) without an additional messaging layer, such as SOAP. REST provides a set of design rules for creating stateless services that are viewed as resources, or sources of specific information, and can be identified by their unique URIs. A client accesses the resource using the URI, a standardized fixed set of methods, and a representation of the resource is returned. The client is said to transfer state with each new resource representation.

When using the HTTP protocol to access RESTful resources, the resource identifier is the URL of the resource and the standard operation to be performed on that resource is one of the HTTP methods: GET, PUT, DELETE, POST, or HEAD.

You build RESTful endpoints using the invoke() method of the javax.xml.ws.Provider<T> interface (see http://docs.oracle.com/javaee/5/api/javax/xml/ws/Provider.html). The Provider interface provides a dynamic alternative to building an service endpoint interface (SEI).

How RESTful Web Services Requests Are Formed and Processed

The following sections describe how RESTful Web service requests are formed on the client side and how they are processed on the server side.

Building HTTP Get Requests

If a SOAP endpoint that is REST enabled is deployed at the following URL:

http://example.com/my-app/my-service

Then HTTP GET requests will be accepted at the following URL:

http://example.com/my-app/my-service/{operationName}?{param1}={value1}&{param2}={value2}

In the example above, {operationName} specifies one of the operation names in the WSDL for the service. For RPC-literal operations, {param1}, {param2}, and so on, are the part names defined in the operation's input wsdl:message. Note that these must be simpleTypes (xsd:int, and so on).

Note:

Some browsers limit the size of the HTTP GET URL (typically less than 2000 characters). Try to keep the size of the URL small by using a limited number of parameters and short parameter names and values.

For document-literal operations, messages have only a single parameter. To simulate multiple parameters, the WSDL specifies a single parameter that is defined in the schema as a sequence. Each member of the sequence is considered a parameter. In this case, {param1}, {param2}, and so on, will be the members of the sequence type, instead of message parts. As with RPC-literal, these must be simpleTypes.

The following example illustrates the request message defined for an operation named addNumbers.

Example 8-1 GET Request on an Operation

<wsdl:message name="AddNumbersRequest"> 
      <wsdl:part name="a" type="xsd:int" /> 
      <wsdl:part name="b" type="xsd:int" />
</wsdl:Message>

This request can be invoked by using a GET with the following URL:

http://{yourhost}/{context-path}/{service-url}/addNumbers?a=23&b=24

The following example illustrates the SOAP envelope that the Oracle Web Services platform will create on the server side from the GET request. This message will be processed like any other incoming SOAP request.

Example 8-2 SOAP Envelope Created from a GET Request

<soap:Envelope> 
    <soap:Body> 
        <ns:addNumbers> 
            <ns:a>23</ns:a> 
            <ns:b>24</ns:b> 
        </ns:addNumbers> 
    <soap:Body> 
<soap:Envelope>

The following example illustrates the request message sent for the addNumbers service when it is defined as a document-literal operation.

Example 8-3 Sample GET Request on a Document-Literal Wrapped Operation

<wsdl:message name="AddNumbersRequest"> 
     <wsdl:part name="params" type="tns:AddNumbersRequstObject" />
</wsdl:Message>

The following example illustrates the definition of the AddNumbersRequestObject as it would be defined in the schema.

Example 8-4 XML Definition of a Document-Literal Wrapped Operation

<xsd:complexType name="AddNumbersRequestObject"> 
    <xsd:complexContent> 
        <xsd:sequence>
            <xsd:element name="a" type="xsd:int"/> 
            <xsd:element name="b" type="xsd:int"/>
        </xsd:sequence> 
    </xsd:complexContent> 
</xsd:complexType>

This operation can be invoked by a GET request with the following URL.

http://{yourhost}/{context-path}/{service-url}/addNumbers?a=23&b=24

Note:

This is the same URL that is used for the RPC-literal request in Example 8-1.

Build HTTP Post Request

RESTful Web services support HTTP POST requests that are simple XML messages—not SOAP envelopes. RESTful requests do not support messages with attachments. Since the service also supports SOAP requests, the implementation must determine if a given request is meant to be SOAP or RESTful request.

When a SOAP service receives a POST request, it looks for a SOAP action header. If it exists, the implementation will assume that it is a SOAP request. If it does not, it will find the QName of the root element of the request. If it is the SOAP envelope QName, it will process the message as a SOAP request. Otherwise, it will process it as a RESTful request.

RESTful requests will be processed by wrapping the request document in a SOAP envelope. The HTTP headers will be passed through as received, except for the Content-Type header in a SOAP 1.2 request. This Content-Type header will be changed to the proper content type for SOAP 1.2, application/soap+xml.

For example, the following RESTful request will be wrapped in the SOAP envelope illustrated in Example 8-6.

Example 8-5 RESTful Request

<ns:addNumbers> 
    <ns:a>23</ns:a> 
    <ns:b>24</ns:b> 
</ns:addNumbers>

The following request will be processed as a normal SOAP request.

Example 8-6 SOAP Envelope Wrapping the RESTful Request

<soap:Envelope> 
       <soap:Body> 
               <ns:addNumbers> 
                       <ns:a>23</ns:a> 
                       <ns:b>24</ns:b> 
               </ns:addNumbers> 
           </soap:Body> 
</soap:Envelope>

Building RESTful Responses

For any request (either GET or POST) that was processed as a RESTful request, the response must also be in RESTful style. The server will transform the SOAP response on the server into a RESTful response before sending it to the client. The RESTful response will be an XML document whose root element is the first child element of the SOAP body. For example, assume that the SOAP envelope illustrated in the following example exists on the server.

Example 8-7 SOAP Response

<soap:Envelope>
    <soap:Body> 
        <ns0:result xmlns:nso="…"> 
            <ns:title>How to Win at Poker</ns:title> 
            <ns:author>John Doe</ns:author> 
        </ns0:result>
    </soap:Body>
</soap:Envelope>

The following example illustrates the response sent back to the client. Note that the Content-Type will always be text/xml. Any SOAP headers or attachments will not be sent back to the client.

Example 8-8 RESTful Response

<ns0:result xmlns:ns0="…"> 
       <ns:title>How to Win at Poker</ns:title> 
       <ns:author>John Doe</ns:author> 
</ns0:result>

Enabling RESTful Web Services

When administering a Web service using the Oracle Enterprise Manager, you can enable it as a RESTful Web service by setting REST Enabled to true on the Configuration tab of the Web service endpoint page, as shown in the following figure. For more information, see "Enabling or Disabling RESTful Web Services" in Security and Administrator's Guide for Web Services.

Figure 8-1 Enabling RESTful Web Services

Description of Figure 8-1 follows
Description of "Figure 8-1 Enabling RESTful Web Services"

Limitations of RESTful Web Service Support

The following list describes the limitations in Oracle Web Services support for RESTful Web services.