Note: This post is based on SOA 12.1.3 release.
In this post, you will learn to expose Proxy Services as REST services. We will use Employees table and come up with REST API that can be used to perform CRUD operations.
This post assumes knowledge of DB connection pool setup and Pipelines.
Creating Business Service
Create the business service using DB Adapter with the help of following steps.
Click Finish and verify that business service has been created as shown below.
Refactor all the artifacts to BusinessService directory.
Now you can test business service alone to make sure that all operations are working fine as expected. You can refer to this post for detailed steps.
Creating REST Binding
We want our REST resource to support the following operations:
Resource |
HTTP Verb |
Resource URIs |
Desription |
Employees | GET | /Employees | Get all employees |
GET | /Employees/{employeeId} | Get an employee represented by Employee ID. | |
POST | /Employees | Create new employee | |
PUT | /Employees | Update new employee | |
DELETE | /Employees/{employeeId} | Delete an employee represented by Employee ID. |
In Service Bus 12c, REST proxy services convert REST native payload to SOAP before invoking a pipeline or split-join, while REST business services convert payload from SOAP to REST. That means, the internal interface is still based on WSDL, while the external business and proxy services expose REST endpoints. This will be evident in later steps as service bus creates both WADL and WSDL files and each resource is mapped to different operations defined in WSDL.
Drag REST binding into Proxy Services swim lane in Service Bus overview editor as shown below.
This brings up Create REST binding window. Give the name as shown below.
Click + icon for Resources to add new resource and click OK.
Similarly add another resource /Employees/{employeeId}. Now your resources should look like below.
Now you have to create the corresponding Operation Bindings which in turn creates WSDL with these operations.
Operation Bindings for resource /Employees:
Use the following steps to create GET mapping.
Here we are selecting both XML and JSON as we want our API to support both content types. Click on highlighted icon to define schema on fly representing the output payload. Enter file name and give directory name as ProxyService as shown below.
Click Next and choose file type as JSON.
Click Next and give Target namespace and Root element as shown below and you can use the following JSON payload sample.
{
“Employee” : [{
“employeeId”: “100”,
“firstName”: “fname”,
“lastName”: “lname”,
“email”: “fn@gmail.com”,
“phoneNumber”: “9848012345”,
“jobId”: “100”,
“salary”: “100”,
“commissionPct”: “100”,
“managerId”: “100”,
“departmentId”: “100”
},
{
“employeeId”: “101”,
“firstName”: “fname1”,
“lastName”: “lname1”,
“email”: “fn1@gmail.com”,
“phoneNumber”: “9848012345”,
“jobId”: “100”,
“salary”: “100”,
“commissionPct”: “100”,
“managerId”: “101”,
“departmentId”: “101”
}]
}
Click Next and verify the schema that gets generated.
Click Next and Finish and verify that schema URL is populated in Response tab.
Click OK and verify Operation Bindings are populated as shown below.
Use the following steps to create POST mapping by reusing existing schema.
Similarly, finish mapping for PUT and use operation name as updateEmployee. Now your Create REST binding window should look like below.
Click OK. You will observe that Proxy Service, WADL and WSDL have been created as expected.
You will also observe errors, as XSD file is created in ProxyService folder whereas WADL and WSDL got created in Resources folder. So open WADL and WSDL files and modify the XSD reference as shown below to resolve errors.
Operation Bindings for resource /Employees/{employeeId}:
You should reuse the schema created in above steps for this resource as well.
Now in Service Bus overview editor, right click EmployeeService and select Edit REST as shown below.
Use the following steps to create GET mapping.
You can leave schema for request as it is so that it will be defaulted by the wizard.
Click OK and your Update Service window should look like below.
Similarly finish DELETE method by using operation name as deleteEmployee and now your Update Service window should look like below.
Click OK and observe the WADL and WSDL files that got updated with your new operation bindings. If you observe that WADL is not updated just do refresh as shown below.
WADL:
WSDL:
With this, you have finished the REST interface that is exposed to consumers.
Creating Pipeline:
Create new pipeline EmployeePipeline using EmployeeService.wsdl as shown below.
Connect EmployeeServcie proxy service with EmployeePipeline in Service Bus overview editor as shown below.
We will not discuss much about finishing the message flow in pipeline as it’s nothing different from regular scenario. You can find the Service Bus project here i.e. used for demonstration purpose in this post.
Testing:
In test console, you can observe that Accept http header shows both application/xml and application/json i.e. now your REST service supports both xml and json data formats.
GET With application/xml:
GET With application/json:
POST With application/xml:
POST With application/json:
You can observe that both records have been inserted as expected.
PUT With application/xml:
PUT With application/json:
You can observe that both records have been updated as expected.
Resource /Employees/{employeeId}:
GET With application/xml:
GET With application/json:
DELETE With application/xml:
DELETE With application/json:
You can observe that both records have been deleted as expected.
If you want to expose SOAP interface as well, then you just need to create another Proxy Service and join EmployeePipeline as shown below.
Notes:
- We did not talk about fault handling specific details here.
- It’s always recommended not to do blind GET as we may see performance issues when large number of records are there.
- As an exercise, you can come up with resource emulating QBE on db.
References:
Hi Siva,
I am following ur blog from long. Very nice work !!!
I have a question regarding rest services in OSB 12c. I am exposing a soap pipeline as a rest service proxy. The service takes json as input and sends back json response. But I am getting ‘no response’ in return. Can you please help? I have posted the query on a forum, please can you have a look for detailed expaination?
https://stackoverflow.com/questions/56210867/osb-getting-no-response-when-exposing-a-soap-based-pipeline-as-a-rest-service
Thanks
Pargat
is it message based proxy service and did you make sure that both input and output are selected as json?
It is rest proxy based on WADL with transport type as ‘http’ and service type as ‘rest service’.
Both request and response payload type is set to ‘json’
Hi Siva, I am using Jdeveloper 12.2.1 and when I try to add REST adapter in the Proxy Services column, I am not seeing Operation bindings. I see Method bindings. I am looking for Operation bindings. How to get it ?. I have a stop shower because of this and unable to proceed.
If I follow the approach mentioned in http://www.oracle.com/webfolder/technetwork/tutorials/obe/cloud/sscs/CreatingOSBApp/creating-a-service-bus-app.html#section3s1 , I am able to reach operation bindings.
thank you Siva
When you have WADL for your REST proxy service, you will see operation bindings. This is how we create OSB REST in 12.1.3 release. But release 12.2.1 introduces native REST service where you will not have this WADL and also in message flow you have to use REST branch rather than operational branch. You may want to refer to https://wp.me/pEWnt-Sg and https://wp.me/pEWnt-QN
Hi i need an help. when am trying for delete operation am getting this error
The invocation resulted in an error: .
General runtime error: Invoking invalid outbound operation: delete.
OSB-380000
Hello, Siva,
Nice article. I have a unique requirement that I wonder if you could tell me if it is possible.
I need to use a URI parameter to do a PUT to update a resource on a REST service. However, I do NOT want to submit that parameter as part of my request. Can you tell me if that is possible?
So, in short, I’m needing to specify an ID parameter on my URI…but do NOT want to use it in the JSON input.
Thank you for any light you could shed on this issue.
Refer this http://blogs.perficient.com/oracle/2015/07/07/osb-12c-rest-adapter-implementation/
Very nice article indeed. It would be good if you can throw light on how can I expose this REST URI to external clients so that it can be consumes by a mobile application or tested in a client like SOAPUI?
typically in your local dev, you don’t require any setup. Directly the OSB rest service urls can be used and tested using SOAP UI. But in the actual environments (Dev, Test or Prod), one would always have OHS or some load balancer before OSB server and this load balancer will have the url mappings so the exact host and port details will not be revealed to customers. External clients will always be hitting this load balancer.
Same is the case when you want to access it from mobile. But local dev access is not straight forward and may need to create some LAN and all so that you can access it from mobile
Hi Siva,
You have a very informative blog! It really help folks like us.
I am using REST binding (12.2.1), and have 2 flavors of GET operation as below
resource path
/employee
/employee/{id}
When we actually define the logic for the GET URI parameter operations how do I access {id} within a pipeline ? Is there any variable or property I can refer to ?
I used inbound/ctx:transport/ctx:request/http:relative-URI , but it gives the complete URI – /employee/{id} , I can remove the ID value but was wondering if there was any inbuilt parameter
Thanks,
Anju
Could not execute exact steps from Creating REST Binding section in 12.2.1
from below step cannot continue
Here we are selecting both XML and JSON as we want our API to support both content types. Click on highlighted icon to define schema on fly representing the output payload. Enter file name and give directory name as ProxyService as shown below.
in 12.2.1, OSB got native REST support which differs from 12.1.3 but still it supports creating REST services this way. Refer to this link http://wp.me/pEWnt-QN for the differences
Hi Shiva ,
can we validate JSON payload using XSD like we do for XML payload, using Validate Action ?
Regards
Adarsh
Assuming you are using 12.1.3, its all xml inside pipeline that’s available..so where so u have this req..
Hi Siva,
Thanks for the quick reply, but I’m using version 12.2.1. It have native support for REST right ?
Hi Siva,
Thanks for the good article.
I have a requirement currently i am working on, I need to pass the JSON input payload for GET request instead of query parameter.
Is there any way to achiev this in OSB 12c REST adapter?
Please help
-Venkat
9490351358
GET request payload is always as query params and is REST philosophy.. how do you want to send ur payload..as http body?? Then u shud choose other http methods only
Hi Siva,
Thanks for the response. Sure I will try this.
Suresh
Hi Siva,
Can you help me how to read XML file and write file with JSON output ? is it possible in 12c??
thanks
Suresh
It should be possible though i don’t have working example. You can achieve this using nxsd schema using steps similar to below.
– Created nxsd schema from File -> New.
– There you will see JSON format as the option and proceed to next page.
– give the options and come up with sample JSON payload matching your xml structure and give it there in source.
After nxsd gets created, it should be just using translate activity to transform XML payload (source schema) to JSON payload (target schema).
It should be possible though i don’t have working example. You can achieve this using nxsd schema using steps similar to below.
– Created nxsd schema from File -> New.
– There you will see JSON format as the option and proceed to next page.
– give the options and come up with sample JSON payload matching your xml structure and give it there in source.
After nxsd gets created, it should be just using XSLT to transform XML payload (source schema) to JSON payload (target schema).