Exposing a Report Region as a RESTful Web Service

RESTful Web services, that are callable with a URL and return either JSON or XML, can be exposed in report regions. To expose a report region as a RESTful Web service, the following steps must be performed:

1. The instance administrator must enable the REST provider feature in instance settings.
2. A developer must enable RESTful access to a report region.
3. The page that contains the report must not require authentication.
   
   

   Enabling RESTful Access to a Report Region

   To enable RESTful access to a report regions, you must make the page public so no authentication is required and enable the report for RESTful access.
   To make a page public:
   

   1. On the Workspace home page, click the Application Express.
   2. Select an application.
   3. Select the page that contains the report you want to enable.
      The Page Definition appears.
   4. Under Page, click the edit icon.
   5. Under Security, select Page is Public from the Authentication list.
   6. Click Apply Changes.

   To enable a report region for RESTful access:
   

   1. On the Workspace home page, click Application Builder.
   2. Select an application.
      Application Builder appears.
   3. Select the page that contains the report you want to enable.
      The Page Definition appears.
   4. Under Regions, click the name of the region that contains the report you want to enable.
   5. Under Attributes, enter a value for Static ID field. This value is used to access the report RESTfully.
   6. From the Enable RESTful Access List, select Yes.
   7. Click Apply Changes.

   Accessing a RESTful Enabled Report Region from a Web Service Client

   Once you enabled a report for RESTful access, you need to know the endpoint URL and parameters to pass to the RESTful Web service. The endpoint URL is similar to the URL used to access this instance of Oracle Application Express followed by the resource apex_rest.getReport. For example:
   http://apex.oracle.com/apex/apex_rest.getReport
   

   Tip:

   If your client uses the POST method, you must also set the HTTP Header, Content-Type, to the value application/x-www-form-urlencoded.

   Name	Default	Required	Description
   app	N/A	Yes	The numeric ID or alias of the application that contains the RESTful enabled report.
   page	N/A	Yes	The numeric ID or alias of the page that contains the RESTful enabled report.
   reportid	N/A	Yes	The Static ID attribute of the RESTful enabled report.
   parmvalues	null	No	Values for the report parameters can be sent in a comma separated list. For example: CLERK,10
   lang	en	No	Sets the NLS environment variables prior to running the report based on the language passed in. For example: de
   output	xml	Yes	This determines whether XML or JSON will be returned to the client. Domain of possible values are: xml, json

   The apex_rest service also has an operation to allow discoverability of RESTful enabled reports, given an application ID or alias. The response is an XML document with a description of all reports that can be accessed by RESTful Web services. This service is invoked with a URL similar to the following:
   http://apex.oracle.com/apex/apex_rest.getServiceDescription?app=691
   In the URL above, 691 is the numeric ID of an application. The document returned is similar to the following:
   

   <?xml version="1.0"?>
   <urn:getServiceDescriptionResponse xmlns:urn="urn:oasis:names:tc:wsrp:v1:types">
           <urn:requiresRegistration>false</urn:requiresRegistration>
           <urn:offeredPortlets>
                       <urn:PortletDescription>
                                 <urn:portletHandle>employees</urn:portletHandle>
                                 <urn:markupTypes>
                                           <urn:mimeType>application/xml</urn:mimeType>
                                           <urn:mimeType>application/json</urn:mimeType>
                                 </urn:markupTypes>
                                 <urn:groupID>1</urn:groupID>
                                 <urn:description/>
                                 <urn:title>EMP</urn:title>
                                 <urn:keywords>
                                   <urn:value>P1_JOB</urn:value>
                                         <urn:value>P1_DEPTNO</urn:value>
                                 </urn:keywords>
                       </urn:PortletDescription>
           </urn:offeredPortlets>
   </urn:getServiceDescriptionResponse
   

   The portletHandle maps to the Static ID of the report region or the reportid parameter in the REST request. The groupID maps to the page id or the page parameter in the REST request. Finally, any parameters used by the SQL report are listed as children of the keywords node.

Viewing a Web Service Reference History

The Web Services History displays changes to Web service references for the current application by application ID, Web service references name, developer, and date.

To view a history of Web service reference changes:

1. On the Workspace home page, click the Application Builder icon.
2. Select an application.
3. Click Shared Components.
   The Shared Components page appears.
4. Under Logic, click Web Service References.
5. Click History.

Note:

The History button only appears on the Web Service Reference page after you have created a Web service reference.

Creating a Form on a Web Service

The Create Form on Web Service Wizard creates a form and a submit button. You can execute this wizard after creating the Web service reference from a WSDL or on a RESTful style Web service, or from the Page Definition.

Use this wizard when you expect a scalar result from the Web service. A Web service that looks up a stock price is a good example because the input is a stock symbol and the output is the scalar value price.

Creating a Form After Creating a Reference

To create a form after creating a Web Service Reference:

1. Create the Web service reference. See "Creating a Web Service Reference Based on a WSDL", Creating a RESTful Web Service Reference , and Creating a Web Service Reference Manually.
2. After the Web service references has been added, select Create Form on Web Service.
3. For Choose Service and Operation:
   
   1. Web Service Reference - Select the Web service reference.
   2. Operation - Select the method to be executed. For RESTful style Web references, doREST will be selected automatically. The Operation option will not appear for Manual style Web references.
