Posts Tagged 'REST'

Branching in Native REST Services

In previous post, we are introduced to native REST services (Typed and Un-typed) support in 12.2.1. But we can observe following issues there:

  • We used only GET method for demonstration and typically this would not be the case as REST service can also support other HTTP methods (POST, PUT and DELETE).
  • No branching in Typed REST Services when multiple HTTP methods are supported.
  • No branching in Un-Typed REST Services when multiple HTTP methods are supported.

In this post, we will try to cover above aspects. Note that all of this discussion is related to native REST services unless stated otherwise.

Branching in Typed REST Services:

Add POST method support for typedEmployees resource as shown below.





Since Typed REST Service uses WADL and contains Operation name annotated with soa:name, we can simply make use of Operational Branch.


You can use URL like below to access REST Service.


Branching in Un-Typed REST Services:

Since Un-Typed REST services does not use WADL, we can’t use Operational Branch as above. So in this release, OSB introduced a new node called  REST Branch for this purpose.


Add REST Branch in pipeline by dragging it from Components.


For each REST branch, give supported Media Types, Resource Path and HTTP method mandatorily.


Use + icon to add media types and give other information as shown below. This means we are creating a REST resource called  untypedEmployees which supports GET and supported media types are  application/xml, application/ json.


Modify REST branch name in General section of Properties. We can add more branches using highlighted icon below.


We can add POST method support for same resource path as shown below.




Test Proxy as shown below. Note that we had specified required parameters in HTTP headers.



You can use URL like below to access this REST Service and make sure that Content-Type is passed without fail.



  • OSB parses payload based on  HTTP header Content-Type in request. We can Use Log activity to see $body contents. Refer  to this post to enable logging.
  • When Content-Type is application/xml, $body is logged as below.

PostPipelinePair, request-ab047b9.N47e0f03.0.15591b0ca2c.N7d1d, Stage1, REQUEST] CreateEmployeeLog: <soapenv:Body xmlns:soapenv="http://schemas.">[[<a><b>1233333</b></a></soapenv:Body>]]

  • When Content-Type is application/json, $body is logged as below.

[PostPipelinePair, request-ab047b9.N47e0f03.0.15591b0ca2c.N7d1d, Stage1, REQUEST] CreateEmployeeLog: <soapenv:Body xmlns:soapenv=" soap/envelope/">{"a":1234,"b":3455}</soapenv:Body>

  • OSB binds a globally-scoped object called process and can be used as process.body or process.var which is similar to $body and $xyz XPath variables. This notation is used for Java Script expressions. Use Log activity as below in Java Script expressions to verify the same.




  • When Content-Type is application/xml, process.body is logged as below

[PostPipelinePair, request-ab047b9.N47e0f03.0.15591b0ca2c.N7d1d, Stage1, REQUEST] CreateEmployeeLog: <a>[[<b>1233333</b></a>]]

  • When Content-Type is application/json, process.body is logged as below

     [PostPipelinePair, request-ab047b9.N47e0f03.0.15591b0ca2c.N7d1d, Stage1, REQUEST]         CreateEmployeeLog: {"a":1234,"b":3455}

  • Though REST service supports JSON/XML payload, there is no automatic conversion takes place at runtime and to be done programmatically in native REST services.
  • When using End-to-End XML, use XQuery/XSLT for transformation.
  • When using End-to-End JSON, use Java script for transformation.


Service Bus 12.2.1 – REST Support

In this blog, we will review native REST service support added in 12.2.1. And you can refer to post to find information about same from 12.13 perspective.

Before discussing further, we will first see how 12.2.1 provides the backward compatibility with 12.1.3. In 12.1.3, REST Proxy Service converts native REST payload to SOAP before calling a Pipeline/Split-Join and REST Business Service convert SOAP to REST native payload i.e. the internal communication happen using WSDL interfaces only.

In 12.13, while creating REST binding as Proxy or Business service check the option as shown below and other steps remain same.

We can see WSDL and WADL gets created in your project.




To access REST resource use url like http://localhost:<<OSB Port>/<<proxy endpoint>>/<<resource name>>  so it will be http://localhost:7003/restDemo/REST1213WayPS/employees

To access design-time WADL use url like http://localhost:<<OSB Port>/sbresource?WADL/<>/<>  so it will be http://localhost:7003/sbresource?WADL/RESTIn1213way/WSDL/REST1213WayPS

