6.6 Managing RESTful Service Modules

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
    Learn how to create a Sample RESTful Service Module.
  • Creating a RESTful Service Module
    Learn how to create a RESTful Service Module.
  • Editing a RESTful Service Module
    A 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 a RESTful Service Module
    Deleting a RESTful service module removes the module along with all resource templates and resource handlers associated with this module.
  • Managing RESTful Service Privileges
    Privileges to access RESTful Service Modules can be restricted to Application Express users that belong to an Application Express user group.
  • Assigning Privileges to RESTful Service Modules
    Learn how to assign privileges to RESTful Service Modules.
  • Creating a RESTful Service Privilege
    You can create a RESTful Service Privilege to restrict access to specified users for one or more RESTful Service Modules.
  • Editing a RESTful Service Privilege
    You can modify a 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 a RESTful Service Privilege
    You can remove a 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 a RESTful Service Module
    RESTful Service Module meta data can be exported to a file in SQL script format. The exported file can be imported on the same instance or another compatible instance of Application Express.
  • Importing a RESTful Service Module
    RESTful Service Module meta data 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 instance of Application Express.

6.6.1 Installing a Sample RESTful Service Module

Learn how to create a Sample RESTful Service Module.

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 Install a Sample RESTful Service.
  3. Fill in the appropriate fields and select the appropriate options. Mandatory fields are marked with a red asterisk (*). To learn more about a specific option, see the field-level help.
  4. Specify the following RESTful Service Module settings:

    • Name (required) - Specify the RESTful Service Module name.

    • URI Prefix - Specify the URI prefix.

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

    • Status - Select Published to make this service available for use, otherwise select Not Published.

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

    • Required Privilege - Select the user privilege required to access this service module.

  5. To add a resource template to this module, specify the following under Add a Resource Template:

    • URI Template - Enter the URI template to identify your Uniform Resource Identifier. A URI template is simple syntax for describing URIs, for example:

      example/{id}

    • Priority - Specify the resource template's evaluation order. Higher numbers are evaluated first.

    • Entity Tag - Specify how the ETag HTTP Header for the resource is generated. See field-level help for further details.

    • Entity Tag Query - Specify the SQL SELECT statement that returns one column and one row that is to be used to generate a custom entity tag. This option is only visible when the user selects Query for the Entity Tag.

  6. If you want to add a resource handler to the resource template, specify the following under Add a Resource Handler:

    • Method - Specify the HTTP method to be used for the resource handler. Options include: GET, DELETE, POST, PUT. See field-level help for further details.

    • Source Type - Select the source implementation for the selected HTTP method. Options include: Query, Query One Row, PL/SQL, Feed, Media Resource.

    • Format - Define how results are returned. Options include: JSON, CSV.

    • Source - Specify the SQL query or PL/SQL block responsible for handling the selected HTTP method.

    Note:

    To define additional resource handlers, complete the Resource Handler Creation wizard and then edit the created resource handler.

  7. Click Create.

    The RESTful Service Module page appears.

6.6.2 Creating a RESTful Service Module

Learn how to create a RESTful Service Module.

To create a RESTful Service Module:

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

    The RESTful Services home page appears.

  2. Click Create.
  3. Fill in the appropriate fields and select the appropriate options. Mandatory fields are marked with a red asterisk (*). To learn more about a specific option, see the field-level help.
  4. Specify the following RESTful Service Module settings:

    • Name (required) - Specify the RESTful Service Module name.

    • URI Prefix - Specify the URI prefix.

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

    • Status - Select Published to make this service available for use, otherwise select Not Published.

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

    • Required Privilege - Select the user privilege required to access this service module.

  5. To add a resource template to this module, specify the following under Add a Resource Template:

    • URI Template - Enter the URI template to identify your Uniform Resource Identifier. A URI template is simple syntax for describing URIs, for example:

      example/{id}

    • Priority - Specify the resource template's evaluation order. Higher numbers are evaluated first.

    • Entity Tag - Specify how the ETag HTTP Header for the resource is generated. See field-level help for further details.

    • Entity Tag Query - Specify the SQL SELECT statement that returns one column and one row that is to be used to generate a custom entity tag. This option is only visible when the user selects Query for the Entity Tag.

  6. If you want to add a resource handler to the resource template, specify the following under Add a Resource Handler:

    • Method - Specify the HTTP method to be used for the resource handler. Options include: GET, DELETE, POST, PUT. See field-level help for further details.

    • Source Type - Select the source implementation for the selected HTTP method. Options include: Query, Query One Row, PL/SQL, Feed, Media Resource.

    • Format - Define how results are returned. Options include: JSON, CSV.

    • Source - Specify the SQL query or PL/SQL block responsible for handling the selected HTTP method.

    Note:

    To define additional resource handlers, complete the Resource Handler Creation wizard and then edit the created resource handler.

  7. Click Create.

    The RESTful Service Module page appears.

