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


OAC 12c Articles

OAC 12c–Consuming API Assets in SOA/OSB Projects

In this post, we will see how to lookup Oracle API Catalog (OAC) for API assets using JDeveloper and consume it in SOA/OSB projects. Note that as mentioned in post, we need to install patch 19721053 to get JDeveloper extension for OAC/OER.

Creating OAC Connection

Select File –> New –> General –> Connections.


Enter required information as shown below. Note that any user with Developer role would be able to connect to OAC.


Click OK. Observe that new OER connection is shown in Resources as shown below and able to see all the published API assets.


We must associate a JDeveloper application with a default OAC Connection to consume assets. Without this, we will see the following error when trying to consume assets.


To associate OAC Connection, select Tools –> Oracle Enterprise Repository and select the above OAC connection as shown below.


Now we can consume API asset in SOAP Project as shown below for partner link creation.


Similarly, while creating business service in OSB we can select the OAC asset as shown below.



OAC 12c:Harvesting SOA/OSB Projects

In this post, we will see how to use harvester to populate Oracle API Catalog (OAC) with Oracle SOA Suite projects.

Harvester can be used to collect services from Oracle SOA Suite and Oracle Service Bus and creates OAC API assets. Initially API assets gets created in Draft status. User can modify these assets to add metadata and publish so that users can search and use.

Before getting into nuances of Harvester, let us understand little but about the roles supported by OAC. OAC supports Developer, Curator and Admin roles for the users.

Developer: Users with this role can search for API assets in OAC console or using OER Jdeveloper plugin. And also can submit ratings and reviews for API assets.

Curator: Users with this role can run harvester to create API assets, add metadata and publish along with the capabilities provided by Developer role.

Admin:Users with this role can access the admin page to manage users, departments, settings and security along with  capabilities provided by Curator role.

It’s always recommended to run harvester with admin role. Before running the harvester, make sure that services are deployed to server Weblogic 11g or higher. Harvester can be found in %MW_HOME/oer/tools/harvester and we can run it from command line, Ant or WLST. Here in this blog, we will look at command line usage. Refer to documentation here for more information.

As a prerequisite, set JAVA_HOME variable and harvester requires Java 6 or later. Open configuration file  HarvesterSettings.xml from above location and modify repository section as shown below which points to your OAC server.


Now, we should tell harvester about the location from where it can collect the resources. This can be done either using remoteQuery section in configuration file or can mention as options in command line itself.

To use remoteQuery section, modify  as shown below by giving remote server URL and the required credentials.  Make sure that your SOA server is running.


Harvester needs  passwords to be mentioned in encrypted form always so run encrypt.bat as below to take care of this requirement.

encrypt.bat HarvesterSettings.xml  HarvesterSettings.xml

Now just run  harvest.bat and see that new API assets have been created as shown below with initial status as Draft.


We can achieve the same results from command line by running the following command;

.\harvest.bat -remote_url http://localhost:7004 -remote_username weblogic -remote_server_type SOASuite  -soa_partition default

However, harvester always picks up passwords from configuration file, so we should have remoteQuery section as below for this command to work.

http://localhost:7004/</uri> –>

To harvest a specific project, you can include project name in remoteQuery section as shown below. We can mention revision along with project name or can just mention project name if we have single version of the project.


The command would look like below, if we want to harvest single project:

.\harvest.bat -remote_url http://localhost:7004 -remote_username weblogic -remote_server_type SOASuite  -soa_partition default –remote_project AsyncBPEL

We can always find usage information by using –help option as shown below.


We should use –remote_server_type SOASuite11g to harvest SOA Suite 11g projects.

Adding Metadata for API Assets

Search in OAC using Draft status and click individual asset to edit.



In this details page, we will observe following icons used to get link to view API details, to toggle the view, to add to list of My APIs, to edit and to delete the assets respectively.


Clicking Toggle view brings up following to show API asset information.


Clicking Add to My APIs will add this asset to list of My APIs.


Click Edit and add/modify required metadata for an asset and Save.


Publishing API Asset

To Publish API, go to Edit page and modify the status to Published as shown below.


And the OAC Home page will show the published APIs.



Harvesting OSB Projects

The harvesting process, adding and publishing API assets will remain same for OSB Projects but we should use harvester from location %MW_HOME$/oer/ tools/osbharvester. Please Make sure that harvester and OSB are installed in the same middleware home.

Modify the repository and remoteQuery sections in HarvesterSettings.xml as shown below. As above, use encrypt.bat to encrypt passwords. Note that we have given the Admin server port in remoteQuery section.



Run osb-harvest.bat to do harvest of OSB Projects and you can see the new API assets got created in OAC as shown below with initial status as Draft.


To harvest single OSB project, add projectName to remoteQuery section as shown below.



Note that I had to change following highlighted line in setenv.bat file to include tools in OER path before running harvester otherwise encrypt and harvester commands were throwing the errors.

@rem    OSB / ConfigJar Tool Home directories

set OSB_HOME=%MW_HOME%\osb
set OER_HOME=%MW_HOME%\oer\tools
set HARVESTER_HOME=%OER_HOME%\osbharvester

Similarly, API assets can be created for REST services as shown below.



Installation of Oracle API Catalog (OAC) 12c

Oracle API Catalog (OAC) acts as a catalog for the APIs and provides search capability for users/developers so that they can understand APIs and use APIs in application development as per the requirement. And also provides a way to populate OAC.

We can download  Oracle API Catalog installer from here. Also download and install the other required patches as given in download page.


Unzip installer. Do java -jar oer_generic.jar and use following screenshots to finish installation.


We can enter new Oracle Home or choose the existing home as shown below.






Once the installation is done, you can find the oer directory in selected Oracle Home showing following directories.


Now proceed with the installation of other required patches 18718889 (WLS update for harvester), 18791727 (RCU) and 19721053 (JDev extension for OAC/OER). Unzip the patches and install using opatch utility as shown below.




After the installation of these patches:

  • We should be able to see OER connection in File –> New –> General –> Connections.


  • We should be able to see OAC related schemas in RCU installer as shown below. We can invoke  RCU installer from %MW_HOME%/ oracle_common /bin. Make sure that you install certified database before installing these schemas also choose the corresponding schemas depending on OER or OAC installation that you opted for.


Finish OAC schema installation with help of following screenshots.





Note: Here I have used the existing middleware home for installation and used XE database for RCU installation.

For more information, you can refer to installation guide here.

OAC Domain Creation:

Invoke the configuration wizard from %MW_HOME%/wlserver/common/bin and create new OAC domain using the following screenshots.









Once OAC domain creation is successful, start both Admin and OAC managed servers to access Oracle API Catalog.

We can access OAC using url http://localhost:8111/oac and default credentials for admin are admin/weblogic1. You will be asked to modify admin password after the first login and will bring up the following screen.




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

Join 353 other followers

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