Sample Number |
101 |
Level |
|
Description |
This sample demonstrates the usage of UltraESB to proxy REST services |
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.
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.
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. |
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.