7 Developing RESTful Web Services

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

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>

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.

<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

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

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

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.

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