To access effective WADL use url like http://localhost:<<OSB Port>/sbresource?(PROXY or BIZ)/<<project path>>/<<proxy or biz service name>>  so it will be http://localhost:7003/sbresource?PROXY/RESTIn1213way/ProxyServices/REST1213WayPS

Now in 12.2.1, we have native REST support and no need of creating WSDL for internal communication. This native support is broadly classified into following categories:

  • Un-typed Proxy/Business Service –  For which method information is available at design time so no WADL is involved.
  • Typed Proxy/Business Service – For which the method information is available at design time so WADL is used/created having this information.

REST binding can be used to create both Proxy and Business services that fall into above categories. In this post, we discuss from Proxy Service perspective and same can be followed for business services.

Creating Typed Proxy Service:

We use REST binding to create native REST service. So drag REST binding from Components to Proxy Services swim lane or right click to choose REST option.


Provide name for REST binding and do not select WSDL interfaces check box as we are creating native REST services. Click Next.


Create a new REST resource as shown below.



Create a REST method using following steps by clicking + icon in Methods.




Now verify that WADL file is generated automatically with method information as defined above. Now create pipeline using the following steps.





Connect Proxy Service, Pipeline and Business Service as shown below. Use the same business service as we used earlier.


Finish the message flow as shown below.



Deploy and test your project in Service Bus console. Observe that you can see all media types supported by REST service are shown in Accept choice list.



Now we will see how to use an existing WADL to create Typed REST services.

Again drag the REST binding from Components to Proxy Services swim lane or right click in swim lane to choose REST option.


Provide name for REST binding and do not select WSDL interfaces check box as we are creating native REST services. Click Next.


Choose REST1213WayPS.wadl. This confirms that WADLs generated by 1213 REST services are supported here. Observe that REST methods are populated automatically from selected WADL.




Click Finish and verify that new WADL is generated again for this Proxy Service.


Now finish pipeline message flow as above using WADL created in above step.



To access REST resource use url http://localhost:7003/restDemo/typedService/typedEmployees

To access design-time WADL use url http://localhost:7003/sbresource?WADL/RESTTypedServices/TypedRestService

To access effective WADL use url http://localhost:7003/sbresource?PROXY/RESTTypedServices/TypedRestService


  • WADL is always created for Typed native REST services when one is not chosen during creation.
  • No where we are able to give the input/output message structure (XML or JSON schema) for REST methods. I think this may be improved in later releases.
  • When a native REST Proxy Service supports multiple content types (XML, JSON), automatic payload conversion (XML to JSON and vice-versa) is not happening as we see in WSDL based REST services. I will try to cover more on this in later posts.
  • Content-Type HTTP header is used by OSB for content parsing and we can see this set automatically when media type is chosen in test console.
  • Value given for soa:name in WADL is populated for $operation context variable in pipeline.
  • 1213 WADL is not supported for creating pipelines but can be used to create Proxy, however a new WADL will be generated by OSB as we saw above.

Creating Un-typed Proxy Service:

Create a Proxy Service using following steps. Observe the usage of Transport and no where we define REST resource or methods.





Create pipeline using following steps and observe that we are not selecting any WADL as we did earlier.



Connect all these pieces as shown below and complete Message Flow as we did earlier.


Deploy and test your project in Service Bus console. Observe that you can see all media types supported by REST service are shown in Media Type choice list as we have not specified supported types any where. Service Bus uses the Content-Type HTTP header for parsing the payload and you can see this is set automatically when we choose the media type in Test Console.



To access REST resource use url http://localhost:7003/restDemo/untypedService


  • No WADL is used during creation of Un-typed native REST services.
  • Again, no where we are able to give the input/output message structure (XML or JSON schema) for REST methods.
  • Again, no automatic payload conversion will happen when REST Proxy supports multiple Content Types.
  • Content-Type HTTP header is used by OSB for content parsing and we can see this set automatically when media type is chosen in test console.

In above 2 sections, we created  both Proxy and Pipeline separately and we can observe that WADL is optional for REST based pipelines. So even Pipelines are classified into Typed and Un-typed  depending on usage of WADL.

So now the Q arises about compatibility between Proxy and Pipelines as both of them can be Typed /Un-Typed. Since Typed is more restrictive having REST methods we will be able to call both Un-Typed and Typed pipelines provided they used same WADL. In the same way, Un-Typed will be able to call both Un-typed and Typed Pipelines.

The source code used in this post can be downloaded from here and please note that you need to create DB connection pool to run this project with JNDI eis/DB/LocalDB.


