Lab 5: Working with REST APIs Oracle's Autonomous Transaction Processing cloud service provides all of the performance of the market-leading Oracle Database in an environment that is tuned and optimized for transaction processing workloads. Oracle Autonomous Transaction Processing ( or ATP ) service provisions in a few minutes and requires very little manual ongoing administration and is therefore ideal for developers to build and test their applications Often times, you would prefer to interact with your cloud services programmatically over REST rather than log into the cloud console and click through screens. Besides, by creating your own deployment and management scripts you can save and reuse your deployments, set gold standards and in fact store entire application infrastructure stacks as version controlled code. The Oracle Cloud Infrastructure APIs are typical REST APIs that use HTTPS requests and responses and support HTTPS and SSL protocol TLS 1.2, the most secure industry standards. Also, All Oracle Cloud Infrastructure API requests must be signed for authentication purposes. To create and sign your API requests, you must 1. Form the HTTPS request (SSL protocol TLS 1.2 is required). 2. Create the signing string, which is based on parts of the request. 3. Create the signature from the signing string, using your private key and the RSA- SHA256 algorithm. 4. Add the resulting signature and other required information to the Authorization header in the request While these seem like a lot of steps and can make your curl statements look sick, they are meant to avoid using username/passwords and are based on the draft-cavage-httpsignatures-08 specification for secure communication over the internet Let's take a look at how to generate REST calls to the Oracle Cloud Infrastructure using a popular scripting language, node.js. While we are using node.js to build some sample calls to create and list Autonomous Database services, you may use similar concepts to build scripts in Python, Golang, Ruby, Perl, Java, C#, bash or even curl if you dare! To make life easier, I've shared a set of modular scripts at this git repo. Download this repository to a local folder. You will also need to generate an ssh key pair in the pem format. Lets do that first. First generate a primary key using this command $ openssl genrsa -aes128 -out ~/oci_api_key.pem 2048 Change permission so only you have access to it $ chmod go-rwx ~/oci_api_key.pem
Then generate a public key using the private key you just created $ openssl rsa -pubout -in ~/oci_api_key.pem -out ~/oci_api_key_public.pem Upload the public key to your OCI account from the console. Once you login to Oracle Cloud Infrastructure, from top left hamburger menu, select Identity --> Users. Pick user from list of user and on the User page, click 'Add API Keys' button. You can then cut and paste your oci_api_key_public.pem key text. Note how the service generates a key Fingerprint. Save the fingerprint some where since you will need it to sign your API requests. Also make note of your user OCID and Tenant OCID besides the key fingerprint as shown below. These three artifacts along with a user s private key make up a unique signature that is used to sign the REST requests. Its extremely important that you do not share this with anyone or expose it over an unencrypted network.
To get started, 1. Make sure you have node.js installed. If not, follow download and installation instructions for your OS at https://nodejs.org/en/download/ 2. In the REST API scripts folder, install node package dependencies using a. $ npm install Now lets take a look at the code you downloaded from the git repository. It consists of, 1. auth.js This module has all the user auth information used to generate the signature and other header information including compartments. You will need to edit this file and change the tenancyid, authuserid, keyfingerprint, privatekeypath and compartments to match your.
Make sure the privatekeypath variable accurately points to the location of your private key file. Compartments are Oracle s way of providing isolation among users of a cloud account. Compartments can be created by users, departments, environment types etc and provide a clear separation among entities that share a single OCI account / tenant. Before you can create objects in your account, you would need to create a compartments and grant access to the user to that compartment by creating a suitable IAM policy. Refer to Oracle s IAM documentation to create and enable compartments. Once finished, update auth.js with the compartment OCIDs 2. regions.js This module lists all the API endpoints for OCI. You do not need to change anything here unless a new service is added or Oracle makes a change to the URLs (which is less likely) 3. headers.js
This module builds API signing keys and generates https headers required for your REST calls depending upon whether it s a GET, PUT, POST or DELETE call. You do not need to modify anything here. It also has an optional getuser method used in every REST call to get user info. from the Identity and Access Management service. You may use that example to generate other IAM REST calls 4. createautonomousdatabase.js, listautonomousdatabase.js, createvcn.js, getautonomousdatabase.js, deleteautonomousdatabase.js These are the scripts you would need to run. Make sure the variables in each of these scripts are set right before you run them. For eg, in the createautonomousdatabase.js script, replace compartmentid, displayname, dbname, adminpassword, cpucorecount and datastorageintbs to match your requirements. Run these scripts as, $ node <filename>.js Here s an example output of the listautonomousdatabase.js call
Explore the various scripts provided and build your own using the Oracle REST API documentation. You may build similar scripts using python, Java, golang, Perl, C#, bash and Curl.