6.6.3 Editing a RESTful Service Module

A 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 a 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 RESTful Service Module edit 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 RESTful Services Module.

  4. 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.

  5. To edit a resource handler:

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

    2. Make your changes.

    3. Click Apply Changes.

  6. Click Apply Changes.

See Also:

6.6.4 Deleting a RESTful Service Module

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

To delete a 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 RESTful Service Module page appears.

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

    The RESTful Services home page appears.

6.6.5 Managing RESTful Service Privileges

Privileges to access RESTful Service Modules can be restricted to Application Express users that belong to an Application Express user group.

To protect RESTful Service Modules by assigning RESTful Service Privileges:

  1. Define an Application Express user group using Application Express Administration.
  2. Create a RESTful Service Privilege based on one or more user groups.
  3. Specify which RESTful Service Modules are protected by this privilege.

6.6.6 Assigning Privileges to RESTful Service Modules

Learn how to assign privileges to RESTful Service Modules.

There are a couple of ways to assign privileges to RESTful Service Modules:

  • During the creation or editing of a RESTful Service Module, you can specify the privilege for the module.

  • During the creation or editing of a 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:

6.6.7 Creating a RESTful Service Privilege

You can create a 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 a RESTful Service Privilege:

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

    The RESTful Services home page appears.

  2. Under Tasks, click the RESTful Services Privileges link.

    The RESTful Service Privileges page appears.

  3. Click Create.

    The RESTful Service Privileges Details page appears.

  4. For Name, enter a name to identify the privilege.
  5. For Label, enter a label value to identify the privilege.
  6. For Assigned Groups, select the user groups this privilege is assigned to.
  7. For Description, enter a description of this privilege.
  8. For Protected Modules, use the arrows to select the modules this privilege is assigned to.
  9. Click Create.

    The RESTful Service Privileges page appears.

  10. To verify the privilege has been assigned to the appropriate modules:

    1. Click RESTful Services in the breadcrumb.

      The RESTful Services page appears.

    2. Click the protected RESTful Service Module.

      The RESTful Service Module page appears.

    3. Make sure the Required Privilege displays the created RESTful Service Privilege.

    4. Repeat these verification steps to ensure all modules assigned to this privilege are protected.

6.6.8 Editing a RESTful Service Privilege

You can modify a 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 RESTful Service Privilege:

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

    The RESTful Services home page appears.

  2. Under Tasks, click the RESTful Services Privileges link.

    The RESTful Service Privileges page appears.

  3. Click a RESTful Service Privilege.

    The RESTful Service Privileges Details page appears.

  4. Make modifications.
  5. Click Apply Changes.

    The RESTful Service Privileges page appears.

6.6.9 Deleting a RESTful Service Privilege

You can remove a 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 a RESTful Service Privilege:

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

    The RESTful Services home page appears.

  2. Under Tasks, click the RESTful Services Privileges link.

    The RESTful Service Privileges page appears.

  3. Click a RESTful Service Privilege.

    The RESTful Service Privileges Details page appears.

  4. Click Delete.

    The RESTful Service Privileges page appears.

6.6.10 Exporting a RESTful Service Module

RESTful Service Module meta data can be exported to a file in SQL script format. The exported file can be imported on the same instance or another compatible instance of Application Express.

To export a RESTful Service module:

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

    The RESTful Services home page appears.

  2. Under Tasks, click the Export link.

    The Export RESTful Services page appears.

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

    • To export one module, select the module name.

    • To export all modules, select All Services.

  4. Click Export.

    The Opening dialog appears.

  5. Select export options.
  6. Click OK.

See Also:

"Importing a RESTful Service Module"

6.6.11 Importing a RESTful Service Module

RESTful Service Module meta data 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 instance of Application Express.

Note:

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

To import a RESTful Service module:

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

    The RESTful Services home page appears.

  2. Under Tasks, click the Import link.

    The Import RESTful Services page appears.

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

    The RESTful Services page appears.

See Also:

"Exporting a RESTful Service Module."