4. For Identify Page and Region Attributes, review the page and region attributes. If the page you specify does not exist, the wizard creates the page for you.
5. For Items for Input Parameters:
   
   1. Identify which items to add. To include an item, select Yes in the Create column. Otherwise, select No.
   2. If necessary, edit the item label.
6. For Items for Output Parameters (this step is bypassed for Manual style Web references):
   
   1. Identify which items need to be added. To include an item, select Yes in the Create column. Otherwise, select No.
   2. If necessary, edit the item label.
7. If applicable, specify the Item Names and Item Labels for basic authentication.
   Note that this step only appears if basic authentication was specified for this Web service reference when it was created.
8. Click Finish.

Creating a Form by Adding a New Page

If you have an existing Web service reference, you can create form by adding a new page.
To create a form by adding a new page:

1. Create the Web service reference. See "Creating a Web Service Reference Based on a WSDL", Creating a RESTful Web Service Reference , and Creating a Web Service Reference Manually.
2. Create a new page.
   In the Create Page Wizard:
   
   1. Select Form.
   2. Select Form on Web Service.
3. For Web Service Reference and Operation, select the Web service reference and operation (that is, the method to be executed). For RESTful style Web references, doREST will be selected automatically. The Operation option does not appear for Manual style Web references.
4. For Identify Page and Region Attributes, review the page and region attributes. If the page you specify does not exist, the wizard creates the page for you.
5. For Items for Input Parameters:
   
   1. Identify which items need to be added. To include an item, select Yes in the Create column. Otherwise, select No.
   2. If applicable, specify the Item Names and Item Labels for basic authentication.
      Note that this step only appears if basic authentication was specified for this Web service reference when it was created.
6. For Items for Output Parameters (this step is bypassed for Manual style Web references):
   
   1. Identify which items need to be added. To include an item, select Yes in the Create column. Otherwise, select No.
   2. If necessary, edit the item label.
7. Click Finish.

Creating an Input Form and Report on a Web Service

The Create Form and Report on Web Service Wizard creates an input form, a submit button, and a report for displaying results. You can execute this wizard directly after creating the Web service reference from a WSDL or a RESTful style Web service, or by adding a page.

Use this wizard when you expect a nonscalar result from the Web service. The Amazon Product API Web service is a good example. This Web service returns many results based on the search criteria entered in an input form.

Creating a Form and Report After Creating a Reference

To create a form and report after creating a Web Service Reference:

1. Create the Web service reference. See "Creating a Web Service Reference Based on a WSDL" and Creating a RESTful Web Service Reference.
2. After the Web service reference has been added, select Create Form and Report on Web Service.
3. For Choose Service and Operation:
   
   1. Web Service Reference - Select the Web service reference.
   2. Operation - Select the method to be executed. For REST style Web references, select doREST.
4. For Page and Region Attributes, review the displayed attributes. If the page you specify does not exist, the wizard creates the page for you.
5. For Input Items:
   
   1. Identify which items to add to the form. To include an item, select Yes in the Create column. Otherwise, select No.
   2. If necessary, edit the item label.
6. If applicable, specify the Item Names and Item Labels for basic authentication. Note that this step only appears if basic authentication was specified for this Web service reference when it was created.
7. For Window Service Results:
   
   1. Temporary Result Set Name - Enter a name for the collection that stores the Web service result.
   2. Result Tree to Report On (Not displayed for REST style Web service references) - Select the portion of the resulting XML document that contains the information you want to include in the report.
8. For Result Parameters to Display, select the parameters to be included in the report.
9. Click Finish.

Creating a Form and Report by Adding a New Page

If you have an existing Web service reference, you can create an input form and report by adding a new page.
To create a form and report by adding a new page:

1. Create the Web service reference. See "Creating a Web Service Reference Based on a WSDL", "Creating a Web Service Reference Manually", and"Creating a RESTful Web Service Reference".
2. Create a new page.
   In the Create Page Wizard:
   
   1. Select Form.
   2. Select Form and Report on Web Service.
3. For Choose Service and Operation:
   
   1. Web Service Reference - Select the Web service reference.
   2. Operation - Select the method to be executed. For RESTful style Web references, doREST will be selected automatically. The Operation option will not appear for Manual style Web references.
4. For Page and Region Attributes, review the page and region attributes. If the page you specify does not exist, the wizard creates the page for you.
5. For Input Items:
   
   1. Identify which items to add to the form. To include an item, select Yes in the Create column. Otherwise, select No.
   2. If necessary, edit the item label.
6. If applicable, specify the Item Names and Item Labels for basic authentication. Note that this step only appears if basic authentication was specified for this Web service reference when it was created.
7. Follow the on-screen instructions.
8. Click Finish.

Testing a REST Web Service Reference

After you have created a Web service reference, you can test it on the Test Web Service Reference page.

To test a Web service reference:

1. Navigate to the Web Service References page. See "Accessing the Web Service References Page".
2. From View, select Report.
3. Click the Run icon adjacent to the Web Service reference name.
   The Test Web Service Reference page appears. The Web service name and URL endpoint display at the top of the page.
4. In the URL and Proxy Override fields, optionally edit the values for the test.
5. If required, enter the username and password under Basic Authentication.
6. Under HTTP Headers, enter appropriate values.
7. Under Input Parameters, enter appropriate values.
8. Click Test.
   The message response appears at the bottom of the page.