Creating RESTful Web Services

4.5 Creating RESTful Web Services

Create RESTful web services using the Modules, Templates and Handlers pages.

To create a RESTful web service, you need to:

Define a resource module
Define a resource template
Define one or more resource handlers such as GET, PUT, POST or DELETE. Optionally, define parameters that you need to pass to the resource handler.

The following sections provide information on how to create resource modules, resource templates and resource handlers.

4.5.1 Managing Resource Modules

You can define, edit and delete resource modules in the Modules page.

To navigate to the Modules page, in the REST Overview page, click Modules in Objects, or from the menu in the header, select Modules.

The module attributes displayed by default in card view are shown in the following figure.

Description of the illustration module_card.png

The module status can be published or unpublished. If the status is unpublished, the icon is displayed in a red color.

Click the module name in card view to go to the Templates page for that module. You can also navigate to the Templates page through the context menu.

The actions available in the context menu are:

Creating a Resource Module
Editing a Resource Module
Deleting a Resource Module
Publishing/Unpublishing a Resource Module
Exporting a Resource Module
Navigating to the Templates page for a module

See Also:

About the REST Search Toolbar

4.5.1.1 Creating a Resource Module

This section describes how to create a resource module.

In the Modules page, click Create Module.
Enter the following fields. The fields with an asterisk (*) are mandatory:
Module Definition tab
- Module Name: Enter the name of the module. This field is case sensitive.
- Base Path: Enter the base of the URI for accessing the RESTful service. For example: hr/ means that all URIs starting with hr/ will be serviced by this resource module. Note the change in the Preview URL as you enter the base path.
- Is Published: Enable to make the RESTful service available for use.
- Pagination Size: Enter or select the number of results to return on each page based on a database query. The default value is 25.
- Comments: Enter descriptive comments.
- Go to Module after creation: Select this option to go to the Templates page after the module is created.
Origins Allowed tab
- Enter origins that are allowed to access the resource templates. Click Add (+) to add each origin. For example:
  
  http://example1.org
  
  https://*.example2.com
Click Create.

The new module is displayed on the Modules page. If you cannot see it, locate the module using the Search field.

4.5.1.2 Editing a Resource Module

This section describes how to edit a resource module.

In the Modules page, for the specific module, click , and select Edit.
Edit the required fields and click Save. For a description of the fields, see Creating a Resource Module.

4.5.1.3 Deleting a Resource Module

This section describes how to delete a resource module.

In the Modules page, for the specific module, click and select Delete.

A prompt appears asking you to confirm.
Click OK to delete.

4.5.1.4 Publishing/Unpublishing a Resource Module

This section describes how to make a resource module available or not.

In the Modules page, for the specific module, click and then select Publish or Unpublish.

You see a prompt to confirm.
Click OK.

4.5.1.5 Exporting a Resource Module

You can export the PL/SQL source code for a resource module or RESTful service using the Copy to Clipboard option. If the module has templates, handlers, parameters, roles, and so on, these objects are also displayed and available for copying to the clipboard.

In the Modules page, for a specific module, click and select Export.

The PL/SQL code for the module appears.
Click Copy to Clipboard.

4.5.2 Managing Resource Templates

You can define, edit and delete resource templates for a module in the Templates page.

To navigate to this page, in the Modules page, click for a module and select Templates, or click the name of the module in card view.

At the top of the page, the module card is available with context menu options such as Edit, Delete, Publish and Export.

The templates attributes displayed by default in card view are shown in the following figure.

Description of template_card.png follows

Description of the illustration template_card.png

Click the template name in card view to go to the Handlers page. You can also navigate to the Handlers page through the context menu.

The actions available in the context menu are:

Creating a Resource Template
Editing a Resource Template
Deleting a Resource Template
Navigating to the Handlers page for the template

4.5.2.1 Creating a Resource Template

This section describes how to create a resource template.

In the Templates page for a module, click Create Template.
Enter the following fields. The fields with an asterisk (*) indicate that they are mandatory:
- URI Template: Enter the URI pattern for the resource template.
  
  For example, a pattern of /objects/:object/:id? will match /objects/emp/101 (matches a request for the item in the emp resource with id of 101) and will also match /objects/emp/ (matches a request for the emp resource, because the :id parameter is annotated with the ? modifier, which indicates that the id parameter is optional).
  
  Note that the Preview URL changes as you type the URI template.
