Application Integration WorkshopBy David Peake
Consuming Web services with Oracle Application Express
Just about every leading Web site, from Amazon and eBay to Facebook and Google, has a Web services offering these days. 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, using HyperText Transfer Protocol (HTTP). The service receives the request, processes it, and returns a response.
Oracle Application Express has supported Web services integration for several releases now, but with Oracle Application Express 3.0, that support has been enhanced—for example, document-style Web services are now supported. Oracle Application Express 3.0 also enables manual creation of Web service references. This column shows you how to create Web services references manually, using one of the YouTube Web services APIs.
Note that you must create this example on your own instance of Oracle Application Express—the apex.oracle.com site does not support external network callouts, so it cannot be used for this project.
Oracle Application Express 3.0 provides two approaches to adding Web services to an application:
Example YouTube XML-RPC-Style Web Service
YouTube (www.youtube.com) offers access to several areas of its video repository via an open API interface that lets you easily integrate YouTube content into an application. The YouTube APIs enable you to obtain information about videos and obtain videos by tag name or username. For this sample application project, you'll obtain just music videos and display them in a report-style format. YouTube's Web services APIs are in both representational state transfer (REST) and XML-RPC format. This example describes how to create an Oracle Application Express application that interacts with the YouTube XML-RPC Web service music video API.
To use the YouTube APIs, you must have a YouTube account (it's free) and you must obtain a developer ID (also free). Your developer ID is embedded in the XML-RPC request document and submitted with every request to the API. To get your account and developer ID, visit www.youtube.com/dev.
The sample application project consists of the following steps:
Step 1: Create an Oracle Application Express application
Step 1: Create an application. Prior to creating the manual Web reference to the YouTube music video XML-RPC Web service, you must create an application in Oracle Application Express.
1. Log on to your Oracle Application Express workspace.
If your Oracle Application Express instance requires a proxy server to reach pages on the internet, you must define the proxy server in Application Definition ( Shared Components -> Application -> Definition ).
Step 2: Create a manual Web reference. To create a manual Web reference, enter the URL to the Web service and define the document to send to it. The results will be stored in a collection, which you define in the steps below. To create a manual Web reference,
1. Click Shared Components.
Code Listing 1: Web services properties
Name: YouTube Music Videos URL: http://www.youtube.com/api2_xmlrpc SOAP Envelope: <?xml version='1.0'?> <methodCall> <methodName>youtube.videos.list_by_category_and_tag</methodName> <params> <param><value><struct> <member> <name>dev_id</name> <value><string>YOUR_DEV_ID</string></value> </member> <member> <name>category_id</name> <value><int>10</int></value> </member> <member> <name>tag</name> <value><string></string></value> </member> <member> <name>per_page</name> <value><int>5</int></value> </member> </struct></value></param> </params> </methodCall> Store Response in Collection: YOUTUBE_MUSIC_VIDEOS
6. Click Create . The YouTube Music Videos component appears on the Web Services References page.
Step 3: Test the Web reference. To test the manual Web reference you created for the YouTube music videos list, you must have the component selected on the Web Service References page:
1. Select Details from the View list, and then click Go . The component appears in a table just below the selection row.
The response section displays the XML-RPC response, a string that contains an escaped, standalone XML document. The embedded XML document contains the information about the music videos. (In step 5, you'll see how to unescape the content so that it displays properly in a report.)
Step 4: Create a process to associate with the Web service. Now that you've created the Web service reference, you must invoke it from your application. To create the process that invokes the Web reference,
1. Navigate to the definition of page 1.
Step 5: Extract the embedded XML document. The YouTube Music Videos API returns a string (an XML-RPC response) that contains an escaped standalone XML document comprising the result of the API call: the list of music videos. (When the embedded XML is unescaped, the result is the same as the response to a REST call.) It's this result that you want the application to report on, so now create a process that extracts the document and unescapes the XML. The process also updates the collection used to store the response with the value of the extracted document.
To create a process to extract the embedded XML document,
1. Click the plus ( + ) icon in the Processes region under Page Rendering.
Code Listing 2: PL/SQL code that processes the embedded XML
declare l_clob clob; l_xml xmltype; l_val clob; begin for c1 in (select clob001 from apex_collections where collection_name = 'YOUTUBE_MUSIC_VIDEOS' ) loop l_clob := c1.clob001; exit; end loop; l_xml := xmltype.createxml(l_clob); l_val := dbms_xmlgen.convert(l_xml.extract('/methodResponse/params/param/value/ string/text()').getclobval(),1); apex_collection.update_member_attribute( p_collection_name => 'YOUTUBE_MUSIC_VIDEOS', p_seq => '1', p_clob_number => '1', p_clob_value => l_val ); end;
6. Leave the message text areas blank, and click Next.
Step 6: Create a report on the manual Web reference. To display the output of the Web services reference, build a report by using the "Create Report on a Manual Web Service" wizard. For this step, you must provide information about the structure of the XML response document.
To create a report on a manual Web service,
1. Click the plus ( + ) icon in the Regions area under Page Rendering.
The basic application is now complete. Click the Run Page icon to view the application.
Step 7: Refine the report. You can fine-tune the report layout, displaying thumbnails of the video and adding hyperlinks from the thumbnail to the video on YouTube. To make refinements to the report,
1. Click the Report link next to the Music Videos region on the page definition of page 1.
<a href="#url#"> <img src="#thumbnail_url#" /> </a>
4. Click Apply Changes.
Run the page to view your refinements. Figure 1 shows a sample result.