REST APIs
The Oracle Cloud Infrastructure APIs are typical REST APIs that use HTTPS requests and responses.
API Reference and Endpoints
For links to the Oracle Cloud Infrastructure API reference and a list of the regional API endpoints, see
API Reference and Endpoints.
Using the Collections to make API calls
Fork, Select and Update OCI Credentials Environment
Fork and Update the
OCI Credentials
Qodex Environment Variables with your Oracle Cloud Infrastructure credentials information.
Get OCI Credentials
You will need the following information about your tenancy and user to be able to make API calls:
- tenancy_ocid: OCID of your tenancy.
- user_ocid: OCID of the user calling the API.
- fingerprint: Fingerprint for the public key that was added to this user.
- private_key: Contents of the private key file.
- passphrase: Optional passphrase used for the key. Only required if it key is encrypted.
- region: An Oracle Cloud Infrastructure region. See Regions and Availability Domains.
The easiest way to quickstart and generate the values, in case you do not have already, is to follow this steps:
- Navigate to the OCI Console > Identity > My profile > API keys
- Click on
Add API Key
- Download the Private Key (Note that you can import your own public key and use your private key later)
- After you succesfully added the API Key, a
Configuration file preview
dialog will appear. (You can open this dialog later by clicking on the 3-dots menu of the API key that you generated)
- On the Configuration file preview textbox, copy the contents of each variable after the
=
and paste to the OCI credentials Qodex Environment that you just forked. Use the below table as reference:
Configuration file preview | OCI Credential variable Name | Example Value |
---|
user | user_ocid | ocid1.user.oc1..aaaa... |
fingerprint | fingerprint | ac:ee:ca:3f:... |
tenancy | tenancy_ocid | ocid1.tenancy.oc1..aaa... |
region | region | us-ashburn-1 |
(Contents of the Downloaded Private Key) | private_key | --- BEGIN PRIVATE KEY ------... |
Forking an API and testing the API and the OCI Credentials
Now you can fork a new API collection and test the API with the new configured credentials.
Here a quick example to check the OCI Cloud Regions that you have subscribed:
- Fork the List Region Subscriptions using this [link]
- Make sure you have the
OCI Credentials
enviroment selected on the top-right of the Qodex
- Click on the blue SEND button of the API and you should see the all regions that your tenancy is subscribed
Informations about the API usage
Credentials Variables Explained
- tenancy_ocid: OCID of your tenancy.
To get the value, see Required Keys and OCIDs.
Example: ocid1.tenancy.oc1..
(shortened for brevity)
- user_ocid: OCID of the user calling the API.
To get the value, see Required Keys and OCIDs.
Example: ocid1.user.oc1..
- fingerprint: Fingerprint for the public key that was added to this user.
To get the value, see Required Keys and OCIDs.
- private_key: Contents of the private key file.
You can open the file in an editor and copy the contents or use a command like pbcopy < ~/.oci/oci_api_key.pem
The key pair must be in PEM format. For instructions on generating a key pair in PEM format, see Required Keys and OCIDs.
- passphrase: Passphrase used for the key. Only required if it key is encrypted.
- region: An Oracle Cloud Infrastructure region. See Regions and Availability Domains.
Example: us-ashburn-1
- compartment_ocid: OCID of the compartment that will be used for the API calls.
API Version
The base path of the endpoint includes the desired API version (for example, 20160918). Here's an example for a POST request to create a new VCN in the Ashburn region:
POST https://iaas.us-ashburn-1.oraclecloud.com/20160918/vcns
API Breaking Changes Policy
Oracle Cloud Infrastructure will provide 12 months advance notice prior to the date of removing or changing an existing API of a Cloud Service that you have deployed which would require you to update your code.
Maximum Allowed Client Clock Skew
HTTP status code 401 (NotAuthenticated) is returned if the client's clock is skewed more than 5 minutes from the server's.
Request and Response Format
The Oracle Cloud Infrastructure APIs use standard HTTP requests and responses. Each may contain Oracle-specific headers for pagination, entity tags (ETags), and so on as described elsewhere in this topic and in the API documentation.
Each response includes a unique Oracle-assigned request ID (for example, bb3f3275-f356-462a-93c4-bf40fb82bb02) in the
opc-request-id
response header. If you need to contact Oracle about a particular request, please provide this request ID.
Many of the API operations require JSON in the request body or return JSON in the response body. The specific contents of the JSON are described in the API documentation for the individual operation. Notice that the JSON is not wrapped or labeled according to the operation's name or the object's name or type.
Note: Make sure to set the Content-Type header to application/json in your POST and PUT requests that contain JSON in the body.