Purpose

This tutorial covers creating a RESTful Web Service and accessing the Web Service through an application in Application Express 4.2. This tutorial also covers consuming the Web Service using a Java client.

Time to Complete

Approximately 40 minutes

Introduction

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. Web Services are typically based on Simple Object Access Protocol (SOAP) or Representational State Transfer (REST) architectures. RESTful Web Services are result 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,
and DELETE.

This tutorial covers creating a RESTful Web Service declaratively using Oracle Application Express's SQL Workshop tool, and then consuming the same service by creating an application and adding a Web Service Reference to the RESTful Web Service. The RESTful
Web Service is also consumed using a Java client.

Prerequisites

Before starting this tutorial, you should have:

• Access to an Oracle Database 11g database or above that has the sample schema installed.
• Installed Application Express Release 4.2 into your Oracle Database.
• Access to the OEHR tables. If necessary, download and install OEHR Sample Objects available from OTN at http://www.oracle.com/technetwork/testcontent/oehr-sample-objects-131098.zip
• Installed Java Development Kit 6 or later to consume the RESTful Web Service using a Java client.
• Downloaded and unzipped the files.zipinto your working directory.

In this topic, you create a RESTful Web Service using RESTful Services tool in SQL Workshop. The RESTful Web Service Wizard is a set of pages in SQL Workshop that help you to create a RESTful Web Service declaratively. The RESTful Web Service calls a specific
SQL statement in your database.

Log into the Application Express Login page using your login credentials. Enter the following credentials and click Login. 

Note: Here, the Workspace, Username and Password used are obe.

Workspace: OBE

Username: OBE

Password: obe

Click SQL Workshop.

Select RESTful Services.

Click Create to create a RESTful Service.

Enter Employees as the Name for the RESTful Service module. Enter the URI Template as employees to identify your Uniform Resource Identifier (URI). Select GET as the method. Select CSV for Format.
This identifies the HTTP method to be used for the Resource Handler. For Source, enter the following SQL query. This is responsible for handling the selected HTTP method. Click Create Module.

select * from oehr_employees

Click the GET method Resource Handler.

Change the Require Secure Access option from Yes to No. Click Apply Changes.

Click Test to test the behavior of the RESTful Service Handler.

You are prompted to save the file which you can then view using a CSV editor. The CSV format resultset is displayed. Make a note of the URI which is used later while creating a client service.

Click Create Handler to create a Resource Handler for the POST method.

Select POST for Method, Source Type as PL/SQL, Mime Types Allowed as application/json. Select No for Requires Secure Access. In the Source section enter the following PL/SQL
code to create a row by inserting values into the employees table. Click Create.

declare

id oehr_employees.employee_id%TYPE;

begin

id := oehr_employees_seq.nextval;

insert into oehr_employees (employee_id,first_name, last_name, email, hire_date, job_id)

values (id, :first_name, :last_name, :email, to_date(:hire_date, 'DD-MM-YYYY'), :job_id); :employee_id := id;

end;

Scroll down the page and click Create Parameter to add an OUT parameter to the handler that will return the newly created employee’s ID.

Enter employee_id for Name and employee_id for Bind Variable Name. Select OUT for Access Method, HTTP Header for Source Type, and String for Parameter Type. Click Create.

You will next create a new template to retrieve JSON resultset based on Query One Row with a Bind Variable. Create a new template by clicking Create Template.

Enter employees/{id} for URI template. Click Create.

Click Create Handler.

Select Query One Row for Source Type and select No for Requires Secure Access. Enter the following SQL statement for Source and click Create.

select * from oehr_employees where employee_id = :id

Click Create Parameter.

Enter id for Name and Bind Variable Name. Select Source Type as HTTP Header. Click Create.

The Source Type URI is not being displayed and hence you want to edit the Resource Handler Parameter that you just created. Select id from the Parameter list and select URI for Source Type. Click Apply Changes.

Click Set Bind Variables.

Enter 103 or any Employee ID for the Value of the :ID Bind Variable and click Test.

Open the file. All the information for employee_id is displayed, which is the variable passed as the final portion of the URI. Close this window.

