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.
The following request will be processed as a normal SOAP request.
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.
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.
Limitations of RESTful Web Service Support
The following list describes the limitations in Oracle Web Services support for RESTful Web services.
-
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.