Previous Next JavaScript must be enabled to correctly display this content

## 7.6 Managing RESTful Service Modules

Learn how to install sample RESTful service module, You can create ,edit, and delete an ORDS RESTful service module.

A RESTful Service Module is a grouping of common templates, known as resource templates, under a common Uniform Resource Identifier (URI) prefix.

The specification of a URI prefix is optional. If defined for the RESTful Service Module, it is prepended to all resource templates. A priority value is used to choose between resource templates when their patterns both match a single request URI. In such cases, the resource template with the highest priority value is chosen.

- Installing a Sample RESTful Service Module with Schema ORDS not Enabled
  Learn how to create a Sample RESTful Service Module with Schema ORDS not Enabled.
- Installing a Sample RESTful Service Module with Schema ORDS Enabled
  Learn how to create a Sample RESTful Service Module with Schema ORDS Enabled.
- Creating an ORDS RESTful Service Module
  Learn how to create an ORDS RESTful Service Module.
- Editing an ORDS RESTful Service Module
  An ORDS RESTful Service Module can have associated resource templates and resource handlers. During the edit process for a particular RESTful Service Module, you can make changes to any of the associated resource templates and resource handlers.
- Deleting an ORDS RESTful Service Module
  Deleting an ORDS RESTful service module removes the module along with all resource templates and resource handlers associated with this module.
- Managing an ORDS RESTful Service Privileges
  Privileges to access RESTful Service Modules can be restricted in APEX.
- Assigning Privileges to an ORDS RESTful Service Modules
  Learn how to assign privileges to an ORDS RESTful Service Modules.
- Creating an ORDS RESTful Service Privilege
  You can create an ORDS RESTful Service Privilege to restrict access to specified users for one or more RESTful Service Modules.
- Editing an RESTful Service Privilege
  You can modify an ORDS RESTful Service Privilege. Changes to the specified Protected Modules will be reflected in the Required Privilege setting on the RESTful Service Module page for affected modules.
- Deleting an ORDS RESTful Service Privilege
  You can remove an ORDS RESTful Service Privilege. After deleting the privilege, any RESTful Service Modules that were protected by this privilege will be unprotected until reassigned another privilege.
- Exporting an ORDS RESTful Service Module
  An ORDS RESTful Service Module metadata can be exported to a file in SQL script format. The exported file can be imported on the same instance or another compatible Oracle APEX instance.
- Importing an ORDS RESTful Service Module
  An ORDS RESTful Service Module metadata that has been exported to a file in SQL script format can be imported. The imported module must have been exported on the same instance or another compatible Oracle APEX instance.
- Generating a Swagger Document
  Learn how to generate a Swagger document.

Parent topic: Enabling Data Exchange with RESTful Services

### 7.6.1 Installing a Sample RESTful Service Module with Schema ORDS not Enabled

Learn how to create a Sample RESTful Service Module with Schema ORDS not Enabled.

Note:

You can install a sample RESTful service only when you create new workspace.

To create a Sample RESTful Service Module:

1. On the Workspace home page, click SQL Workshop and then RESTful Services.

   The RESTful Services home page appears.

2. Click ORDS Based RESTful Services.

   The ORDS RESTful Services page appear.

3. Click Register Schema with ORDS.

   The ORDS Schema Attributes page appears.

   Note:

   ORDS enabling a schema that is assigned to more than one workspace as the default schema causes issues with workspace related static files. Oracle recommends that you do not ORDS enable schemas shared amongst multiple workpaces until you are running ORDS 18.3 or higher.

4. Enter the attribute details:
   1. Enable RESTful Access - Select On to enable or Off to disable access to any REST services defined in the schema.
   2. Schema Alias - Enter the name of the schema alias to be used in the formation of the URL referencing any RESTful service within the schema.
   3. Install Sample Service - Select On. Selecting On installs sample `oracle.example.hr` RESTful service.
   4. Authorization Required for Metadata Access - Select On. Selecting On requires Oracle REST Data Services user authorization before allowing access to the ORDS metadata catalog of the schema.
5. Click Save Schema Attributes.

   The ORDS RESTful page appears. Sample RESTful Services appears under Modules.

Parent topic: Managing RESTful Service Modules

### 7.6.2 Installing a Sample RESTful Service Module with Schema ORDS Enabled

Learn how to create a Sample RESTful Service Module with Schema ORDS Enabled.

Note:

You can install a sample RESTful service only when you create new workspace.

To create a Sample RESTful Service Module:

1. On the Workspace home page, click SQL Workshop and then RESTful Services.

   The RESTful Services home page appears.

2. Click ORDS Based RESTful Services.

   The ORDS RESTful Services page appear.

3. Click Install Sample Service on the right pane.

   The Sample service is installed and appears under RESTful Services Modules.

   Note:

   Click Reset Sample Service button to reset the sample service. Reset Sample Service Verification dialog appears warning the user that the service will be completely deleted and re-created.

Parent topic: Managing RESTful Service Modules

