Implementing Web Services

Web services enable applications to interact with one another over the Web in a platform-neutral, language independent environment. In a typical Web services scenario, a business application sends a request to a service at a given URL by using the protocol over HTTP. The service receives the request, processes it, and returns a response. You can incorporate calls with external Web services in applications developed in Application Builder.

Web services are typically based on Simple Object Access Protocol (SOAP) or Representational State Transfer (REST) architectures. SOAP is a World Wide Web Consortium (W3C) standard protocol for sending and receiving requests and responses across the Internet. SOAP messages can be sent back and forth between a service provider and a service user in SOAP envelopes. RESTful Web services are resource oriented. The scope of the Web service is found in the URI and the method of the service is described by the HTTP method that is used such as GET, POST, PUT, HEAD, and DELETE.

SOAP offers two primary advantages:

  • SOAP is based on XML, and therefore easy to use.

  • SOAP messages are not blocked by firewalls because this protocol uses simple transport protocols, such as HTTP.

Tip:

If you are running Oracle Application Express with Oracle Database 11g Release 1 (11.1), you must enable network services to use Web services. See "Enabling Network Services in Oracle Database 11g"

REST offers similar advantages:

  • REST messages are also not blocked by firewalls because this protocol uses the HTTP protocol.

  • REST requests do not require the overhead of XML and SOAP envelopes and inputs are typically provided in the URI.

Topics:

Note:

The SOAP 1.1 specification is a W3C note. SOAP Version 1.2 specification is a W3C recommendation.

For information about Simple Object Access Protocol (SOAP) see:

http://www.w3.org/TR/SOAP/

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.

Working with SSL Enabled Web Services

Secure Sockets Layer (SSL) is an industry standard protocol that uses RSA public key cryptography with symmetric key cryptography to provide authentication, encryption, and data integrity.

If the Web service that you need to interact with is SSL-enabled (that is, https displays in the URL to the Web service), you must create a wallet and configure Oracle Application Express to use the wallet. A wallet is a password-protected container that stores authentication and signing credentials (including private keys, certificates, and trusted certificates) needed by SSL.

See Also:

"Configuring Wallet Information" in Oracle Application Express Administration Guide

Creating a Web Service Reference Based on a WSDL

When you create a Web service reference based on a WSDL, you must decide how to locate the WSDL. You can locate a WSDL in two ways:

  • By searching a Universal Description, Discovery and Integration (UDDI) registry

  • By entering the URL to the WSDL document

A UDDI registry is a directory where businesses register their Web services.

Topics:

Creating a Web Service Reference by Searching a UDDI Registry

To create a Web service by searching a UDDI registry:

  1. Navigate to the Web Service References page. See "Accessing the Web Service References Page".

  2. Click Create.

  3. Select Based on WSDL and click Next.

  4. When prompted to search a UDDI registry to find a WSDL, click Yes then Next.

  5. For UDDI Location, enter a URL endpoint to a UDDI registry and click Next.

  6. For Search, specify the following:

    1. Search Type - Specify whether to search for a business name or a service name. You cannot search for both.

    2. Name - Enter the business name or service name to search for. Use the percent (%) symbol as a wildcard character.

    3. Optionally indicate if the search should be case-sensitive or an exact match.

    4. Click Search.

    5. When the search results appear, make a selection and click Next.

    A summary page appears describing the selected Web service.

  7. Review your selection and click Next to continue.

    The URL to the WSDL document displays in the WSDL Location field.

  8. Click Finish.

The Web service reference is added to the Web Service References Repository.

Creating a Web Service Reference by Specifying a WSDL Document

To create a Web service by specifying a URL to a specific WSDL document:

  1. Navigate to the Web Service References page. See "Accessing the Web Service References Page".

  2. Click Create.

  3. Select Based on WSDL and click Next.

  4. When prompted to search a UDDI registry to find a WSDL, click No then Next.

  5. In WSDL Location, enter the URL to the WSDL document.

  6. Click Finish.

The Web service reference is added to the Web Service References Repository.

Creating a Web Service Reference Manually

To create a Web service reference manually:

  1. Navigate to the Web Service References page. See "Accessing the Web Service References Page".

  2. Click Create.

  3. Select Manual and click Next.

    The Create/Edit Web Service page appears.

  4. In Name, enter a name to identify the reference.

  5. Under Service Description:

    1. URL - Enter the URL used to post the SOAP request over HTTP. This corresponds to the soap:address location of a service port in the WSDL.

    2. Action - Enter the intent of the SOAP HTTP request (optional). The value is a URI identifying the intent. SOAP places no restrictions on the format or specificity of the URI or requires that it is resolvable.

    3. Proxy - Enter a proxy to override the application proxy for this service.

    4. SOAP Version - Select 1.1 or 1.2.

    5. Basic Authentication - Choose whether the Web service requires authentication. Select Yes or No.

  6. For SOAP Envelope, enter the SOAP envelope to be used for the SOAP request to the Web service.

    Note:

    You can reference items from session state in the SOAP envelope by using #ITEM_NAME# syntax.

  7. For Store Response in Collection, enter the name of a collection to store the response (optional). The response is stored in the CLOB001 column.

  8. Click Create.

