Best Practices from Oracle Development's A‑Team

  • July 22, 2014

Introduction to FMW 12C REST adapter

In this entry, I will present the usage of the new REST adapter using OSB 12C.  This adapter is a new feature providing support for RESTful web services; it also supports JSON request and response.   One important thing to keep in mind is the internal implementation of the message within OSB is SOAP/XML, there are transformations between JSON and XML during the message processing.


Use Case


I have deployed a JAX-RS service on the server with the following interfaces and we are going to expose this on OSB.



public Response putUserVIP(CompoundObject element);



public Response complexRest(
             CompoundObject obj,  
             @PathParam("year") int year,
             @PathParam("month") int month,
             @PathParam("day") int day);



public Response getUsers(
                    @PathParam("year") int year,       
                    @PathParam("month") int month,
                    @PathParam("day") int day,
                    @QueryParam("from") int from,
                    @QueryParam("to") int to,
                    @QueryParam("orderBy") String orderBy);



public Response otherwise(
                @FormParam("name") String name,
                @FormParam("id") int id,
                @PathParam("year") int year,
                @PathParam("month") int month,
                @PathParam("day") int day);


The inbound  CompoundObject is of the format

{ “key” :  “keyname” , “value” : “valuetext” }


The response is in the format

{  “value” : “valuetext” }




Step 1     Launch JDeveloper and start the integration server


Step 2     Create a new service bus application with service bus project


Step 3     Import the WADL of the JAX-RS service as Service Bus Resources


Right click on the new project-> Import -> Service Bus Resources -> Resources from URL





Step 4    Create a REST service reference


Drag the REST adapter to the External Services swim lane.




Step 5     Define the REST bindings


In the operation bindings,  select Add operations based on WADL service and use the wadl just imported.


You will get the warning dialogs and take some time to read it.   The warnings are reminders that we need to provide the operations bindings details.





Since the operation bindings are not completed, we need to modify each one and provide the operation details:


  1.      1. Request and Response schemas
  2.      2. Request and Response payload types
  3.      3. Request URI parameters details


For getUsers operation request bindings, we need to provide the mappings between the internal SOAP/XML payload to the URI parameters when it is invoking the outbound call.   In this case since this is a GET operation and the values are from the payload in the format of:


$msg.request/<parameter name>




In the Response dialog, we need to provide the schema for the result.  Since we do not have the xsd schema defined yet,  we are going to use the native format builder to create one for us.

Click on the Define Schema for Native Format icon on the right corner.



The native format builder allows us to define different the schema from various format, here we use JSON.



Let’s use a sample payload and the builder will generate the schema for us.





For the complexRest operation.  In the Request tab,  since this is a PUT with a JSON payload, the URI parameters cannot be mapped to the same payload.  In this case we will use the expression in the following format for the mappings, at runtime, the values can be provided in the outbound variable's user-metadata.


$property.<property name>




For the otherwise operation, we have both template parameter and URL-encoded payload, so the request URI parameters mappings look like this:



Once we completed all the details for every operation, the external business is generated.



We can test the service by right click on the external service and select Run







Step 6   Create pipeline and expose as REST


Next we will create a pipeline, connect the business service and expose the pipeline as REST.


Right click in the Pipeline/Split joins swim lane and select create pipeline and connect the pipeline and RestReference service upon completion.

Note:  Do not select expose as proxy service yet.



Right click on the RestPipeline and select expose as REST



You will need to complete the REST bindings for the proxy service similar to the business service.  In our example, we just reuse the schemas and mappings created earlier,  but you are free to define your own interfaces and schemas.




Step 6   Complete the pipeline for pass through actions


If you open the pipeline design, you will see the pipeline is just a straight pass through to the back end using the inbound operation for outbound request.




If you try to execute the PUT/POST operation that also has URI parameters (putTest, otherwise), you will receive an error complaining missing parameters.   This is because the OSB store those URI parameters in the inbound variable and they need to populate to the outbound variable.


<con:endpoint name="ProxyService$RestfulProject$RestService" xmlns:con="http://www.bea.com/wli/sb/context">





<con:request xsi:type="http:HttpRequestMetaData" xmlns:http="http://www.bea.com/wli/sb/transports/http" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

<tran:headers xsi:type="http:HttpRequestHeaders" xmlns:tran="http://www.bea.com/wli/sb/transports">




<tran:user-metadata name="year" value="2014" xmlns:tran="http://www.bea.com/wli/sb/transports"/>

<tran:user-metadata name="month" value="5" xmlns:tran="http://www.bea.com/wli/sb/transports"/>

<tran:user-metadata name="day" value="6" xmlns:tran="http://www.bea.com/wli/sb/transports"/>





In order to pass the parameters to the backend web services,  we need to insert the meta data if it exists.   We will add a  IF-THEN action in the request pipeline and if there is any user-meta data presents in the inbound request, we populate them in the outbound request:













Once its is completed, you can test the external REST service.




In this blog, I showed the basic usage of REST adapter:


  • Internal implementation as SOAP/XML
  • How to define REST business and proxy service
  • Use of native format builder to define schema for transformation
  • Use of $msg.request and $property expression in different use cases for request bindings
  • URI parameters stored as user-metadata in the inbound context variable for PUT/POST operations.


JDeveloper projects are here:  CodeSampleRestAdapter12c


Be the first to comment

Comments ( 0 )
Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.Captcha