REST APIs for Oracle Clusterware

J REST APIs for Oracle Clusterware

This appendix describes the REST application programming interfaces (APIs) for Oracle Clusterware.

The following topics are discussed:

About REST APIs for Oracle Clusterware

About REST APIs for Oracle Clusterware

The REST application programming interfaces (APIs) for Oracle Clusterware enable you to remotely execute commands on your cluster, whether in the Oracle Cloud, at remote physical locations, or locally provisioned. With the remote execution of REST interface commands, you are able to retrieve information about that execution, including output, error codes, and execution duration. In some cases a command generates a file as output. In these cases, the REST interface also provides a Uniform Resource Identifier (URI) through which the file can be retrieved.

The REST interface provides secure support for Oracle Clusterware CLUVFY, CRSCTL, and SRVCTL command line interfaces (CLIs).

Note:

The REST APIs for Oracle Clusterware are not supported in Windows environments.

Getting Started with REST APIs for Oracle Clusterware

REST APIs for Oracle Clusterware require that the CDP Cross Cluster Domain Protocol (CDP) daemon is running on all of the SCAN VIPs of the cluster. REST endpoints exist for you to execute CLIs as asynchronous jobs. You can access the output of a command from a REST endpoint at later point of time, and get return codes and execution time.

To make the REST APIs secure by default, all requests that are not from IP addresses of nodes in the cluster are rejected. The CDP daemon monitors the nodes in the cluster and rejects any request to the CLI endpoint that do not match one of the IPs. To support the ability to make requests from outside the cluster, you can run the srvctl modify cdp command to provide a list of IPs or networks in CIDR format.

To change the admin password, run the following commands.

$ srvctl stop cdp
$ echo "myAdminPasswd" > /tmp/a
$ srvctl modify cdp -passfile_admin /tmp/a
...
$ rm /tmp/a

To enable connections from outside the cluster, run the following commands.

$ srvctl start cdp
$ srvctl modify cdp -allow "ip/network1,ip/network2,.."

You can view the configuration information with the following command:

$ srvctl config cdp

The password is not visible when you display the configuration information.

See Also:

Using CLUVFY Commands with REST APIs

Noninteractive Cluster Verification Utility commands (CLUVFY), which apply to Cluster Ready Services (CRS) post-installation, can be issued using the REST interface. If the issued command is not supported over the REST interface, then the CLUVFY command reports the following error as a response to the REST call.

PRVP-1070 "cluvfy command with the arguments \"{0}\" not supported through REST API call. \n[ Unsupported arguments = \"{1}\" ]"
*Cause: cluvfy command was invoked with the indicated arguments which are not supported through a REST API call.
*Action: Retry the command omitting the unsupported arguments.

REST Endpoints

Delete a Specified Job

Method: Delete

Path: /grid/cmd/v1/cmd/jobs/jobId
Execute a CLI

Method: Post

Path: /grid/cmd/v1/cmd/exec
Return a List of the Job Resources

Method: Get

Path: /grid/cmd/v1/cmd/jobs
Return the Common Resource

Method: Get

Path: /grid/cmd/v1/cmd
Return the Status of the Current Job

Method: Get

Path: /grid/cmd/v1/cmd/jobs/jobId

Examples

The following are some examples of the use of REST APIs for Oracle Clusterware.

Example J-1 Get the list of all homes

 curl -k -X GET https://scan-name:port/grid/cmd/v1/cmd/ --user admin:myAdminPasswd

Example J-2 Create a job (crsctl) and monitor the status

curl -k -X POST \
    https://scan-name:port/grid/cmd/v1/cmd/exec \
    '-H "accept: text/plain,text/javascript,application/json"' \
    '-H "content-type: application/vnd.oracle.resource+json;type=singular"' \
     --user admin:myAdminPasswd \
    '-d  {"command" : ["crsctl", "stat", "res", "-t"], "runAsUser":"osUser", "userPassword":"osPasswd"}'

curl -k -X GET https://scan-name:port/grid/cmd/v1/cmd/jobs/myJobId --user admin:myAdminPasswd

Example J-3 Create a job (srvctl) and monitor the status

curl -k -X POST \
    https://scan-name:port/grid/cmd/v1/cmd/exec  \
    '-H "accept: text/plain,text/javascript,application/json"' \
    '-H "content-type: application/vnd.oracle.resource+json;type=singular"' \
     --user admin:myAdminPasswd \
    '-d  {"command" : ["srvctl", "config", "cdp"], "runAsUser" : "osUser", "userPassword" : "osPasswd"}'

curl -k -X GET https://scan-name:port/grid/cmd/v1/cmd/jobs/myJobId --user admin:myAdminPasswd

Example J-4 Monitor the status, get the job output, and get the CVU job output file

curl -k -X POST \
    https://scan-name:port/grid/cmd/v1/cmd/exec  \
    '-H "accept: text/plain,text/javascript,application/json"' \
    '-H "content-type: application/vnd.oracle.resource+json;type=singular"' \
     --user admin:myAdminPasswd \
    '-d  {"command" : ["cluvfy", "comp", "healthcheck"], "runAsUser":"osUser", "userPassword":"osPasswd", "jobExpiry":300}'

curl -k -X GET https://scan-name:port/grid/cmd/v1/cmd/jobs/myJobId --user admin:myAdminPasswd 

wget --user admin --password myAdminPassword https://scan-name:port/grid/cmd/v1/cmd/jobs/myJobId/outputFile

Example J-5 Monitor the status of all jobs

curl -k -X GET \
    https://scan-name:port/grid/cmd/v1/cmd/jobs/ --user admin:myAdminPasswd

Example J-6 Delete a job

curl -k -X DELETE \ 
         https://scan-name:port/grid/cmd/v1/cmd/jobs/myJobId --user admin:myAdminPasswd

Example J-7 Verify that a deleted job has been removed

curl -k -X GET \ 
    https://scan-name:port/grid/cmd/v1/cmd/jobs/myJobId --user admin:myAdminPasswd