The Web service reference is added to the Web Service References Repository.

Creating a RESTful Web Service Reference

To utilize a RESTful Web service from your application, you must create a RESTful Web service reference.

To create a RESTful Web service reference:

  1. Navigate to the Web Service References page. See "Accessing the Web Service References Page".

  2. Click Create.

  3. Select REST and click Next.

  4. For REST Details, specify the following:

    1. Name - Enter a name to identify the reference.

    2. URL - Enter the URL endpoint of the Web service.

    3. Proxy - Enter a proxy to override the application proxy for this service (optional).

    4. HTTP Method - Choose the http method used for the request to the Web service. Select GET, HEAD, POST, PUT or DELETE.

    5. Basic Authentication - Select Yes to require HTTP Basic Authentication. Otherwise, select No.

    6. HTTP Headers - Enter the names of the HTTP headers to send with the request.

    7. Click Next.

  5. For REST Input parameters, specify the following:

    1. Name - Enter the name of the input parameter expected by the method.

    2. Type - Select the input type.

    3. Click Add Parameter.

    4. Repeat steps a though c for each expected input.

    5. Click Next.

  6. For REST Output parameters, specify the following:

    1. Output Format - Select XML or Text for the response format expected from the Web service.

    2. XPath to Output Parameters (XML only) - Enter an XPath expression to the relevant part of the response.

    3. Response Namespace (XML only) - Enter the namespace corresponding to the Response XPath.

    4. Parameter Delimiter (Text only)- Enter the character or sequence that separates parameters returned from the Web service. Use \n to indicate a new line and \t to indicate a tab character.

    5. New Record Delimiter (Text only) - Enter the character or sequence that determines a new record in a text response from the Web service. Use \n to indicate a new line and \t to indicate a tab character.

    6. Name - Enter the name of the output parameter returned by the method.

    7. Type - Select the output type.

    8. Click Add Parameter.

    9. Repeat steps f though h for each returned output parameter.

    Note:

    Click Test to send a request to a RESTful Web service and see the response. This test process will help you in specifying the appropriate Output parameters.

  7. Click Create.

The Create Web Service Reference Success page appears. The Web service reference is added to the Web Service References Repository.

Using the Web Service Reference Repository

Web service references are stored in the Web Service Reference Repository.

To access the Web Service References Repository:

  1. On the Workspace home page, click Application Builder.

  2. Select an application.

  3. Click Shared Components.

    The Shared Components page appears.

  4. Under Logic, click Web Service References.

    The Web Service Reference page appears.

    A Search bar displays at the top of the page. Available controls include:

    • Search columns icon - Resembles a magnifying glass. Click this icon to narrow your search. To search all columns, select All Columns.

    • Text area - Enter case insensitive search criteria (wildcard characters are implied) and then click Go.

    • Go button - Executes a search or applies a filter.

    • View. Use this control to toggle between icon and report views. To change the view, click these icons:

      • Icons (the default) displays each Web service reference as a large icon. To edit a Web service reference, click the appropriate icon.

      • Report displays each Web service reference as a line in a report.

    • Actions menu - Displays the Actions menu. Use this menu to customize the report view. See "About the Actions Menu".

  5. Click the View Report icon.

  6. In report view you can:

    • Edit a reference by clicking the reference name.

    • Test a reference by clicking the Run icon.

    • View details about a reference by clicking the View icon. Note that this option is not available for manually created or REST Web service references.

Testing a Web Service Reference Created from a WSDL

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. From Operation, select an operation (that is, the method to be executed).

  5. Under Input Parameters, enter the appropriate values.

  6. Click Test.

    The message request and response appear at the bottom of the page.

Testing a Web Service Reference Created Manually

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. If required, enter the username and password under Basic Authentication.

  5. In SOAP Envelope text area, optionally edit the SOAP request envelope.

  6. Click Test.

    The message request and response appear at the bottom of the page.

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.

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. See "Managing Pages in a Database Application".

    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.

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. See "Managing Pages in a Database Application".

    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.

Invoking a Web Service as a Process

