Deploying REST Web Services (Oracle E-Business Suite Help)

Deploying REST Web Services

Oracle E-Business Suite Integrated SOA Gateway allows the administrator to deploy interface definitions as REST services. These interfaces are PL/SQL APIs, Concurrent Programs, Java Bean Services, and Application Module Services. Among these interfaces, only PL/SQL APIs and Concurrent Programs can be exposed as both SOAP and REST services.

Deploying REST Services in the REST Web Service Tab

Before deploying a REST service, the administrator must perform the following tasks:

Specify Service Alias

Each REST service should be associated with a unique alias name. Alias is a set of characters and is used in the service endpoint which shortens the URL for the service.

For example, 'Invoice' is entered as the service alias for an interface Create Invoice (AR_INVOICE_API_PUB) before being deployed. The alias will be displayed as the service endpoint in the WADL and schema for a selected service operation CREATE_INVOICE as follows:

href="https://<hostname>:<port>/webservices/rest/Invoice/?XSD=CREATE_INVOICE_SYNCH_TYPEDEF.xsd" />

Guidelines for Entering Service Alias
- Use simple and meaningful name to represent the service, such as "person", "employee", and so on.
- Do not use "rest", "soap", and "webservices" as the alias.
- Do not start with number and special character, such as #, $, %, _, - and more.
- Do not end with special character.
- Characters such as ., _, and - are allowed in service alias.
Select Desired Methods or Service Operations

In the Service Operations table, select one or more methods to be exposed as REST service operations.

For example, select the CREATE_INVOICE method for the PL/SQL API Create Invoice (AR_INVOICE_API_PUB). After service deployment, only the selected method CREATE_INVOICE will be exposed as a REST service operation.

Select Desired HTTP Verbs for Java Bean Services, and Application Module Services

For Java Bean Services and Application Module Services, the administrator needs to select HTTP method check boxes for the desired methods to be exposed as REST service operations.

Note: PL/SQL APIs and Concurrent Programs can be exposed as REST services with POST HTTP method only.

If the Java or Application Module method is annotated (rep:httpverb) with a specific HTTP method, then the corresponding HTTP method check box is preselected for that method in the table.
- If the GET HTTP method is not annotated, then the GET check box becomes inactive or disabled for further selection. This means that the Java or Application Module method will never be deployed as a REST service operation with the GET method.
- If the POST HTTP method is not annotated, unlike the GET method, the POST check box is still active or enabled by default. This allows the administrator to select the POST check box if needed for the Java or Application Module method as a REST service operation before deploying the service.
For example, if "Add Grant" method within the "REST Service Locator" is annotated only with POST HTTP method, then the POST method check box is preselected for the method. The GET method check box that is not annotated for the "Add Grant" method is shown as inactive or disabled which cannot be chosen for that method before deploying the service.

The administrator can modify the desired HTTP methods before deploying the REST service. For example, uncheck the preselected POST check box if the "Add Grant" method will not be exposed as a REST service operation with POST method.

For information about the rep:httpverb annotation, see rep:httpverb. For more Java Bean Services annotation guidelines, see Annotations for Java Bean Services.

For more Application Module Services annotation guidelines, see Annotations for Application Module Services.

REST Service Security

All REST services are secured by HTTP Basic Authentication or Token Based Authentication at HTTP or HTTPS transport level. Either one of the authentication methods will be used in authenticating users who invoke the REST services.

HTTP Basic Authentication: This authentication is for an HTTP client application to provide username and password when making a REST request that is typically over HTTPS.
Token Based Authentication: This security method authenticates a user using a security token provided by the server. When a user tries to log on to a server, a token (such as Oracle E-Business Suite session ID) may be sent as Cookie in HTTP header. This authentication method can be used in multiple consecutive REST invocations.

For example, an Oracle E-Business Suite user has been initially authenticated on a given username and password. After successful login, the security Login service creates an Oracle E-Business Suite user session and returns the session ID. The session ID that points to the user session will be passed to HTTP headers of all subsequent Web service calls for user authentication.

