Restful Proxy Services

Sample Number

101

Level

Introductory

Description

This sample demonstrates the usage of UltraESB to proxy REST services

Use Case

I have a REST service and I want to mediate the invocation of this REST service with the ESB. Any response going with HTTP "Location" headers from the back end REST service needs to be switched to ESB, so that all traffic to the REST service goes through the ESB.

101 restful proxy

As shown in the above diagram, instead of directly talking to the REST service, UltraESB acts as the proxy for all the requests going to the back-end server.

Sample Configuration

The configuration for this use case is straight forward which consists of a proxy service, exposed on the HTTP/S transports and forwards the incoming message into the target back-end service configured using the in destination of the proxy service.

Proxy service configuration for the restful proxy service

 1<u:proxy id="rest-proxy">
 2  <u:transport id="http-8280">
 3    <u:property name="ultra.transport.url" value="rest-proxy*"/>
 4  </u:transport>
 5  <u:target>
 6    <u:inDestination>
 7      <u:address type="prefix">http://localhost:9000/rest-services</u:address>
 8      <u:property name="ultra.endpoint.switch_location_headers_to" value="http ://localhost:8280/service/rest-proxy"/>
 9    </u:inDestination>
10    <u:outDestination>
11      <u:address type="response"/>
12    </u:outDestination>
13  </u:target>
14</u:proxy>

The configuration also specifies the response from the rest back-end service to be delivered back to the caller, using a response type endpoint. The property "ultra.endpoint.switch_location_headers_to" configures the HTTP Location header to be re-written with the specified value if there are any Location or Content-Location headers in the response, making all subsequent requests to go through the ESB.

Note
For the simplicity the complete configuration is not displayed here, you may look at the complete configuration either from the binary distribution under samples/conf/ultra-sample-101.xml, or from the sample 101 configuration of the source tag.

In Action

To run the example, start the UltraESB sample configuration 101 via the ToolBox or on the command line as follows.

Running the sample from startup script

$ cd /opt/ultraesb-2.6.1/bin
$ ./ultraesb.sh -sample 101

Now start the SOA Toolbox, and fire-up the sample Jetty server on port 9000 that holds a RESTEasy sample service for testing.

The proxy service endpoint will be http://localhost:8280/service/rest-proxy, while the original RESTEasy sample hosted on the Jetty server is available at http://localhost:9000/rest-services/customers. To create a new Customer record, first change the URL to http://localhost:9000/rest-services/customers,  load a sample request using Preset "3" from the HTTP/S client of the ToolBox, and issue it against the RESTEasy service using POST. Your response will be as follows;

Response for the create request to the backend RESTEasy service

HTTP/1.1 201 Created
Location: http://localhost:9000/rest-services/customers/1
Connection: close
Server: Jetty(8.1.13.v20130916)

Now change the URL to http://localhost:8280/service/rest-proxy/customers and issue the same request over POST against the UltraESB proxy service. The second Customer instance will now be created in the backend,and a response similar to the following returned.

Response for the create request to the ESB proxy service

HTTP/1.0 201 Created
Location: http://localhost:8280/service/rest-proxy/customers/2
Date: Web, 17 Aug 2016  04:54:51 GMT
Server: UltraESB/2.6.1
Content-Length: 0
Connection: close

Note that when the request was made through the Proxy Service, the "Location" header of the response has been re-written so that a subsequent call by the client will be directed to the Proxy service itself, instead of the Location returned by the RESTEasy sample - which can be seen in the first response.

To experiment with REST features, you can now perform a GET operation on the returned 'Location'. A GET on URL http://localhost:8280/service/rest-proxy/customers/2 will return the following;

Response for the GET customers/2 from the ESB

HTTP/1.0 200 OK
Content-Type: application/xml
Date: Web, 17 Aug 2016  04:56:53 GMT
Server: UltraESB/2.6.1
Content-Length: 243
Connection: close

<customer id="2">
   <first-name>Asankha</first-name>
   <last-name>Perera</last-name>
   <street>12 A 1 Pirivena Road</street>
   <city>Mount Lavinia</city>
   <state>LK</state>
   <zip>10370</zip>
   <country>Sri Lanka</country>
</customer>

To modify a customer instance, issue a PUT on the URL with a request payload to replace the resource. For example, edit the Preset "3" request and set the "first-name" element to something different. As an example, issuing a PUT on the URL http://localhost:8280/service/rest-proxy/customers/2 with first-name set to "Chamath" will return the following response confirming the update.

Response for the PUT request to update customers/2 from the ESB

HTTP/1.0 204 No Content
Date: Web, 17 Aug 2016  05:01:53 GMT
Server: UltraESB/2.6.1
Connection: close

A subsequent GET on the URL will now return the updated request as follows;

Response for the GET request for customers/2 after the update from the ESB

HTTP/1.0 200 OK
Content-Type: application/xml
Date: Web, 17 Aug 2016  05:04:35 GMT
Server: UltraESB/2.6.1
Content-Length: 243
Connection: close

<customer id="2">
   <first-name>Chamath</first-name>
   <last-name>Perera</last-name>
   <street>12 A 1 Pirivena Road</street>
   <city>Mount Lavinia</city>
   <state>LK</state>
   <zip>10370</zip>
   <country>Sri Lanka</country>
</customer>

Issuing a DELETE on the same URL will remove the Customer instance from the backend, with a response similar to the following,

Response for the DELETE cutomers/2 request from the ESB

HTTP/1.0 204 No Content
Date: Web, 17 Aug 2016  05:05:31 GMT
Server: UltraESB/2.6.1
Connection: close

Any subsequent operations (e.g. a GET) on the URL will return a "404 Not Found" response from RESTEasy

Response for the GET customers/2 request after deleting from the ESB

HTTP/1.0 404 Not Found
Date: Web, 17 Aug 2016  05:06:56 GMT
Server: UltraESB/2.6.1
Content-Length: 0
Connection: close

That demonstrates all the major REST operations working smoothly with the UltraESB REST proxy.

Related Samples

Sample Number

Sample Title

201

Proxying SOAP Messages

In this topic
In this topic
Contact Us