Teaching How to Provision an Oracle Database (Cloud Service) Environment Using REST APIs…

We just covered in previous blogs how to provision environments with components such as: Database Cloud Service, Java Cloud Service, SOA Cloud Service (SOA, OSB, SOA & OSB, API Manager), etc. via the various Cloud Services Console web pages.

In this section I am going to demonstrate how to provision the same type of environments, this time a DB CS environment using REST APIs. REST APIs are very well documented for the vast portfolio of Oracle Cloud Services. For more information refer to http://docs.oracle.com/cloud

Notice that being able to script, version and test the creation of environments via REST APIs, can facilitate the life cycle of not only software, but also environments, which is a crucial aspect in DevOps.

For more information specifically about the provisioning of DB CS environment via a REST API, refer to the official Oracle documentation at https://docs.oracle.com/cloud/latest/dbcs_dbaas/CSDBR/rest-endpoints.html

What you need to know:

  • The Provisioning of DB CS environment is via a POST on /bdcs/api/v1.1/instances/{identityDomain} – Where identityDomain is the name of the identity domain where you are willing to provision your environment.
  • The REST API will be accompanied with a JSON payload, which will be referenced from within the API at the moment of invoking the API.
  • Using CURL, this is the structure of the REST API to create a DB instance:
curl –include –request POST \

–cacert ~/[cacert.pem] \



–header “Content-Type:application/json” \

–data @[REQUEST_BODY.json] \



[cacert.pem] = Specifies the location of the CA certificate bundle on the local machine. You can download an SSL CA certificate bundle from http://curl.haxx.se/docs/caextract.html or provide your own. For information about CA certificate verification using cURL, see: http://curl.haxx.se/docs/sslcerts.html

[DBAAS_ADMIN_GOES_HERE] = Your DB Environment Admin name, e.g. cloud.admin

[PASSWORD_GOES_HERE] = Your DB Environment Admin password

[IDENTITY_DOMAIN_GOES_HERE] = Your OPC identity domain where you want to provision the DB environment.

[REQUEST_BODY.json] = This is the JSON file that contains the configurations for your new DB Instance.

[REGION_PREFIX] = dbaas for United States region, dbcs.emea for EMEA region.