Note: Login service validates the user credentials and returns an access token. It is a predeployed Java security service, and is part of the Authentication services that help validate and invalidate users, as well as initialize applications context required by the service before being invoked.

For more information on applications context in REST service, see REST Header for Applications Context.

For more information on supported authentication types, see Managing Web Service Security.

Click Deploy to deploy the selected service operations to an Oracle E-Business Suite managed server for consumption.

After Service Deployment

Once the REST service has been successfully deployed, the REST Web Service tab has the following changes:

Service Alias: The REST alias should be displayed as a read-only text field.
REST Service Status: This field is changed from its initial state 'Not Deployed' to 'Deployed' indicating that the deployed service is ready to be invoked and to accept new requests.
View WADL: The View WADL link is displayed. Click the link to display the deployed WADL information.

It shows the physical location of the service endpoint where the service is hosted.
Verb (PL/SQL APIs and Concurrent Programs only): This field displays the HTTP method indicating how the REST service is implemented.

POST is displayed by default because it is the only supported HTTP method for PL/SQL APIs and Concurrent Programs.
Service Operations: This table displays the list of methods (or procedures and functions) contained in the selected interface.
- If the selected interface is a PL/SQL API or concurrent program, then the Included Operations column will be checked for the methods that have been exposed as REST service operations.
  
  By default, all methods in a PL/SQL API are deployed with POST HTTP method. A concurrent program contains only one method which is also deployed with POST HTTP method.
- If the selected interface is an interface type of Java Bean Services or Application Module Services, then the GET and POST columns will be displayed with the included operation marks indicating which HTTP methods have been used to assist the REST service operations.
- Click the Grant icon to view the read-only grant details for a selected method.

Reviewing Deployed WADL

To view the deployed REST service WADL, click the View WADL link.

The following example shows the deployed WADL for the selected CREATE_INVOICE service operation contained in the PL/SQL API Invoice Creation (AR_INVOICE_API_PUB):

Note: Please note that 'Invoice' highlighted here is the service alias entered earlier prior to the service deployment. After the service is deployed, the specified alias name (Invoice) becomes part of the service endpoint in the .xsd schema file.

<?xml version="1.0" encoding="UTF-8" standalone="no" ?> 
<application xmlns:tns="http://xmlns.oracle.com/apps/ar/soaprovider/plsql/rest/ar_invoice_api_pub/" xmlns="http://wadl.dev.java.net/2009/02"
xmlns:tns1="http://xmlns.oracle.com/apps/ar/rest/ar/create_invoice/" name="AR_INVOICE_API_PUB" 
targetNamespace="http://xmlns.oracle.com/apps/ar/soaprovider/plsql/rest/ar_invoice_api_pub/">
  	<grammars>
  		<include xmlns="http://www.w3.org/2001/XMLSchema" href="https://<hostname>:<port>/webservices/rest/Invoice/?XSD=CREATE_INVOICE_SYNCH_TYPEDEF.xsd" /> 
  	</grammars>
	<resources base="http://<hostname>:<port>/webservices/rest/Invoice/">
		<resource path="/create_invoice/">
			<method id="CREATE_INVOICE" name="POST">
				<request>
					<representation mediaType="application/xml" type="tns1:InputParameters" /> 
					<representation mediaType="application/json" type="tns1:InputParameters" /> 
				</request>
				<response>
					<representation mediaType="application/xml" type="tns1:OutputParameters" /> 
					<representation mediaType="application/json" type="tns1:OutputParameters" /> 
				</response>
			</method>
		</resource>
	</resources>
</application>

If the deployed REST service is an interface type of Java Bean Services or Application Module Services, then both GET and POST can be shown as the supported methods. For example, the following WADL description shows two Java methods contained in the Employee Information service. The getAllReports operation is implemented with GET method, and the getPersonInfo operation is implemented with both POST and GET HTTP methods.

