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.

Understanding Web Service References

To utilize Web services in Oracle Application Express, you create a Web service reference using a wizard. Web service references can be based on a Web Services Description Language (WSDL) document, RESTful style, or created manually by supplying information about the service.

When you create a Web service reference based on a WSDL, the wizard analyzes the WSDL and collects all the necessary information to create a valid SOAP message, including:

• The URL used to post the SOAP request over HTTP(S)
• A Universal Resource Identifier (URI) identifying the SOAP HTTP request
• Operations of the Web Service
• Input parameters for each operation
• Output parameters for each operation

When you create a Web service reference manually, you supply the necessary information to create a valid SOAP request, including:

• The URL used to post the SOAP request over HTTP(S)
• A Universal Resource Identifier (URI) identifying the SOAP HTTP request
• The SOAP envelope for the request, including any item substitutions
• Optionally the name of a collection to store the response from the Web service

When you create a RESTful Web service reference, you supply the necessary information about the structure of the request and response including:

• A Universal Resource Identifier (URI) identifying the RESTful request
• The HTTP method identifying the method of the Web service
• HTTP Headers, if required, that are part of the request
• The type of input expected by the Web service
• The format of the response and how to identify the response parameters
  

  Accessing the Web Service References Page

  You manage Web service references on the Web Service References page.
  To access the Web Service References page:
  

  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.
     The Web Service References page appears.

  Specifying an Application Proxy Server Address

  If your environment requires a proxy server to access the Internet, you must specify a proxy server address on the Application Attributes page before you can create a Web service reference.
  To specify a proxy address for an application:
  

  1. On the Workspace home page, click the Application Builder icon.
  2. Select an application.
     Application home page appears.
  3. Click the Edit Application Properties button.
  4. Under Name, enter the proxy server in the Proxy Server field.
  5. Click Apply Changes.