- Priority: Enter or choose the priority for how the resource template should be evaluated (1 is low priority and 9 is high priority).
- HTTP Entity Tag Type: Select the type of entity tag to be used by the resource template. An entity tag is an HTTP Header that acts as a version identifier for a resource.
  
  Options include:
  - Secure HASH (default): The contents of the returned resource representation are hashed using a secure digest function to provide a unique fingerprint for a given resource version.
  - Query: Define a query manually that uniquely identifies a resource version. A manually defined query can often generate an entity tag more efficiently than hashing the entire resource representation.
  - None: Do not generate an entity tag.
- Comments: Enter descriptive comments if any.
- Go to Handlers after creation: Select this option to go to the Handlers page after the template is created.
Click Create.

The new template for the module is added to the Templates page.

If "Go to Handlers after creation" is selected, you can use the module name in the breadcrumbs at the top of the page to see the list of templates for the module.

4.5.2.2 Editing a Resource Template

This section describes how to edit a resource template.

In the Templates page, for a specific template, click and then select Edit.
Edit the required fields and click Save.

For a description of the fields, see Creating a Resource Template.

4.5.2.3 Deleting a Resource Template

This section describes how to delete a resource template.

In the Templates page, for a specifc template, click and then select Delete.

You are prompted to confirm.
Click OK to delete.

4.5.3 Managing Resource Handlers

You can create, edit and delete resource handlers for a template in the Handlers page.

To navigate to this page, in the Templates page, click for a template and select Handlers, or click the name of the template in card view.

At the top of the page, the template card is available with context menu options such as Edit and Delete.

Tthe handler attributes displayed by default in card view are shown in the following figure.

Description of the illustration handler_card.png

The HTTP Method can be one of the following: GET, PUT, POST and DELETE.

Click the handler name to go to the HTTP method page or you can also navigate to the HTTP method page using the context menu.

The actions available in the context menu are:

Creating a Resource Handler

Note:
This option is not available if the template has all four handlers created (GET, POST, PUT, DELETE).
Editing a Resource Handler
Deleting a Resource Handler
Navigating to the Handler HTTP method page

4.5.3.1 Creating a Resource Handler

This section describes how to create a resource handler.

In the Handlers page, click Create Handler.
Specify the properties of the resource handler. The specific options depend on the method type.
Handler Definition Tab
- Method: Enter the HTTP request method for this handler: GET (retrieves a representation of a resource), POST (creates a new resource or adds a resource to a collection), PUT (updates an existing resource), or DELETE (deletes an existing resource). Only one handler for each HTTP method is permitted.
- Items Per Page: Enter or choose the default pagination size, or the number of rows to return for a database query. This option is only available for GET handlers. If this value is not defined, the number of items per page is the one defined in the module.
- Source Type: Select the source implementation for the selected HTTP method. The default is collection query.
  - Collection Query: Executes a SQL query and transforms the result set into a JSON representation. Available when the HTTP method is GET.
  - Collection Item: Executes a SQL query returning one row of data into a JSON representation. Available when the HTTP method is GET.
  - Media: Executes a SQL Query conforming to a specific format and turns the result set into a binary representation with an accompanying HTTP Content-Type header identifying the Internet media type of the representation.
  - PL/SQL: Executes an anonymous PL/SQL block and transforms any OUT or IN/OUT parameters into a JSON representation.
- Source: Enter the SQL query or the PL/SQL block for the HTTP method. In the handler details page, you can test the SQL or PL/SQL handler code in the handler editor.
- Go to Handler after creation: Select this option to go to the details page after the handler is created.
MIMEs Allowed tab

Identifies the type of information included in the HTTP Request Body. For example, if the POST Handler is expecting JSON in the request, add "Application/JSON" as the MIME type.
Click Create.

The handler is displayed on the Handlers page for the specific template.

You can test the REST service endpoint using a REST client or a command-line tool such as cURL.

4.5.3.2 Example: Inserting a Record using a POST Handler

The following example illustrates how to insert a record in the DEPT table.

Prerequisites

Using the worksheet in the SQL page, create a DEPT table.

CREATE TABLE DEPT(  
  DEPTNO     number(2,0),  
  DNAME      varchar2(14),  
  LOC        varchar2(13),  
  CONSTRAINT PK_DEPT PRIMARY KEY (DEPTNO)  
)

Create a module named example. See Creating a Resource Module
Create a template named emp/ for the module. See Creating a Resource Template

To insert a record:

In the Handlers page, click Create Handler.
Enter the following details:
- In the Method field, select POST.
- In the Source Type field, select PL/SQL.
- In the Source field, enter the following PL/SQL block:
```
DECLARE  
   id number;
BEGIN
    INSERT INTO DEPT (DEPTNO, DNAME, LOC) VALUES (:DEPTNO, :DEPTNAME, :DEPTLOC) RETURNING DEPTNO INTO id;
    :status_code := 201;
    :forward_location := id;
END;
```
  where
  - RETURNING DEPTNO INTO id returns the value assigned to DEPTNO into the variable id.
  - :status_code is an implicit parameter that is assigned 201 to indicate that the resource is created.
  - :forward_location is an implicit parameter that is assigned the id that contains the value of DEPTNO. This parameter specifies the location to forward a GET request to produce the response for the POST request.
- Ensure Go to Handler page after creation is selected.
- In the MIMEs Allowed Tab, select application/json from the drop-down list and click Add +.
- Click Create.
The Handler POST page appears.

Description of the illustration example_handler_source.png

You can test the source code by clicking Execute in the Source editor.
Create a GET resource handler to produce a response for the POST request.
In the Example module, create a template named emp/:id.

Create a GET resource handler where Source Type is Collection Item and Source contains the following query:
```
SELECT * FROM DEPT WHERE DEPTNO = :id
```
Description of the illustration example_get_handler.png

Test the RESTful service endpoint using the following command in cURL. You can copy the URL (http://xyz.us.comp.com:1234/ords/pdbdba/example/emp) using the Copy to Clipboard icon in the POST handler card at the top.

curl --location --request POST --header "Content-Type: application/json" 
--data '{"DEPTNO": 54, "DEPTNAME": "HR", "DEPTLOC": "America" }' 'http://xyz.us.comp.com:1234/ords/pdbdba/example/emp/'

The output is:

{"deptno":54,"dname":"HR","loc":"America","links":[{"rel":"collection",
"href":"xyz.us.comp.com:1234/ords/pdbdba/example/emp/"}]}

In the SQL page, check the DEPT table to see if the new record has been inserted by using the following statement:
```
SELECT * FROM DEPT;
```

4.5.3.3 Editing a Resource Handler

This section describes how to edit a resource handler.

In the Handlers page, for a specific handler, click and then click Details.
Edit the required fields and click Save.

For a description of the fields, see Creating a Resource Handler.

4.5.3.4 Deleting a Resource Handler

This section describes how to delete a resource handler.

In the Handlers page, for the specific handler, click and then click Delete.

You are prompted to confirm.
Click OK to delete.

4.5.4 Viewing Resource Handler Details and Managing Parameters

You can view resource handler details and manage parameters in the HTTP method page.

To navigate to this page, for a specific handler, click and then select Details or click the name of the handler in card view.

At the top of the page, the handler card is available with context menu options such as Edit and Delete.

The Handler HTTP method page has two major sections:

A code editor for executing the SQL or PL/SQL source code that was defined in the resource handler. You can execute the code, save, undo, redo, download and clear output.
A section for managing parameters required for running the HTTP method.

By default, the parameters are displayed in grid view. The attributes displayed on a parameter in card view are shown in the following figure.

Description of parameter_card.png follows

Description of the illustration parameter_card.png

The actions available in the context menu are:

See Also:

About the REST Search Toolbar

4.5.4.1 Creating a Parameter

This section describes how to create a parameter for a resource handler.

In the handler HTTP method page, click Create Parameter.
Enter the following fields. The fields with an asterisk (*) are mandatory:
- Parameter Name: Enter the name of the parameter, as it is named in the URI Template or HTTP Header. The name defines how the parameter is identified in the incoming request or how the parameter is named in the Response.
- Bind Variable Name: Enter the name of the parameter, as it will be referred to in SQL. If NULL is specified, then the parameter is unbound.
- Source Type: Select the type that is identified if the parameter originates in the URI Template or HTTP Header.
- Parameter Type: Select the native type of the parameter.
- Access Method: Select the parameter access method. Indicates if the parameter is an input value, output value, or both.
Click Create.

The parameter is added in the Parameters section.

4.5.4.2 Editing a Parameter

This section describes how to edit a parameter.

In the Parameters section, for the specific parameter, click and then select Edit.
Edit the required fields and click Save.

For a description of the fields, see Creating a Parameter.

4.5.4.3 Deleting a Parameter

This section describes how to delete a parameter.

In the Parameters section, for the specific parameter, click and then select Delete.

You are prompted to confirm.
Click Yes to delete.