You can invoke a Web service as a process on the page. The process is created for you if you run one of the Create Form wizards for Web services. Running the process submits the request to the service provider. You can then display the request results in report.

To invoke a Web service as a process:

  1. Create a Web Service Reference. See "Creating a Web Service Reference Based on a WSDL", "Creating a Web Service Reference Manually", or "Creating a RESTful Web Service Reference".

  2. Create a page. See "Managing Pages in a Database Application".

    In the Create Page Wizard:

    1. Select Blank Page.

    2. When prompted to use tabs, select No.

  3. Navigate to the Page Definition. See "Altering Page Attributes".

  4. Under Page Rendering or Page Processing, locate the Processes section and click Create.

    The Create Page Processes Wizard appears.

  5. For Process Type, select Web Services and click Next.

  6. For Process Attributes, specify the following:

    1. Name - Enter the process name.

    2. Sequence - Enter the sequence for this component. This specifies the order of evaluation.

    3. Point - Select the processing point.

    4. Click Next.

  7. For Process, specify the following:

    1. Web Service Reference - Select the Web service reference for this process.

      If the Web reference was created from a WSDL or is RESTful style, the Operation selection appears.

    2. Operation (WSDL or RESTful style Web service references only) - Select the Web service operation this process executes.

      The Web Service Input Parameters and Web Service Output Parameters appear.

    3. Under Web Service Input Parameters, specify inputs to the Web service process:

      • Source - Select the source type.

      • Value - Select the source value.

    4. Under Web Service Output Parameters, specify where the results are stored:

      To store the results in a collection:

      • Store Result in - Select Collection.

      • Value - Enter a name for the collection.

      To store the results in items on the page:

      • Store Result in - Select Items.

      • Value - Enter the appropriate item value.

    5. Click Next.

  8. For Messages:

    1. Success Message - Enter the message that displays on the next page when the process runs successfully.

    2. Failure Message - Enter the message that displays when an unhandled exception is raised. After any error processing stops, a rollback is issued and an error message displays.

  9. For Process Conditions:

    1. When Button Pressed - Select that button that causes the process to run.

    2. Condition Type - Select a condition type that must be met in order for this component to be processed. If the condition type requires expressions for comparison, the Expression 1 and possibly Expression 2 fields display. Enter expressions into these fields as required.

  10. Click Create Process.

Displaying Web Service Results in a Report

To create a report in which to display Web Service request results:

  1. Navigate to the Page Definition. See "Editing a Page in Component View".

  2. Under Regions, click the Create icon.

    The Create Region Wizard appears.

  3. For the region type, select Report.

  4. For the report implementation, select Report on collection containing Web service result.

  5. On Identify Region Attributes, enter a region title and optionally edit the region attributes.

  6. Choose whether the Web reference was created manually, from a WSDL, or is RESTful style.

  7. If the Web service reference was created from a WSDL:

    1. For Web Service Reference and Operation, select a Web service reference and an operation (that is, the method to be executed).

    2. For Result Tree to Report On, select the portion of the resulting XML document that contains the information you want to include in the report.

    3. For Result Parameters:

      • In Temporary Result Set Name, enter a name for the collection that stores the Web service result.

      • Select and deselect the appropriate parameters.

  8. If the Web service reference was created manually:

    1. Select the Web service reference.

    2. Choose the SOAP style.

    3. Choose the message format.

    4. Enter the XPath expression to the node to report on.

    5. Enter the namespace for the SOAP response envelope and click Next.

    6. Enter the name of the collection where the response message is stored.

    7. Enter the names of the parameters that you want to be included in the report.

  9. If the Web service reference is REST style:

    1. Select the Web service reference.

    2. Enter the name of the collection where the response message is stored.

    3. Choose the report template and the number of rows to display per page.

    4. Select the parameters to be included in the report.

  10. Click Create SQL Report.

Editing a Web Service Process

After you create a process of type Web service on a Web service reference created from a WSDL or a RESTful style Web reference, you can change the attributes of the input and output parameters to the service.

To edit a Web service process:

  1. Create a Web service process. See "Invoking a Web Service as a Process".

  2. Navigate to the Page Definition containing the Web service process.

  3. Select the process name.

    The Edit Page Process page appears.

  4. To map an input parameter to a static value:

    1. Scroll down to Web Service Input Parameters.

    2. Enter a value in the Value field, adjacent to the appropriate parameter name.

  5. Click Apply Changes.

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.

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. To enable RESTful access to an Oracle Application Express instance, see "Enabling RESTful Access" in the Oracle Application Express Administration Guide.

  2. A developer must enable RESTful access to a report region. See Enabling RESTful Access to a Report Region.

  3. The page that contains the report must not require authentication.

Topics:

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.