For example, in my case I ended up doing something like the snippet below (update the fields in blue

curl –include –request POST \

–cacert /home/citurria/cri/jcs/cacert.pem \

–user cloud.admin:Welcome1# \

–header “X-ID-TENANT-NAME:gse00000536” \

–header “Content-Type:application/json” \

–data @devDBInstanceBody.json \


  • Notice that there is a mention for a “devDBInstanceBody.json” file. This is the Payload that you need to invoke as part of the REST API call payload which configures the environment depending on your needs. Make sure to modify the values depending on your needs.

Note in blue
the values that you will need to update according to your own environment…


“description”: “My Dev DB Cloud Service Instance”,

“edition”: “EE_HP”,

“level”: “PAAS”,

“serviceName”: “my-db12c-xp-si”,

“shape”: “oc3”,

“subscriptionType”: “MONTHLY”,

“version”: “”,

“vmPublicKeyText”: “ssh-rsa AAAAB3Nza… “,

“parameters”: [


“type”: “db”,

“usableStorage”: “15”,

“adminPassword”: “Welcome1#“,

“sid”: “ORCL”,

“pdbName”: “MYPDB”,

“failoverDatabase”: “no”,

“backupDestination”: “BOTH”,

“cloudStorageContainer”: “Storage-gse00000536\/dbcsbackups“,

“cloudStorageUser”: “cloud.admin“,

“cloudStoragePwd”: “Welcome1#




Notice that I have previously created my Storage. For this case, I am assuming a storage called “Storage-gse00000536\/dbcsbackups” under the following configuration using CloudBerry:

If you still have not created one or require more information, please refer to this other blog:


Things that you need to be aware from this JSON file:

  • Make sure it is located on the same directory from which you are running the curl command. Otherwise modify the path in the curl command.
  • Edition: Database edition for the service instance:
    • SE: Standard Edition
    • EE: Enterprise Edition
    • EE_HP: Enterprise Edition – High Performance
    • EE_EP: Enterprise Edition – Extreme Performance
  • Level: Service level for the service instance; one of:
    • PAAS: The Oracle Database Cloud Service service level
    • BASIC: The Oracle Database Cloud Service – Virtual Image service level
  • ServiceName: Name of Database Cloud Service instance. The service name:
    • Must not exceed 50 characters.
    • Must start with a letter.
    • Must contain only letters, numbers, or hyphens.
    • Must not contain any other special characters.
    • Must be unique within the identity domain.
  • Shape: Desired compute shape. A shape defines the number of Oracle Compute Units (OCPUs) and amount of memory (RAM). Valid shapes include:
    • oc3: 1 OCPU, 7.5 GB memory
    • oc4: 2 OCPUs, 15 GB memory
    • oc5: 4 OCPUs, 30 GB memory
    • oc6: 8 OCPUs, 15 GB memory
    • oc1m: 1 OCPU, 15 GB memory
    • oc2m: 2 OCPUs, 30 GB memory
    • oc3m: 4 OCPUs, 60 GB memory
    • oc4m: 8 OCPUs, 120 GB memory
  • SubscriptionType: Billing unit. Valid values are:
    • HOURLY: Pay only for the number of hours used during your billing period. This is the default.
    • MONTHLY: Pay one price for the full month irrespective of the number of hours used.
  • Version: Oracle Database software version; one of:,, or
  • vmnPublicKeyText: Public key for the secure shell (SSH). This key will be used for authentication when connecting to the Database Cloud Service instance using an SSH client. You generate an SSH public-private key pair using a standard SSH key generation tool. See: https://solutionsanz.blog/2016/11/22/teaching-how-to-create-ssh-keys-for-oracle-public-cloud-opc-access/ for more information.
  • vmPublicKeyText: Substitute AAAAB3Nza… with your entire Public SSH Key (after “ssh-rsa “) – Make sure to finish with a

Refer to the DB CS API documentation for more fine-grain level configuration.

  • Note: When running the curl command. If you get an error, you can add a –v flag to make it verbose.
  • Otherwise, validate that you get a successful “202 Accepted” response

  • Now go to the DB CS Console and validate that the SOA Environment is being provisioned.

You can also query a simple REST API that shows all DB CS Instances, IN this case, it will show you that this DB Instance is to be provisioned:

curl –include –request GET \

–cacert /home/citurria/cri/jcs/cacert.pem \

–user cloud.admin:Welcome1# \

–header “X-ID-TENANT-NAME:gse00000536” \


After some time it will be fully provisioned and ready to go. Pretty easy, huh?

If you have any question, please feel free to contact any of the authors of solutionsanz.blog

Thanks for your time!


Author: Carlos Rodriguez Iturria

I am extremely passionate about people, technology and the most effective ways to connect the two by sharing my knowledge and experience. Working collaboratively with customers and partners inspires and excites me, especially when the outcome is noticeable valuable to a business and results in true innovation. I enjoy learning and teaching, as I recognise that this is a critical aspect of remaining at the forefront of technology in the modern era. Over the past 10+ years, I have developed and defined solutions that are reliable, secure and scalable, working closely with a diverse range of stakeholders. I enjoy leading engagements and am very active in the technical communities – both internal and external. I have stood out as a noticeable mentor running technology events across major cities in Australia and New Zealand, including various technology areas such as, Enterprise Integrations, API Management, Cloud Integration, IaaS and PaaS adoption, DevOps, Continuous Integration, Continuous Automation among others. In recent years, I have shaped my role and directed my capabilities towards educating and architecting benefits for customers using Oracle and AWS Cloud technologies. I get especially excited when I am able to position both as a way to exceed my customers’ expectations. I hold a bachelor degree in Computer Science and certifications in Oracle and AWS Solutions Architecture.

One thought on “Teaching How to Provision an Oracle Database (Cloud Service) Environment Using REST APIs…”

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: