How to use the OCI Python SDK to make API Calls — #mytechretreat

4 min readMar 22, 2020

Oracle Cloud Infrastructure (OCI) provides a wide array of applications and services that you can play with.

Among the many features and services that OCI provides, there is one I’d like to point out: You can evenly access all of its capabilities through the OCI UI Console, Command Line Interface (CLI), Cloud Shell, SDKs, and REST API depending on your preference or need.

Maybe you’re trying to build some scripts to make your life easier or to automate some of your work, and you’d like to know how to execute API calls against OCI.

In this post, we’ll talk about the OCI Python SDK and how to use it to make API calls.

API Security

Before going straight to the subject, it is important to mention some key information about API security in OCI:

HTTPS and TLS 1.2 is required
All OCI API requests must be signed for authentication purposes
If the client’s clock is skewed more than 5 minutes from the server’s, an HTTP status code 401 will be returned

OCI SDKs

OCI provides 4 SDKs at the time of this article:

SDK for Java
Go SDK
Ruby SDK
Python SDK

You can check the list here.

When you’re building a script for OCI, you have two choices:

Call the REST APIs directly, using cURL or requests or any other method depending on your platform or preferences
Use an SDK if your preferred language is Java, Go, Ruby or Python — mine happens to be Python!

Note: Of course, for creating and managing resources you can use Terraform and Ansible — but this is another subject for another time.

For me, I found it much easier to use the Python SDK in my scripts and I’ll show you why.

Authentication prerequisites

Before using the SDK (the same applies to the CLI and the REST APIs), there are a few prerequisites that need to be done:

Create a user in IAM that will be used in the script, and put that user in at least one IAM group with any desired permissions. This step is optional if you already have a user with the necessary permissions
Generate an API Signing Key
Get the Key’s fingerprint
Note down your OCI tenancy’s OCID and your user’s OCID. Follow these steps if you need help finding them
Upload the public key to your tenancy
Install the Python SDK

SDK configuration

Oracle Cloud Infrastructure SDKs require basic configuration information. You can provide this information by:

Using a configuration file
Declaring a configuration at runtime

The configuration contains some basic information needed for authentication:

User OCID
API Key Fingerprint
Full path to the API signing key
Passphrase for the key, if the key has one
Tenancy OCID
OCI Region name

Configuration File

config file example:

As you can see in the example, there are two Profiles — a and a DEFAULT. You can create multiple profiles in your config file for different use cases if needed. ADMIN_USER

Read the file and validate the config:

Configuration at runtime

As the config is actually a dict, you can also build it and validate it inside your script:

Signing requests

Once the configuration is validated, we need to create a signer based on that configuration. The signer is used to sign all requests made by that user — as this is a security measure required by OCI.

Note: pass_phrase and private_key_content are optional and have default values ‘None’ if they are not provided

Execute requests

And now, we can finally make our calls!

For each client you’ll be initializing, you’ll pass the config and the generated earlier: signer

From now on, you can make any calls you want using the OCI Python SDK.

You can find the complete documentation of the SDK here.

Conclusions & Complete Solution

For the first time using the OCI APIs, this process may be a little long because of the extra security measures but once you configure the prerequisites one time and you understand how it works, the rest should be pretty straight forward.

You can find below, a complete example of how to get the tenancy information and the list of subscribed regions using the DEFAULT profile from a config file.

config file

get_oci_tenancy.py

My project’s arborescence is:

I hope this was helpful to you.

You can also find the code on my GitHub Repo.

See how to authenticate using Instance Principals while running the script on OCI.