ADF BC REST Services Articles

Sample application can be found here.

ADF BC REST Services–III – Using Row Finder

In this post, we will see how to use Row Finder in ADF BC REST services.

Open REST resource VO and create a View Criteria as shown below having 2 bind variables for Department name and Location ID.



Go to Row Finders section and create new one with searhByDeptName.


Here we can observe that above VC is selected by default. In Variables section as shown below, we can also set whether bind variable is allowed to be passed in REST resource URL along with Required settings.


Deploy the application and use any REST client to test GET method using the following urls. Observe the usage of row finder and bind variables.

Passing single bind variable:


Passing both bind variables:


Now mark bindLocId variable as required and try to test without using it in the URL and you will observe the error as shown below.


ADF BC REST Services–II – Change Indicator

In ADF, often we see error saying ‘JBO-25014: Another user has changed the row with primary key oracle.jbo.Key’. The framework throws this error to make sure that none of the user changes are accidentally overwritten by another user and generally occurs when a user trying to modify record that has been just modified and committed by another user. In this post, we will see how to take care of this scenario using ADF BC REST services in context of HTTP PATCH.

ADF BC REST Services make use of attribute called changeIndicator  which can be observed in response of GET.

Follow the steps mentioned below to enable this in a resource:

  • EO should have an attribute marked as Change Indicator and set Track Change History as shown below.


  • Add this attribute in VO i.e to be exposed as REST resource.


Deploy your changes and issue GET to observe changeIndicator as below.



for e.g. changeIndicator for department 10 (resource instance):


Now update department 10 using following sql query to simulate the actual update.

update departments set department_name = ‘Administration-modified’, object_version_number = object_version_number+1
where department_id = 10

Issue GET again on same resource and observe the changeIndicator.




As observed above, the value of changeIndicator changes with each update and is calculated by RESTServlet registered in web.xml of RESTWebService project.


Here is an interesting observation and do issue issuing GET for department 10.


If we observe HTTP response headers, the value of ETag is same as that of changeIndicator. Hence changeIndicator works in similar lines of ETag defined in HTTP specification.


Now let us observe the behavior of REST resource when  ETag is used for If-Match/If-None-Match HTTP headers during GET and PATCH. Basically these HTTP headers tells server to do requested operation when sent Etag value matches or did not match respectively.

Make sure you enclose ETag value with “ (double quotes) as shown below.


Using GET:

  • When resource is not modified, returns status code as 304.


  • When resource is modified, returns response with new changeIndicator value.


Using PATCH:

  • When resource is not modified, returns response status code as 412.


  • When the resource is not modified, then returns response with new changeIndicator value after update.




Not Modified


(Query Successful)
Status: 304


Status: 200
(Update Successful)
Status: 412


Using GET:

  • When resource is not modified, resource is returned.


  • When resource is modified, expected response status code is 304 but shows 200 with junk response.


Using PATCH:

  • When resource is not modified, returns response with new change Indicator value after update.


  • When resource is modified, expected response status code is 412 but shows 200 with junk response. However you will observe that the actual update is not happening though it returns 200.




Not Modified


Status:304 Status:200
(Query Successful)


Status:412 Status: 200
(Update Successful)

Note: As you observed above, ETag combination with If-Match header is not working as expected which is a bug in this release.


ADF BC REST Services-I

In this blog post, We will see how to expose ADF VOs as REST resources. ADF has got native REST support in 12.2.1 release.

We will use Department, Employee VOs and following AM Data Model here.



Creating Release Version:

Creating a release version in adf-config.xml is the first step to be done before exposing any of the AM VOs as resource. Use the following steps to create one and you can follow your own conventions for versioning REST resources. Here I  have given the initial version as r1.




Expose VO as REST resources:

Open AM and navigate to Web Service –> REST and Click + icon.


Creation of REST resources create a new project RESTWebService.jpr in our workspace that can be deployed as WAR through which these REST services get deployed.


Give the resource name as shown below and click OK.


Observe the new RESTWebService project gets created.


Also observe other files related to REST resources that get created as shown below.


You can use the following tabs to choose the methods to be exposed and the attributes to be exposed to consumers.


When a VO has View Links the Resource Structure will show all these VOs as shown below. Check these VOs as shown below if it has to be exposed as child resource.



Modify context root of RESTWebService project as shown below representing the purpose of your REST API.


Optionally, we can modify URL pattern in web.xml as shown below.