### 7.6.3 Creating an ORDS RESTful Service Module

Learn how to create an ORDS RESTful Service Module.

To create an ORDS RESTful Service Module:

1. On the Workspace home page, click SQL Workshop and then RESTful Services.

   The RESTful Services home page appears.

2. Click ORDS Based RESTful Services.

   The ORDS RESTful Services page appears.

3. Click Modules under RESTful Data Services tree.
4. Click Create Module on the right pane.

   The ORDS Module Definition page appears.

5. Specify the following RESTful Service Module settings:

   - Module Name - Enter the name of the RESTful Service Module.

   - Base Path - Enter module base path.

   - Is Published - Select On to make this service available for use, otherwise select Off.

   - Pagination Size - Specify the size of the pagination window. For database queries, this is the number of rows to return.

   - Origins Allowed(optional) - Specify a comma-separated list of origins that are permitted to access the resource template.

   - Comments(optional) - Enter comments.

6. Click Create Module.

   The ORDS Module Definition page appears.

Parent topic: Managing RESTful Service Modules

### 7.6.4 Editing an ORDS RESTful Service Module

An ORDS RESTful Service Module can have associated resource templates and resource handlers. During the edit process for a particular RESTful Service Module, you can make changes to any of the associated resource templates and resource handlers.

To edit an ORDS RESTful Service Module:

1. On the Workspace home page, click SQL Workshop and then RESTful Services.

   The RESTful Services home page appears.

2. Click the name of the module you want to edit.

   The ORDS Module Definition page appears.

   Note:

   Use the RESTful Service tree on the left pane to view, edit and create resource templates and resource handlers.

3. To edit RESTful Service Module settings, make changes to the fields on the right pane under ORDS Module Definition page.
   - To edit a resource template:

     1. Select the resource template you want to edit on the RESTful Service tree on the left panel. The resource template options appear on the right panel.

     2. Make your changes.

     3. Click Apply Changes.

   - To edit a resource handler:

     1. Select the resource handler you want to edit on the RESTful Service tree on the left panel. The resource handler options appear on the right panel.

     2. Make your changes.

     3. Click Apply Changes.

4. Click Apply Changes.

See Also:

- Creating an ORDS RESTful Service Module

- Adding a Resource Template

- Adding a Resource Handler

Parent topic: Managing RESTful Service Modules

### 7.6.5 Deleting an ORDS RESTful Service Module

Deleting an ORDS RESTful service module removes the module along with all resource templates and resource handlers associated with this module.

To delete an ORDS RESTful Service Module:

1. On the Workspace home page, click SQL Workshop and then RESTful Services.

   The RESTful Services home page appears.

2. Click the name of the module you want to delete.

   The ORDS Module Definition page appears.

3. Click Delete.
4. Click OK to confirm.

   The RESTful Services home page appears.

Parent topic: Managing RESTful Service Modules

### 7.6.6 Managing an ORDS RESTful Service Privileges

Privileges to access RESTful Service Modules can be restricted in APEX.

To protect an ORDS RESTful Service Modules by assigning privileges:

1. Create a RESTful Service Privilege.
2. Specify which RESTful Service Modules are protected by this privilege.

   See Also:

   - Managing Users in a Workspace in Oracle APEX Administration Guide

   - Creating an ORDS RESTful Service Privilege

   - Assigning Privileges to an ORDS RESTful Service Modules

   - Editing an RESTful Service Privilege

   - Deleting an ORDS RESTful Service Privilege

Parent topic: Managing RESTful Service Modules

### 7.6.7 Assigning Privileges to an ORDS RESTful Service Modules

Learn how to assign privileges to an ORDS RESTful Service Modules.

You can assign privileges to an ORDS RESTful Service Modules during the creation or editing of an ORDS RESTful Service Privilege, you can specify the module or modules protected by this privilege.

Note:

After a RESTful Service Privilege is deleted, all RESTful Service Modules protected by that privilege are unprotected.

See Also:

- Creating an ORDS RESTful Service Module

- Editing an ORDS RESTful Service Module

- Creating an ORDS RESTful Service Privilege

- Editing an RESTful Service Privilege

- Deleting an ORDS RESTful Service Privilege

Parent topic: Managing RESTful Service Modules

### 7.6.8 Creating an ORDS RESTful Service Privilege

You can create an ORDS RESTful Service Privilege to restrict access to specified users for one or more RESTful Service Modules.

A RESTful Service Privilege can include users belonging to one or more user groups. RESTful Service Modules protected by this privilege display the privilege name for Required Privilege on the RESTful Service Module page.

To create an ORDS RESTful Service Privilege:

1. On the Workspace home page, click SQL Workshop and then RESTful Services.

   The RESTful Services home page appears.

2. Click ORDS Based RESTful Services.

   The ORDS RESTful Services page appears.

3. Under RESTful Data Services tree on the left pane, click Privileges.
4. Click Create Privilege on the right pane.

   The ORDS Privileges Definition page appears.