<xml version="1.0" encoding="UTF-8"> 
<application name="EmployeeInfo" targetNamespace="http://xmlns.oracle.com/apps/per/soaprovider/pojo/employeeinfo/"
 xmlns:tns="http://xmlns.oracle.com/apps/per/soaprovider/pojo/employeeinfo/" 
 xmlns="http://wadl.dev.java.net/2009/02" xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
 xmlns:tns1="http://xmlns.oracle.com/apps/fnd/rest/empinfo/getallreports/" 
 xmlns:tns2="http://xmlns.oracle.com/apps/fnd/rest/empinfo/getdirectreports/" 
 xmlns:tns3="http://xmlns.oracle.com/apps/fnd/rest/empinfo/getpersoninfo/">

<grammars>
  	...
</grammars>
<resources base="http://<hostname>:<port>/webservices/rest/empinfo/">
  <resource path="/getAllReports/">
	<method id="getAllReports" name="GET">
	   	<request>
			  <param name="ctx_responsibility" type="xsd:string" style="query" required="false" />
           <param name="ctx_respapplication" type="xsd:string" style="query" required="false" />
				<param name="ctx_securitygroup" type="xsd:string" style="query" required="false" />
				<param name="ctx_nlslanguage" type="xsd:string" style="query" required="false" />
				<param name="ctx_orgid" type="xsd:int" style="query" required="false" />
			</request>
			<response>
					<representation mediaType="application/xml" type="tns1:getAllReports_Output" /> 
					<representation mediaType="application/json" type="tns1:getAllReports_Output" /> 
				</response>
			</method>
	</resource> 
 ...
 <resource path="="/getPersonInfo/ {personId}/">
  <param name="personId" style="template" required="true" type="xsd:int" /> 
	<method id="getPersonInfo" name="GET">
	   	<request>
			  <param name="ctx_responsibility" type="xsd:string" style="query" required="false" />
           <param name="ctx_respapplication" type="xsd:string" style="query" required="false" />
				<param name="ctx_securitygroup" type="xsd:string" style="query" required="false" />
				<param name="ctx_nlslanguage" type="xsd:string" style="query" required="false" />
				<param name="ctx_orgid" type="xsd:int" style="query" required="false" />
			</request>
			<response>
					<representation mediaType="application/xml" type="tns3:getPersonInfo_Output" /> 
					<representation mediaType="application/json" type="tns3:getPersonInfo_Output" /> 
				</response>
			</method>
		</resource> 
 <resource path="/getPersonInfo/">
		<method id="getPersonInfo" name="POST">
				<request>
				   <representation mediaType="application/xml" type="tns3:getPersonInfo_Input" /> 
					<representation mediaType="application/xml" type="tns3:getPersonInfo_Output" /> 	
				</request>
		   	<response>
				   <representation mediaType="application/xml" type="tns3:getPersonInfo_Input" /> 
					<representation mediaType="application/xml" type="tns3:getPersonInfo_Output" />
           </response>
			</method>
		</resource>
  </resource path>
</application>

For more information about WADL description, see Reviewing WADL Element Details.

To deploy a REST Web service:

Log in to Oracle E-Business Suite as a user who has the Integration Administrator role. Select the Integrated SOA Gateway responsibility and the Integration Repository link.
In the Integration Repository tab, select 'Interface Type' from the View By drop-down list.
Expand an interface type node to locate your desired interface definition.
Click the interface definition name link to open the interface details page.
In the REST Web Service tab, enter the following information:
- Service Alias: Specify service alias information.
- In the Service Operations table, select one or more methods to be exposed as REST service operations.
  
  If the selected interface is an interface type of Java Bean Services or Application Module Services, select the desired HTTP method check boxes for the methods to be exposed as REST service operations.
Click Deploy to deploy the service to an Oracle E-Business Suite environment.
Click the deployed View WADL link to view the deployed WADL description.