Integrated WLS:

Select RESTWebservice project and do Run on right click as shown below.


Standalone WLS:

Create EAR profile for ADF application and include RESTWebService project as shown below and deploy this EAR to standalone WLS.


Once the deployment is done, you can access the REST resource using url like:

http://<<host>&gt;:<<port>>/<<ContextRoot>>/<<url pattern>>/<<version>>/<<resource name>>

For e.g.: http://localhost:7001/departmentApi/rest/r1/departments

We can also use latest keyword to access the latest version of the resource.

For e.g.: http://localhost:7001/departmentApi/rest/latest/departments

You can use any REST client to try out POST, DELETE, PUT, PATCH depending on the operations you exposed on REST resource.

Describing Resource – GET:

URI: http://localhost:7001/departmentApi/rest/r1/departments/describe

Describing Resource Instance – GET:

URI: http://localhost:7001/departmentApi/rest/r1/departments/10/describe


Querying Departments – GET:

URI: http://localhost:7001/departmentApi/rest/r1/departments

Querying a particular Department – GET:

URI: http://localhost:7001/departmentApi/rest/r1/departments/{id}

Creating Department – POST:

URI: http://localhost:7001/departmentApi/rest/r1/departments

Content-Type: application/


“DepartmentId”: 1000,
“DepartmentName”: “Administration”,
“ManagerId”: 200,
“LocationId”: 1700

Deleting a Department – DELETE:

URI: http://localhost:7001/departmentApi/rest/r1/departments/{id}

Updating a Department – POST:

URI: http://localhost:7001/departmentApi/rest/r1/departments/{id}

Content-Type: application/

X-HTTP-Method-Override: PATCH

Body: (contains only fields to be modified)

“DepartmentName”: “Administration-Modified”

Replacing a Department – PUT:

URI: http://localhost:7001/departmentApi/rest/r1/departments/{id}

Content-Type: application/

Body: (Values not sent in body will be set to null)


“DepartmentName”: “Administration-Replace”,
“ManagerId”: 100

Querying Department for a few fields – GET:

URI: http://localhost:7001/departmentApi/rest/r1/departments?fields=DepartmentName,ManagerId

Querying a Department using an attribute – GET:

URI: http://localhost:7001/departmentApi/rest/r1/departments/{id}?q=DepartmentName=Administration

Querying a Department for only Data – GET:

URI: http://localhost:7001/departmentApi/rest/r1/departments?onlyData=true

Will not fetch any links or  metadata for resource instances in response.

Sorting Departments – GET:

URI: http://localhost:7001/departmentApi/rest/r1/departments?orderBy=DepartmentName:asc

URI: http://localhost:7001/departmentApi/rest/r1/departments?orderBy=DepartmentName: desc

Limiting the records in Querying Departments – GET:

URI: http://localhost:7001/departmentApi/rest/r1/departments?limit=2

Fetches only 2 records.

Querying Departments from a particular record– GET:

URI: http://localhost:7001/departmentApi/rest/r1/departments?offset=2

Fetches only 2 records.

URI: http://localhost:7001/departmentApi/rest/r1/departments?offset=2&limit=5

Fetches 5 records starting from 2nd record.

Expanding a Child Resource – GET:

URI: http://localhost:7001/departmentApi/rest/r1/departments?expand=Employee (Child Resource Name)

Querying Child Resource – GET:

URI: http://localhost:7001/departmentApi/rest/r1/departments/{id}/child/Employee

Querying a particular Child Resource – GET:

URI: http://localhost:7001/departmentApi/rest/r1/departments/{id}/child/Employee/{Child Resource Id}

Querying a Child Resource using an attribute – GET:

URI: http://localhost:7001/departmentApi/rest/r1/departments/{id}/child/Employee?q=FirstName=Jennifer


Service Bus 12c- Mixing URI Parameters and Payload in REST Service

Typically, a PUT request URI looks like below accepting the actual payload in HTTP body.


In Service Bus12c, We cannot mix URI parameters with representation of the resource, when we want to define a resource in this way.


If we run Proxy Service with this setup, we will get an error as shown below.




Instead, you can use the expression as shown below.


You can access this using the following expression from your message flow.


If you log $body and above expression, you would see the log messages as shown below.



As explained in this link, you may have to populate these URI parameters in outbound variable.

Sending JSON payload requests from BPEL