You create a new template for Retrieving JSON Result Set Based on a Feed. Here, you create the employeesfeed/ RESTful service, which selects the employee_id and the first_name values in the employees table and displays them as a feed. Create
a new template by clicking Create Template.

Enter employeesfeed/ for URI template. Click Create.

Click Create Handler.

Select Feed for Source Type and select No for Requires Secure Access. Enter the following SQL statement for Source and click Create.

select employee_id, first_name from oehr_employees order by employee_id, first_name

Click Create Template.

Enter employeesfeed/{id} for URI template. Click Create.

Click Create Handler.

Select Feed for Source Type and select No for Requires Secure Access. Enter the following SQL statement for Source and click Create.

select employee_id, first_name from oehr_employees where employee_id = :id

Click GET method of the employeesfeed/ URI template type

Click Test .

The data returned is displayed for all employees in the OEHR_EMPLOYEES table. The URI contains the link to the individual record. This link is actually using the employeesfeed/{id} Resource Template.

Copy the link and execute it in the browser. This will display the details of the individual employee's record.

In this topic, you consume the RESTful Web Service in Apex by creating a database application and by creating a Web Service Reference in the application. You create a form and report page that uses the web service.

Note: Make sure you have granted the connect privileges by executing the APEX_ACL.sql script from the files.zip that you have unzipped in the Prerequisites section of this
tutorial.

Navigate to your workspace home page and create a new application by selecting Application Builder > Database Applications > Create.

Enter the Name of the application as RESTful Web Services App and click Create Application.

Click Create Application.

On the application home page, click Shared Components.

Under Logic, click Web Service References.

Click Create.

Select REST for Web Reference and click Next.

Enter Employees for Name, enter the URL for URL. In this case enter http://localhost:8888/apex/obe/employees . Since the REST Web Service does not require an HTTP Header parameter, click the Delete
Header icon. Click Next.

Delete the input parameter by clicking the Delete Parameter icon. Click Next.

Select Text for Output Format. Enter the names of the parameters like Employee ID, Name, Hire Date, and Job ID by mapping them to the response. Click Test.

Select Test.

Scroll down to view the response. Click Close.

Click Create.

Click Create Form & Report on Web Service.

Select Web Service Reference as Employees. Click Next.

Accept the default values and click Next.

Click Next.

Select the check box next to Name to select all the parameters and click Next.

Click Next.

Click Create.

Click Run Page.

Enter your login credentials if prompted as OBE for Username and obe for Password. Click Login.

Click Submit.

The resultset is displayed.

In this topic, you consume the Web Service that you have created in Application Express using a Java Client.

Open Command Prompt.

Execute the following command to navigate to the directory where you extracted the files available in the Prerequisites of this tutorial. Navigate to where the RESTemp java code resides. If you have extracted it in the Downloadsdirectory
then, you can find the RESTemp file in the C:\Downloads\files\RESTemp directory.

cd Downloads

cd files\RESTemp

To fetch the details of an employee, enter the following command. Pass a value for employee_id. Note: Here, the command line parameter 'S' indicates that you want to do a select. Also, you have to edit the run.cmd file that you have downloaded
to replace the URL for your RESTful Web Service.

run.cmd S [employee_id]

The values for the employee are displayed.

To insert new values into the employees table, enter the following command to invoke the POST Method which will insert a new row into the table. Note: Here, the command line parameter 'I' indicates that you want to insert a new row.

run.cmd I

Enter the first name, last name, email address, hire date, and job ID. You will notice that a new row is created with a new employee ID.

You can verify if this new row entry was created in the table by navigating to SQL Workshop to check for the new row values.

In this tutorial, you have learned how to:

• Create a RESTful Web Service in Application Express
• Create a RESTful Web Service Reference in Application Express
• Consume the Web Service created in Application Express using a Java Client

Resources

• APEX OTN Home Page
• To learn more about Application Express 4.2, refer to additional OBEs in the Oracle Learning Library

• dc=D67259GC20&intcmp=WWOU11042424MPP032C002" style="text-decoration:none">Oracle Application Express: Developing Web Applications

• Oracle University

Credits

Put credits here

• Lead Curriculum Developer: Anupama Mandya