If an interface is exposed as a REST service, you can view the corresponding WADL description in a separate window.
Take the same interface example PL/SQL API Invoice Creation (AR_INVOICE_API_PUB) explained earlier for WSDL description. This interface can also be exposed as a REST service. To view the associated WADL information, click View WADL link in the REST Web Service tab of the interface details page. The WADL document appears.
WADL (Web Application Description Language) is designed to provide a machine processable description of HTTP-based Web applications.
The application element forms the root of a WADL description. It may contain the following elements:
Grammars: This element serves as a container for definitions of data exchanged during execution of the protocol described by the WADL document.
Resources: This element serves as a container for all the included child resource elements provided by the application.
<?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> ... </grammars> <resources base="http://<hostname>:<port>/webservices/rest/Invoice/"> ... </resources </application>
This element acts as a container for definitions of data exchanged during execution of the protocol described by the WADL document. Include element is often referenced to allow the definitions of one or more data format descriptions to be included.
<grammars> <include xmlns="http://www.w3.org/2001/XMLSchema" href="https://<hostname>:<port>/webservices/rest/Invoice/?XSD=CREATE_INVOICE_SYNCH_TYPEDEF.xsd" /> <include xmlns="http://www.w3.org/2001/XMLSchema" href="https://<hostname>:<port>/webservices/rest/Invoice/?XSD=CREATE_SINGLE_INVOICE_SYNCH_TYPEDEF.xsd" /> </grammars>
In this example, two service operations with the support for synchronous pattern CREATE_INVOICE_SYNCH and CREATE_SINGLE_INVOICE_SYNCH are referenced in the Include element.
Invoice highlighted here is the service alias name entered earlier prior to the service deployment. Once the service has been successfully deployed, the specified alias name (Invoice) becomes part of the service endpoint in the WADL and namespaces in the XSDs.
The resources element represents the resource information provided by the Web application. It includes a base attribute that provides the base URI for each included child resource identifier.
For example, each child resource element represents a specific service operation (such as create_invoice and create_single_invoice) contained in the selected interface.
<resources base="http://<hostname>:<port>/webservices/rest/Invoice/"> <resource path="/create_invoice/"> ... </resource> <resource path="/create_single_invoice/"> ... </resource> </resources>
A resources element may contain a set of resource elements; each resource element represents a REST service operation. In this example, create_invoice and create_single_invoice are included child resource element.
Each resource element can include the following child elements:
Method: This element describes the input to and output from an HTTP protocol method that can be applied to the resource.
POST is the only supported method for PL/SQL and Concurrent Program REST services; POST and GET are the supported methods for Java Bean Services and Application Module Services.
Request: This element describes the input to be included when applying an HTTP method to a resource.
Element mediaType indicates the supported media type, such as XML and JSON, for the input parameters.
Response: This element describes the output results from performing an HTTP method on a resource.
The supported media types for the output results are XML and JSON.
<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> <resource path="/create_single_invoice/"> <method id="CREATE_SINGLE_INVOICE" name="POST"> <request> <representation mediaType="application/xml" type="tns2:InputParameters" /> <representation mediaType="application/json" type="tns2:InputParameters" /> </request> <response> <representation mediaType="application/xml" type="tns2:OutputParameters" /> <representation mediaType="application/json" type="tns2:OutputParameters" /> </response> </method> </resource> </resources>
In this example, input request and output response messages are all supported with XML and JSON formats when applying the HTTP method POST for each resource element 'create_invoice' and 'create_single_invoice'.
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 in the REST service operation. For example, the following WADL description shows two of many methods contained in the Rest Service Locator interface. The addGrant method is implemented with POST HTTP method, and the getOperations method is assisted with GET HTTP method.
<resources base="http://<hostname>:<port>/webservices/rest/locator/">
<resource path="/addGrant/">
<method id="addGrant" name="POST">
<request>
<representation mediaType="application/xml" type="tns1:addGrant_InputParameters" />
<representation mediaType="application/json" type="tns1:addGrant_InputParameters" />
</request>
<response>
<representation mediaType="application/xml" type="tns1:addGrant_OutputParameters" />
<representation mediaType="application/json" type="tns1:addGrant_OutputParameters" />
</response>
</method>
</resource>
...
<resource path="/getOperations/{irepClassName}/">
<param name="irepClassName" style="template" required="true" type="xsd:string"/>
<method id="getOperations" 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:getOperations_OutputParameters" />
<representation mediaType="application/json" type="tns3:getOperations_OutputParameters" />
</response>
</method>
</resource>
</resources>
The GET method of the above example contains the path variable and application context information if required for the service execution:
Note: Path variables and context parameters are applicable only for the HTTP GET method.
{irepClassName} is a path variable for "getOperations" operation as specified below:
<resource path="/getOperations/{irepClassName}/">
Path variable is defined using the <param> tag after the <resource> tag and before the <method> tag. A service client will replace the path variable with actual value at run time when the HTTP GET method is invoked.
For example, if the value of the irepClassName is ''PLSQL:FND_PROFILE", then "PLSQL:FND_PROFILE" should be passed in HTTP URL for this request. The URL on which the HTTP GET will be performed is: http://<hostname>:<port>/webservices/rest/locator/getOperations/PLSQL:FND_PROFILE
Path variables are identified by inline annotation @rep:key_param in Java API source file. For annotation guidelines on Java Bean Services, see Annotations for Java Bean Services. For more Application Module Services annotation guidelines, see Annotations for Application Module Services.
Context parameters are predefined parameters required for initializing Oracle E-Business Suite application context. These parameters including ctx_responsibility, ctx_respapplication, ctx_securitygroup, ctx_nlslanguage, and ctx_orgid are only applicable for the HTTP GET method. These parameters are passed as query strings along with the request payload query strings in the RESTHeader element.
Control parameters are predefined query parameters that may be used for a resource or collection resource. For example, use offset and limit parameters to limit the number of records returned and for pagination.
offset=<number>&limit=<number>
offset=0&limit5
This returns the first 5 records of response after record 0. That is the 1st, 2nd, 3rd, 4th, and 5th records.
offset=2&limit4
This returns the first 4 records of response after record 2. That is the 3rd, 4th, 5th and 6th records.
http://<hostname>:<port>/webservices/rest/empinfo/getAllReports/?offset=0&limit=5
This returns the first 5 employees reporting to a logged in user in hierarchical order.