11 Enabling ORDS Database API
This section describes how to enable the Oracle REST Data Services (ORDS) Database API.
ORDS database API is a database management and monitoring REST API embedded into Oracle REST Data Services. Depending on the database version and configuration, ORDS database API provides services such as manage pluggable databases, export data and review database performance. By default, the ORDS database API feature is disabled when you install ORDS for the first time.
11.1 Basic Setup to Enable ORDS Database API
This section explains the basic setup to enable the ORDS database API.
database.api.enabled
property to true
and then restart
ORDS:java -jar ords.war set-property database.api.enabled true
- Database authentication using database username and password
- Through a mid-tier user with the SQL Administrator, or System Administrator role
Note:
There are certain endpoints that are accessible only by certain roles. The REST APIs for Oracle Database documentation provides information on which roles can access each endpoint.restEnabledSql.active
property to true
as shown in
the following code snippet and then restart ORDS:
java -jar ords.war set-property restEnabledSql.active
true
Note:
In the following example, sqlplus command-line utility is used to connect to the SALESPDB database as the system user to configure the PDBADMIN user in that database. The mechanism to connect to the database and performing the steps will differ depending on your environment settings.sqlplus system@SALESPDB
GRANT PDB_DBA TO PDBADMIN;
BEGIN
ORDS_ADMIN.ENABLE_SCHEMA(p_schema => 'PDBADMIN');
END;
/
The PDBADMIN user is now ready to use the ORDS database API services.
To list the tables in the database, send a GET
request to
https://<server>/ords/salespdb/pdbadmin/_/db-api/stable/database/objects/tables/
On request, you must provide the username and password. If you are using a browser, ORDS provides a link to login and authenticate the request. Once you are authenticated, your browser will have an access cookie, and you do not have to specify the user credentials until that cookie expires.
The same service can be accessed through command line utilities such as curl:
curl --user pdbadmin:password
https://<server>/ords/salespdb/pdbadmin/_/db-api/stable/database/objects/tables/
An OpenAPI V3 document that describes the available ORDS database API
services can be accessed at https://<server>/ords/<my
database>/<my admin
schema>/_/db-api/stable/metadata-catalog/openapi.json
. With the
exception of https://<server>/ords/<my database>/<my admin
schema>/_/db-api/stable/databases/pdbs/
, all other ORDS database API
services are made available.
Related Topics
11.2 Advanced Setup to Enable the ORDS Database API
This section describes the configuration options for using ORDS database API with various database topologies.
11.2.1 Pluggable Database Lifecycle Management
This section describes how to enable the Pluggable Database (PDB) lifecycle management operations. Pluggable Database management is performed in the Container Database (CDB) and includes create, clone, plug, unplug and delete operations.
You cannot have an ORDS enabled schema in the container database. To
perform the PDB lifecycle management operations, the default CDB administrator
credentials, db.cdb.adminUser
and
db.cdb.adminUser.password
must be defined in the connection
pool. In this case, specifying an user schema in the URI is not required.
To define the default CDB administrator credentials, perform the following steps:
The ORDS role, SQL Administrator must be used to access the
https://<server>/ords/_/db-api/stable/database/pdbs/
services.
11.2.2 Disabling PDB Lifecycle Management
This section describes how to disable the PDB lifecycle management services.
You can enable ORDS database API and disable the PDB related services at
https://<server>/ords/_/db-api/stable/databases/pdbs/
.
When the optional CDB administrator credentials are not set, a
HTTP 503 Service Unavailable
response is produced if a user
attempts to access
https://<server>/ords/_/db-api/stable/databases/pdbs/
.
To clearly indicate that the PDB operations are disabled for the ORDS
installation, set the database.api.management.services.disabled
property to true
as shown in the following code snippet and then
restart ORDS:
java -jar ords.war set-property database.api.management.services.disabled true
This will produce a response, HTTP 503 Service
Unavailable
with an explanatory reason.
11.3 Creating a Default Administrator
This section describes how to create and use the default administrator user for the non-CDB or PDB connections.
db.adminUser
and
db.adminUser.password
in the connection pool, you can execute
the corresponding SQL statements as the default administrator user. The ORDS
database API endpoints can be executed using a specified ORDS enabled schema if the
schema has the DBA role. However, it is not necessary to do so when the default
administrator credentials are configured.
Note:
The user credentials must be the same across all the pluggable databases and therefore it is recommended to create the common user in the CDB.To create the default administrator and grant the DBA role, perform the following steps:
A schema is not required to be provided in the URI request.
For example,
https://<server>/ords/salespdb/_/db-api/stable/database/datapump/jobs/
lists all the data pump jobs in the salespdb,
and queries in that
database are executed as the db.adminUser
user.
The ORDS role SQL Administrator
, is required to use the
database API services.
11.4 Configuration of Database API Environment Services
This section describes how to configure ORDS Database API environment services.
Starting with ORDS 19.2 release, on a system with ORDS installed, you can perform the set of environment services operations.
For example, the following endpoint lists all the databases discovered in the Oracle Home:
https://<server>/ords/_/db-api/stable/environment/databases/
You must have the ORDS System Administrator role to use the ORDS database API environment services. The environment services provide information about the database Oracle Home on the host machine and a RESTful interface to the Oracle Database Configuration Assistant to create or delete the databases.
Similar to pluggable database lifecycle management, the environment services can be disabled.
To disable the
environment services, set the
database.api.management.services.disabled
property to
true
as follows and then restart ORDS:
java -jar
ords.war set-property database.api.management.services.disabled
true