4 The REST Pages
The REST pages enable you to develop and protect ORDS (Oracle REST Data Services) based RESTful web services for your database.
To navigate to the REST pages, do either of the following:
-
In the Launchpad page, select the Development tab and click REST.
-
Click Selector
to display the navigation menu. Under Development, select REST.
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 theemp
resource withid
of101
) and will also match/objects/emp/
(matches a request for theemp
resource, because the :id
parameter is annotated with the?
modifier, which indicates that theid
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 withemployees/
, such asemployees/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), andDELETE
(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, select the Development tab and click REST.
-
Click Selector
to 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.
Use Export Schema to copy or download all the roles, privileges, modules, REST-enabled objects, and OAuth clients defined in the schema.
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![context menu icon context menu icon](img/actions.jpg)
See Also:
Accessing Database Actions4.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:
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:
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 toolbar search toolbar](img/search_toolbar.png)
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.