Mobile backend with REST services and JSON payload based on SOA Suite 12c for Live Mobile Hacking with an OFM 12c red stack - Part 2 image46

Mobile backend with REST services and JSON payload based on SOA Suite 12c for Live Mobile Hacking with an OFM 12c red stack – Part 2

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:

image

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:

image

 

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)

image

 

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)

image

 

 

To update the status of a flight : PUT request to /FlyingHigh/FlightService/FlightService/flights – with a JSON request payload as follows:

image

 

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:

image

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:

image

 

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.

image

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.

SNAGHTML2333454

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:

SNAGHTML24b19c2

 

And load the sample of the JSON message payload:

SNAGHTML24becba

The wizard will now create the NXSD representation of this JSON message format:

SNAGHTML24d59bf

Close the wizard.

Back in the Response tab, we can generate a sample of the message payload in JSON or XML format:

 

image

The operation to fetch the passengerlist can be defined a similar way:

SNAGHTML2515c6d

and the details:

image

 

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:

image

 

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:

image

 

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.

image

The overall project looks like this:

 

image

 

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:

image

This results in a SOA composite instance with the following flow trace:

image

We can look at the details of what happens inside the Mediator:

image

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:

image

but that does not add much value.

The really interesting next step is when Luc starts implementing the mobile app against these REST services.

SNAGHTML21929f7

 

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:

image

and then the result inside the SOA Suite and BPM Suite:

SNAGHTML21b9c87

 

 

Some artist’s impressions from the actual live demo

 

Here some pictures from the actual demo, courtesy of Luis Weir:

image

image

image

image

and Sten Vesterli:

image

and Jim Weaver:

image

and Vikas Anand:

image

and Jan van Hoef:

image

and José Rodrigues

image

and Simon Haslam:

image

and Jacco Cijsouw:

image

 

and one last one taken by me from stage:

image