This section describes how to utilize Web services in Oracle Application Express applications.
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/
Topics:
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 App 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 run Oracle Application Express with Oracle Database 11g Release 1 (11.1), you must enable network services to use Web services.
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.
To use 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.
Topics:
You manage Web service references on the Web Service References page.
To access the Web Service References page:
If your environment requires a proxy server to access the Internet, you must either specify a proxy server address on the Application Attributes page, or your instance administrator must define an instance proxy, before you can create a Web service reference.
To specify a proxy address for an application:
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
This section describes how to create Web service reference based on a WSDL.
Topics:
Before you create a Web service reference based on a WSDL, you must decide how to locate the WSDL. You locate a WSDL by entering the URL to the WSDL document.
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
To create a Web service by specifying a URL to a specific WSDL document:
This section describes how to create a Web service reference manually.
Topics:
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
To create a Web service reference manually:
The Web service reference is added to the Web Service References Repository.
See Also:
This section describes how to create a RESTful Web service reference.
Topics:
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
To create a RESTful Web service reference:
The Create Web Service Reference Success page appears. The Web service reference is added to the Web Service References Repository.
See Also:
"Creating a Proxy Server for an Instance" in Oracle Application Express Administration Guide
Web service references are stored in the Web Service Reference Repository.
To access the Web Service References Repository:
This section describes how to create an input form and report on a Web service.
Topics:
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.
To create a form and report after creating a Web service reference:
This section describes how to create a form on a Web service.
Topics:
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 by running the Create Page Wizard.
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.
To create a form after creating a Web service reference:
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 the report.
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:
See Also:
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:
Note:
The History button only appears on the Web Service Reference page if at least one reference exists.
This section describes how to expose a report region as a RESTful Web service.
Topics:
See Also:
"Using RESTful Services" in Oracle Application Express SQL Workshop Guide
To expose a report region as a RESTful Web service, perform the following steps:
Step 1: The Instance administrator must enable the REST provider feature in instance settings.
Step 2: A developer must enable RESTful access to a report region.
Step 3: The page that contains the report must not require authentication.
See Also:
"Enabling RESTful Access" in the Oracle Application Express Administration Guide
To enable RESTful access to a report region, you must make the page public so no authentication is required and enable the report for RESTful access.
Tip:
To enable RESTful access to an Oracle Application Express instance, see "Enabling RESTful Access" in the Oracle Application Express Administration Guide.
To enable RESTful Access to a report region:
See Also:
"Enabling RESTful Access"in the Oracle Application Express Administration Guide
Once you enable 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 |
---|---|---|---|
|
|
Yes |
The numeric ID or alias of the application that contains the RESTful enabled report. |
|
|
Yes |
The numeric ID or alias of the page that contains the RESTful enabled report. |
|
|
Yes |
The Static ID attribute of the RESTful enabled report. |
|
|
No |
Values for the report parameters can be sent in a comma separated list. For example: CLERK,10 |
|
|
No |
Sets the NLS environment variables before running the report based on the language passed in. For example: de |
|
|
Yes |
This determines whether XML or JSON are 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.