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.zip into 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.