5. Specify the following in the ORDS Privileges Definition page:
   - Name- Enter the name of the RESTful Service Privilege.
   - Title- Enter the name of the RESTful Service Privilege title.
   - Description- Enter the description of the RESTful Service Privilege.
   - Comments- Enter comments.
   - Roles- Select roles assigned to the privilege.
   - Protected Modules- Use the arrows to select the modules this privilege is assigned to.
   - Protected Resources- Adding a list of protection patterns to the Interactive Grid.
6. Click Create Privilege.

Parent topic: Managing RESTful Service Modules

### 7.6.9 Editing an RESTful Service Privilege

You can modify an ORDS RESTful Service Privilege. Changes to the specified Protected Modules will be reflected in the Required Privilege setting on the RESTful Service Module page for affected modules.

To edit a ORDS RESTful Service Privilege:

1. On the Workspace home page, click SQL Workshop and then RESTful Services.

   The RESTful Services home page appears.

2. Click ORDS Based RESTful Services.

   The ORDS RESTful Services page appears.

3. Under RESTful Data Services tree on the left pane, click Privileges.

   The ORDS Privileges Definition page appears.

4. Make modifications.
5. Click Apply Changes.

Parent topic: Managing RESTful Service Modules

### 7.6.10 Deleting an ORDS RESTful Service Privilege

You can remove an ORDS RESTful Service Privilege. After deleting the privilege, any RESTful Service Modules that were protected by this privilege will be unprotected until reassigned another privilege.

To delete an ORDS RESTful Service Privilege:

1. On the Workspace home page, click SQL Workshop and then RESTful Services.

   The RESTful Services home page appears.

2. Click ORDS Based RESTful Services.

   The ORDS RESTful Services page appears.

3. Under RESTful Data Services tree on the left pane, click Privileges.

   The ORDS Privileges Definition page appears.

4. Click Delete.

Parent topic: Managing RESTful Service Modules

### 7.6.11 Exporting an ORDS RESTful Service Module

An ORDS RESTful Service Module metadata can be exported to a file in SQL script format. The exported file can be imported on the same instance or another compatible Oracle APEX instance.

To export an ORDS RESTful Service module:

1. On the Workspace home page, click SQL Workshop and then RESTful Services.

   The RESTful Services home page appears.

2. Click ORDS Based RESTful Services.

   The ORDS RESTful services page appear.

3. Click Export on the right pane.

   The Export ORDS RESTful Services page appears.

4. For RESTful Service, perform one of the following:

   - To export one module, select the module name.

   - To export all modules, select All Services.

5. Click Export.

   The Opening dialog appears.

6. Select export options.
7. Click OK.

See Also:

Importing an ORDS RESTful Service Module

Parent topic: Managing RESTful Service Modules

### 7.6.12 Importing an ORDS RESTful Service Module

An ORDS RESTful Service Module metadata that has been exported to a file in SQL script format can be imported. The imported module must have been exported on the same instance or another compatible Oracle APEX instance.

Note:

If the imported module contains a ORDS RESTful Service name that exists in this workspace, the existing ORDS RESTful Service is deleted and replaced with the definition from the imported module.

To import an ORDS RESTful Service module:

1. On the Workspace home page, click SQL Workshop and then RESTful Services.

   The RESTful Services home page appears.

2. Click ORDS Based RESTful Services.

   The ORDS RESTful services page appears.

3. Click Import on the right pane.

   The Import ORDS RESTful Services page appears.

4. For Import File, browse to and select the import file.
5. For File Character Set, select the character set used by the import file.
6. Click Import.

   The ORDS RESTful Services page appears with the imported data.

   WARNING:

   An error message appears that the file is of the wrong type, when you export an APEX Based RESTful Services and try to import it into the Import ORDS RESTful Services page.

See Also:

Exporting an ORDS RESTful Service Module

Parent topic: Managing RESTful Service Modules

### 7.6.13 Generating a Swagger Document

Learn how to generate a Swagger document.

Generate a swagger document by setting up the URL at the Oracle APEX instance level. This allows you to define the URL for a Swagger server. Oracle APEX sends generated swagger document to the server for rendering when the URL is setup at the instance level. Oracle APEX just displays the JSON generated for Swagger when the URL is not specified.

To generate a Swagger a document:

1. On the Workspace home page, click SQL Workshop and then RESTful Services.

   The RESTful Services home page appears.

2. Click ORDS Based RESTful Services.

   The ORDS RESTful services page appears.

3. Select the module for which you want to generate Swagger document.
4. Click Generate Swagger Doc on the left pane.
   - If a Swagger UI URL is defined at the instance level, then Oracle APEX calls the URL and pass the ORDS Swagger Doc URL to it. Opens in a new browser tab and the swagger documentation appears .
   - If the Swagger UI is not defined, Oracle APEX simply calls ORDS to produce the Swagger documentation JSON file and present that in a new tab.

Parent topic: Managing RESTful Service Modules