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

12.1 Basic Setup to Enable ORDS Database API

This section explains the basic setup to enable the ORDS database API.

To enable the ORDS database API, set the database.api.enabled property to true and then restart ORDS:
java -jar ords.war set-property database.api.enabled true
To access the ORDS database API, you can use one of the following available authentication methods available:
  • Database authentication using database username and password
  • Through a mid-tier user with the SQL Administrator, or System Administrator role


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.
To enable database authentication, you must set the 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

For the database authentication, ensure that the administrator schema is ORDS enabled and is granted with the DBA role in an 11gR2 environment or the PDB_DBA role for 12c and higher versions of the database before the schema is used to execute the database API queries in the database. This is done for each non-CDB or pluggable database in which you want to use the database. For more information, refer to "REST-Enabling the Oracle Database Schema" and "ORDS_ADMIN.ENABLE_SCHEMA" sections.


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.
For example, to use PDBADMIN schema, in the SALESPDB database for ORDS Database API services, use the following commands in the database.
sqlplus system@SALESPDB

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.

12.2 Advanced Setup to Enable the ORDS Database API

This section describes the configuration options for using ORDS database API with various database topologies.


Disabling management services: When the value of database.api.management.services.disabled property is set to true, the following ORDS Database API services are disabled:
  • DBCA Templates: GET
  • Oracle Home Environment: GET
  • PDB Lifecycle: DELETE, GET, POST
  • Open Service Broker- DELETE, GET and PUT

12.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:

  1. Create the CDB administrator user and grant the SYSDBA privilege. In this example, the user is called C##DBAPI_CDB_ADMIN. However, any suitable common user name can be used.
  2. Set the db.cdb.adminUser and db.cdb.adminUser.password properties for the connection pool.
    echo db.cdb.adminUser=C##DBAPI_CDB_ADMIN as SYSDBA > cdbAdmin.properties
    echo db.cdb.adminUser.password=<PASSWORD> >> cdbAdmin.properties
    java -jar ords.war set-properties --conf apex_pu cdbAdmin.properties
    rm cdbAdmin.properties

The ORDS role, SQL Administrator must be used to access the https://<server>/ords/_/db-api/stable/database/pdbs/ services.

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

12.3 Creating a Default Administrator

This section describes how to create and use the default administrator user for the non-CDB or PDB connections.

The ORDS database API service operations are not schema specific. By configuring the default administrator credentials, 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.


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:

  1. Create the default administrator user and grant the DBA role. In this example, the user is called C##_DBAPI_DEFAULT_ADMIN. However, any suitable common user name can be used as shown in the following code snippet:
  2. Set the db.adminUser and db.adminUser.password properties for the connection pool as shown in the following code snipet:
    echo db.adminUser=C##_DBAPI_PDB_ADMIN > pdbAdmin.properties
        echo db.adminUser.password=<PASSWORD> >> pdbAdmin.properties
        java -jar ords.war set-properties --conf apex_pu pdbAdmin.properties
        rm pdbAdmin.properties

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.

12.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:


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

12.5 Configuration of the Database API

This section describes how to configure and use ORDS Database API with Open Service Broker API compatible platforms.

ORDS Database API provides a service broker for each registered connection pool. Service brokers compliant with the Open Service Broker API specification allow platforms to provision a new instance of a service. The ORDS Database API provides the service of creating a user in the connection pool. A database user can be created with specific roles, privileges, and ORDS enable the schema when they are created.

To disable the Open Service Broker services available for a specific pool:

  1. Set the feature property, openservicebroker.exclude to true and specify the pool name as shown in the following code snippet:

    java -jar ords.war set-property --conf <pool name> feature.openservicebroker.exclude true

  2. Restart ORDS.

The service broker URL to register with your Open Service Broker compliant platform depends on how the pool is registered with ORDS and the format is as shown in the following code snippet:

https://<server>/ords/<my database>/<my admin schema>/_/db-api/stable/openservicebroker/

Using the SALESPDB example with PDBADMIN as an ORDS enabled schema, the URL is: https://<server>/ords/salespdb/pdbadmin/_/db-api/stable/openservicebroker/

Oracle recommends to use HTTPS with Open Service Broker endpoints. The process of registering a service broker differs depending on the platform.