In this blog post, I am sharing sample code that demonstrates the usage of JSON in BPEL context. The code is refactored into 2 projects containing the java utility code and  a sample BPEL process. The code can be downloaded from here.


Java Utility Code:

  • Using cookies to pass authentication info (username and password).
  • Sending XML payload as URL parameters using intermediate conversion to JSON for GET request.
  • Sending HTTP request through HTTP proxy.
  • Sending JSON or XML payload in the POST request.

BPEL Process:

  • Using BPEL preferences to store any configurable information.
  • Using java embedding activity to call the external java code. The jar file has to be kept in SCA-INF/lib to refer to java code.
  • Using Replay activity. The fault policy mechanism can also be used for retry functionality, if we throw BPEL related faults from java code.
  • Converting JSON to XML and vice-versa using java utility routines in BPEL.
  • An example on creating XSD similar to JSON data format representing the service response so that XPath expressions can be used in BPEL.

Does not cover:

  • HTTP Basic Authentication
  • Using XML APIs (like JAXP) to convert input XML to URL parameters
  • URL encoding while calling HTTP GET method
  • Using JAX-RS to invoke REST based services


  • in the code zip file is taken from Biemond’s blog.
  • The libraries used for JSON processing can be downloaded from here .
  • JSR – 353 Java API for JSON Processing is closed for public review.

The code is uploaded for reference and  this may not be the only way to achieve this.

Error while using the HTTP Binding in BPEL

HTTP Binding can be used in BPEL to call the RESTful services. We might have come across one common error REPLACE_WITH_ACTUAL_URL while calling. Came across a metalink note that talks about this so thought of sharing the same.

Metalink Note ID: 1328955.1

Following are the few reasons that i found during my testing with the HTTP adapter to invoke REST based urls:

–  If the URL is not accessible from the server because of the firewall or HTTP proxy

– Using the XML complex types in the request structure.

Though, the metalink url says that XML complex types are not supported it’s working in version ( i verified only in this version). The same working sample can be downloaded from here.

The example calls the Echo application which can be downloaded from  here (Antony Reynold’s blog).

Testing OSB based REST Services using SOAP UI

This post assumes the basic working knowledge of SOAP UI testing tool, Oracle Service Bus11g and developing the REST based services.

Primer on REST

REST stands for ‘Representational State Transfer’ and it was first introduced by ‘Roy Fielding’ in his 2000 doctoral dissertation. REST is another architectural style of creating the web services that is different from SOAP based web services. REST based architectures communicate primarily through the transfer of representation of resources (information) and it uses simple XML over HTTP.

RESTful services adhere to certain set of constraints and architectural principles that include the following:

    · REST based architectures are built from resources that are uniquely identified by URIs and the only allowed operations are the HTTP operations: GET, POST, PUT and DELETE.

   · REST components manipulate resources by exchanging the representations of the resources. For example, a trading account can be represented by a XML document. In RESTful architecture a trading account might be updated by posting a XML document containing the modified trading account information to its URI.

Creating New REST Project

Open the SOAP UI and click on File -> New SOAP UI Project. Enter the project name and select the option ‘Add REST Service’ and click on OK.


In the next dialog window, Enter the Service Endpoint as :port">http://<hostname>:port where OSB runs and do not include the proxy service endpoint in this and check the option ‘Create Resource’.


In the next dialog window, Enter any value for the resource name to identify the resource and give the actual Proxy Service endpoint for Resource Path and click OK.


In the next dialog window, Enter any value for method name and select the HTTP method as your Proxy Service supports. Since my OSB proxy service supports only POST I am selecting the method as POST as shown below and click on OK.


Now verify that new REST project has been created and Request1 window is opened. To test your REST based proxy, modify the Media Type to ‘text/xml’, copy the request into request window and run by clicking on green arrow icon on the top.

Adding New Request to Existing Project

Right click and select the New Request as shown below:


Enter the Request Name as you need and click Ok to open the request editor. Once the request editor opens, copy the request into the request window and run as explained earlier.


Adding New Resource to Existing Project

Right click and select New Resource as shown in the below screenshot.


Enter the Resource Name and End point as explained in previous section to add another resource (proxy in our case) and click on OK.


Verify that another resource is added to the project that we have created and enter the Method Name and select POST method as explained earlier and click on OK. And run the request after pasting it in request window.


Enter your email address to subscribe to this blog and receive notifications of new posts by email.

Join 379 other subscribers

Enter your email address to follow this blog and receive notifications of new posts by email.

%d bloggers like this: