Introduction to Developing RESTful Web Services

9.1 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://java.sun.com/javaee/5/docs/api/javax/xml/ws/Provider.html). The Provider interface provides a dynamic alternative to building an service endpoint interface (SEI).

9.2 How RESTful Web Services Requests Are Formed and Processed

A description of how RESTful web service requests are formed on the client side and how they are processed on the server side is detailed in these sections:

9.2.1 HTTP Get Requests

RESTful web services support HTTP Get Requests. You can invoke RESTful requests by using a GET with a specific URL.

This section describes how to build HTTP Get Requests. It includes the following sections:

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

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

9.2.1.2 Building HTTP Get Requests

You can invoke RESTful requests 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.

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

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

<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 addNumbers operation example.

9.2.2 HTTP Post Requests

RESTful web services support HTTP POST Requests that are simple XML messages and not SOAP envelopes.

This section describes how to build HTTP POST Requests. It includes the following sections:

9.2.2.1 About the HTTP Post Requests

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.

9.2.2.2 Building HTTP Post Requests

You can process RESTful requests 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, this RESTful request will be wrapped in the SOAP envelope illustrated the following 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.

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

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

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

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

9.3 Understanding the Limitations of RESTful Web Service Support

Oracle Web Services support for RESTful web services is constrained by certain limitations.

The following list describes the limitations.

RESTful web service support is available only for web service applications with literal operations (both request and response should be literal).
HTTP GET is supported only for web service operations without (required) complex parameters.
Some browsers limit the size of the HTTP GET URL, typically to 2000 characters or less. Try to keep the size of the URL small by using a limited number of parameters and short parameter values and names.
RESTful web services send only simple XML messages. You cannot send messages with attachments.
Many management features, such as security and reliability, are not available with RESTful web services. This is because SOAP headers, which are typically used to carry this information, cannot be used with RESTful invocations of services.
RESTful invocations cannot be made from generated Stubs or DII clients. Invocations from those clients will be made in SOAP.
There is no REST support for the Provider framework.
Operation names in RESTful web services cannot contain multibyte characters.