The REST Pages

4.1 About RESTful Web Services

Representational State Transfer (REST) is a style of software architecture for distributed hypermedia systems such as the World Wide Web. A service is described as RESTful when it conforms to the tenets of REST.

A RESTful service has the following characteristics:

Data is modeled as a set of resources. Resources are identified by URIs.
A small, uniform set of operations are used to manipulate resources (for example, GET, POST, PUT, DELETE).
A resource can have multiple representations (for example, a blog might have an HTML representation and a RSS representation).
Services are stateless and because it is likely that the client will want to access related resources, these should be identified in the representation returned, typically by providing hypertext links.

4.2 RESTful Services Terminology

The following are some major terms related to RESTful services.

RESTful service: An HTTP web service that conforms to the tenets of the RESTful architectural style.
Resource module: An organizational unit that is used to group related resource templates.
Resource template: An individual RESTful service that is able to service requests for some set of URIs (Universal Resource Identifiers). The set of URIs is defined by the URI pattern of the Resource Template
URI pattern: A pattern for the resource template. Can be either a route pattern or a URI template, although you are encouraged to use route patterns.
- Route pattern: A pattern that focuses on decomposing the path portion of a URI into its component parts. 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).
- URI template: A simple grammar that defines the specific patterns of URIs that a given resource template can handle. For example, the pattern employees/{id} will match any URI whose path begins with employees/, such as employees/2560.
Resource handler: Provides the logic required to service a specific HTTP method for a specific resource template. For example, the logic of the GET HTTP method for the preceding resource template might be:
```
select empno, ename, dept from emp where empno = :id
```
HTTP operation: HTTP (HyperText Transport Protocol) defines the standard methods that are supported in Oracle REST Data Services for building RESTful services: GET (retrieve the resource contents), POST (store a new resource), PUT (update an existing resource), and DELETE (remove a resource).

4.3 About the Overview Page

The Overview page provides an overview of the activity in the REST pages.

To navigate to the Overview page, do either of the following:

In the Launchpad page, click REST.
Click Selectorto display the navigation menu. Under Development, select REST.

You can navigate to pages within REST by using the menu in the header: Overview, Modules, AutoREST and Security.

The Overview page consists of three sections.

Objects

Displays the total number of resource modules, schema objects with REST access, roles, privileges, and OAuth clients created. Click the respective card to navigate to the corresponding pages for modules, roles, privileges and OAuth clients.

In the REST pages, the term "object" is used to refer to a module, template, handler, role, privilege, or OAuth Client.

Security

Metadata Catalog: Displays whether access to the ORDS metadata catalog of the schema is protected. The metadata catalog lists all the services in the schema. The user authorization for the metadata catalog is provided at the time of enabling user access.

Modules: Displays the number of modules that are published out of the total modules created.

Module Security: Displays the number of modules that are protected by a privilege out of the total modules created. A partially secured privilege is where the module is protected both by a privilege and a pattern.

Recent Objects

Displays recently updated or created objects. Each entry has a context menu available at the end of the row. Click Actions

to access options such as Edit and Delete.

4.4 About the AutoREST Page

Use the Automatic Enabling of Schema Objects for REST Access (AutoREST) feature to enable REST access for database objects in the current schema.

Enabling REST access for a schema object such as table, view, function, procedure and package allows it to be accessed through RESTful services. See AutoREST in Oracle REST Data Services Developer's Guide

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

The AutoREST page consists of three parts:

Objects: Displays the number of REST-enabled schema objects that are protected and require authorization out of the total number of schema objects enabled in the schema.
AutoREST: Displays the number of tables and views, packages, procedures and functions that are REST enabled in the schema. Click a card to see the corresponding objects listed below.
The bottom part of the page lists schema objects based on the selection made in AutoREST. You can view these objects in card view or grid view. The actions available in the context menu for an object are:
- Edit: Edit the Object Alias or Require Authentication fields for the REST enabled object. For a description of the fields, see Enabling REST Access for a Database Object
- Disable: Disable REST access for the object. See Disabling REST Access for a Database Object
- Get Curl: Generate cURL calls for a REST enabled object. See Generating cURL Requests for a REST-Enabled Database Object
- Export OpenAPI: Export the object as JSON Open API code.
- OpenAPI View: Display the object as a Swagger UI implementation. You can view and execute the handlers, pass parameters to the handlers, and copy or download the responses.

4.4.1 Enabling REST Access for a Database Object

You can enable REST access for a table, view, materialized view, function, procedure or package.

To REST enable a schema object:

In the Navigator tab in the SQL page, right-click an object and select REST, then select Enable.
Enter the following fields:
- Object Alias: Enter another name for the object. For security purposes, it is recommended to use a different name than the actual object name.
- Require Authentication: Select this option to secure the REST endpoint.
- Authorization Role and Authorization Privilege: These fields are automatically pre-filled.
Click Enable.

A REST-enabled object is indicated by a REST Enabled icon in the Navigator tab.

4.4.2 Disabling REST Access for a Database Object

This section describes how to disable REST access for a database object.

In the SQL page, in the Navigator tab, right-click the database object that is REST enabled and select Disable.
You see a prompt to confirm. Click OK.

4.4.3 Generating cURL Requests for a REST-Enabled Database Object

For a REST-enabled database object, you can generate sample cURL calls for GET, POST, PUT and DELETE requests for the selected object. Use the Copy to Clipboard icon to copy the cURL code.

To view the cURL call for a specific method for the selected object:

In the SQL page, in the Navigator tab, right-click the REST-enabled object, select REST and then select cURL command.
Select the HTTP method from the left pane, enter values if required and click Next to see the cURL command.

For more information about each HTTP method, see Examples in Oracle REST Data Services.

4.5 About the REST Search Toolbar

This section describes the various options available on the search toolbar in the REST pages. The options selected are saved for your session.

Search: Performs a search based on the text entered in the field. This field is not case sensitive. When you start typing in the Search field, the icon appears. If you click the icon, the text that you typed is deleted and you can re-enter text again.

Filter by: Performs a search based on the filters selected. In the Filter by drop down, first select the column to apply the filter on, and then select the values to search for in that column.

Sort By: Sorts the data in ascending or descending based on the columns selected. The columns can be turned on or off. Reset restores the columns to the original state.The sort criteria selected is shown in the upper right corner as Sort By.

Page Size. First Page, Previous page, Next Page: Only displayed in the Card View. Enables you to select page size, and move between pages.

Reload: Refreshes the information on the page.

There are two views available:

Open Card View: This is the default display view. Information is displayed for each object in a card format. Each card displays associated attributes for the object along with the context menu, which list the actions available for the object.

Open Grid View: Displays the information for each object in a single row of a table. The last column in each row contains the context menu icon, which shows the actions available for the object.