This article continues the story from Mobile backend with REST services and JSON payload based on SOA Suite 12c for Live Mobile Hacking with an OFM 12c red stack – Part 1. It is the story of how to expose SOAP/XML based Web Services – primed for enterprise integration and process automation – as REST services with URL parameters and JSON payloads that provide the mobile backend APIs required for the development of mobile apps. The story began with the challenge Luc Bors and I were facing for the Live Mobile Hacking session at the Oracle Fusion Middleware EMEA Partner Forum (March 2015). For an audience of some 200 SOA Suite and Oracle Middleware experts – including the product management teams for several of the products we were going to demonstrate – we were to develop live both a mobile app as well as a mobile backend (REST APIs) to support the mobile app.
The use case was defined – an app for flight attendants to be used on tables to look up flight details, inspect the passenger list, update the flight status and record passenger complaints. Luc handled the mobile app based on the agreements we made on the REST resources, services and payloads. It was up to me to implement the backend – consisting of a database, a SOA composite to expose the database data and operations at middleware level (in SOAP/XML) – as described in the previous article. Next, I needed to implement a Service Bus project to expose the required REST service interface with JSON payload, leveraging the SOAP/XML service published by the SCA Composite. That is the story told in this sequel – the part highlighted in the red rectangle in the next picture:
This article will briefly describe the steps I went through to create the REST services on top of the SOAP/XML services. At the end of this article, the end to end flow from the above illustration will have been implemented.
All source code for the mobile backend can be downloaded from a GitHub repository.
Steps:
- Design REST services, Resources, URLs and JSON payloads
- Create REST proxy services in Service Bus project
- Create Pipeline to connect REST proxy to Business Service for SOAP/XML services with appropriate transformations between message formats (JSON/XML and vice versa)
- Publish Service Project and test end-to-end REST services (all the way down to the database and back again)
At the end of this article, here is what we have achieved:
At this point, the Mobile App can come off the mock services it has undoubtedly used during development, and start consuming the real services.
Step One – Design REST services, Resources, URLs and JSON payloads
Luc and I had discussed the functionality to be offered in the mobile app. Subsequently, Luc indicated the REST services he would require to implement the app. Both in terms of functions and in terms of the actual URLs patterns and JSON payloads. The latter can be found in this GitHub directory.
The former were defined as follows:
To retrieve flight details: GET request to /FlyingHigh/FlightService/FlightService/flights/<flight code>?flightDate=2015-03-07 (with a JSON response structured as shown below)
To retrieve the passenger list for a flight : GET request to /FlyingHigh/FlightService/FlightService/flights/<flight code>/passengerlist?flightDate=2015-03-07 (with a JSON response structured as shown below)
To update the status of a flight : PUT request to /FlyingHigh/FlightService/FlightService/flights – with a JSON request payload as follows:
The REST service for submitting a complaint from a passenger was defined the other way round: I dictated the service interface and Luc simply had to consume it – as an example of how ideally you should not do things in mobile app development. The call for submitting the complaint has to be sent as a POST request to: soa-infra/resources/default/CustomerService!1.0/CustomerCareService/complaints with a JSON payload structured like this:
Note: the CustomerCareService is exposed from a SOA Composite directly, not through the Service Bus proxy that is created in the remainder of this article. The flow for requests to this service is as follows – a BPM process being triggered as a result:
Step Two – Create REST proxy services in Service Bus project
The REST adapter wizard in JDeveloper can be used in two ways: either take an existing Pipeline (Service Bus) or Component (such as Mediator or BPEL) and derive a REST binding from the existing SOAP/XML service interface (not an ideal approach) or design a REST service with corresponding payload as desired and have the adapter wizard generate the internal SOAP/XML representation that can be connected through a Pipeline or Mediator. The latter is the approach to be used when the REST service design is leading – as it usually is, including this case.
The starting point is a Service Bus project that already contains a Business Service for the FlightService SOA Composite. This business service obviously exposes the same SOAP/XML interface exposed by the composite.
What we are after, is a REST service exposed by this Service Bus project – of which the interface definition is predefined by Luc. We can create this from the context menu in the Proxy Services swim
lane. The wizard for configuring the REST binding appears.
Set the name to FlightRestService.
Now for each operation the service should expose, a Resource should be configured. For example for the retrieval of FlightDetails using /FlyingHigh/FlightService/FlightService/flights/<flight code>?flightDate=2015-03-07
Press the gears icon to specify the format for the response payload. This is expressed through an XSD document that describes the native format for the response; we call this type of document an NXSD document – in this case for example nxsd_retrieveFlightDetails.xsd.
Choose the type of format:
And load the sample of the JSON message payload:
The wizard will now create the NXSD representation of this JSON message format:
Close the wizard.
Back in the Response tab, we can generate a sample of the message payload in JSON or XML format:
The operation to fetch the passengerlist can be defined a similar way:
and the details:
Note: the endpoint definition for the REST service is set like this – a bit silly really, with the duplicate FlightService that we will have to use when invoking the service, for example from the browser:
Step Three – Create Pipeline to connect REST proxy to Business Service
Create Pipeline to connect REST proxy to Business Service for SOAP/XML services with appropriate transformations between message formats (JSON/XML and vice versa).
Add a Pipeline (for example FlightPipeline) that implements the WSDL created for the REST Proxy Service. The REST proxy can invoke this pipeline, handing it the XML representation (described by the NXSD document) of the URI parameters received in the REST call. It expects to receive the XML representation (also described in the NXSD) of the JSON payload of the response message.
XQuery of XSLT based transformations are required between the NXSD description of the request and the XSD description of the input to the business service FlightServiceBS and between the output from the FlightServiceBS and the required NXSD format to be returned to the REST Proxy Service.
The next figure lists the six transformations created between NXSD and XSD-for-Business Service:
The pipeline between REST proxy and Business Service contains an operational branch – for the three REST operations in the FlightService. In each operation, it does similar things: transform the request, route to the business service and transform the response.
The overall project looks like this:
Step Four – Publish Service Project and test end-to-end REST services
Nothing special about deployment, so I will skip that part.
After deployment, the REST services can be invoked. An example is:
This results in a SOA composite instance with the following flow trace:
We can look at the details of what happens inside the Mediator:
to learn that what we get in JSON is pretty much what was constructed in the PL/SQL package in the database. No surprise there.
Of course I can invoke the other REST services as well:
but that does not add much value.
The really interesting next step is when Luc starts implementing the mobile app against these REST services.
Perhaps the Passenger Complaint is mildly interesting – as it causes some activities, as illustrated by the next two pictures:
first the call to the REST service for (POSTing) customer complaints:
and then the result inside the SOA Suite and BPM Suite:
Some artist’s impressions from the actual live demo
Here some pictures from the actual demo, courtesy of Luis Weir:
and Sten Vesterli:
and Jim Weaver:
and Vikas Anand:
and Jan van Hoef:
and José Rodrigues
and Simon Haslam:
and Jacco Cijsouw:
and one last one taken by me from stage:
