Oracle Cloud Infrastructure Documentation

REST APIs

The Oracle Cloud Infrastructure APIs are typical REST APIs that use HTTPS requests and responses. This topic describes basic information about using the APIs.

Warning

Oracle recommends that you avoid using string values that include confidential information in the Oracle Cloud Infrastructure API.

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.

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

Request Signing Required

All Oracle Cloud Infrastructure API requests must be signed for authentication purposes. For information about the required credentials and how to sign the requests, see Request Signatures.

HTTPS and TLS 1.2 Required

All Oracle Cloud Infrastructure API requests must support HTTPS and SSL protocol TLS 1.2.

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. To determine the server's clock time, use this curl command with the API endpoint:

curl -s --head <endpoint> | grep Date

For example:

curl -s --head https://iaas.us-phoenix-1.oraclecloud.com | grep Date

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.

Example CreateVcn Request

POST https://iaas.us-phoenix-1.oraclecloud.com/20160918/vcns
host: iaas.us-phoenix-1.oraclecloud.com
opc-retry-token: 239787fs987
Content-Type: application/json
HTTP headers required for authentication
Other HTTP request headers per the HTTP spec

{
  "compartmentId": "ocid1.compartment.oc1..aaaaaaaauwjnv47knr7uuuvqar5bshnspi6xoxsfebh3vy72fi4swgrkvuvq",
  "displayName": "Apex Virtual Cloud Network",
  "cidrBlock": "172.16.0.0/16"
}

Example CreateVcn Response

200 OK
opc-request-id: 6c4d01a6-f764-4325-a3f8-720c8b5cae7b

{
   "id": "ocid1.vcn.oc1.phx.aaaaaaaa4ex5pqjtkjhdb4h4gcnko7vx5uto5puj5noa5awznsqpwjt3pqyq",
   "compartmentId": "ocid1.compartment.oc1..aaaaaaaauwjnv47knr7uuuvqar5bshnspi6xoxsfebh3vy72fi4swgrkvuvq",
   "displayName": "Apex Virtual Cloud Network",
   "cidrBlock": "172.16.0.0/16"
   "defaultRouteTableId": "ocid1.routetable.oc1.phx.aaaaaaaaba3pv6wkcr4jqae5f44n2b2m2yt2j6rx32uzr4h25vqstifsfdsq",
   "defaultSecurityListId": "ocid1.securitylist.oc1.phx.aaaaaaaac6h4ckr3ncbxmvwinfvzxjbr7owu5hfzbvtu33kfe7hgscs5fjaq"
"defaultDhcpOptionsId": "ocid1.dhcpoptions.oc1.phx.aaaaaaaawglzn7s5sogyfznl25a4vxgu76c2hrgvzcd3psn6vcx33lzmu2xa"
"state": "PROVISIONING", "timeCreated": "2016-07-22T17:43:01.389+0000" }

Error Format

If a request results in an error, the response contains a standard HTTP response code with 4xx for client errors and 5xx for server errors. The body also includes JSON with an error code and a description of the error. For example:

{
    "code": "InvalidParameter",
    "message": "Description may not be empty; description size must be between 1 and 400"
}

For a list of common errors across all services, see API Errors.

Request Throttling

Oracle Cloud Infrastructure applies throttling to many API requests to prevent accidental or abusive use of resources. If you make too many requests too quickly, you might see some succeed and others fail. Oracle recommends that you implement an exponential back-off, starting from a few seconds to a maximum of 60 seconds. When a request fails due to throttling, the system returns response code 429 and the following error code and description:

{
      "code": "TooManyRequests",
      "message": "User-rate limit exceeded."
}

Polling for Resource Status

Most Oracle Cloud Infrastructure resources, such as compute instances, have lifecycles. In many cases, you want your code to wait until a resource or An object that reports on the current state of an asynchronous service request. reaches a specific state, or a timeout is exceeded, before taking further action.

You can poll a resource to determine its state. For example, when you call GetInstance, the response body contains an instance resource that includes the lifecycleState attribute. You might want your code to wait until the instance's lifecycleState is RUNNING before proceeding.

Different resources take different amounts of time to transition between states. Therefore, the optimal frequency and duration parameters for a polling strategy can vary among resources. The Oracle Cloud Infrastructure SDK waiters use the following default strategy:

  • Use an exponential back-off, starting from a few seconds to a maximum of 30 seconds between poll attempts.
  • Poll up to 20 minutes, and then stop.

Or more information on waiters, see:

Where to Find Your Tenancy's OCID

If you use the API, you'll need your The root compartment that contains all of your organization's compartments and other Oracle Cloud Infrastructure cloud resources.'s OCID in order to sign the requests (see Request Signatures). You'll also need it for some of the IAM API operations. An OCID is an Oracle Cloud ID (see Resource Identifiers).

Get the tenancy OCID from the Oracle Cloud Infrastructure Console on the Tenancy Details page: Open the navigation menu, under Governance and Administration, go to Administration and click Tenancy Details.

Navigation menu showing Tenancy Details item
The tenancy OCID is shown under Tenancy Information. Click Copy to copy it to your clipboard.
Tenancy Details page showing the location of the tenancy OCID
The tenancy OCID looks something like this (notice the word "tenancy" in it): ocid1.tenancy.oc1..<unique_ID>.

List Pagination

Most List operations paginate results. For example, results are paginated for the ListInstances operation in the Core Services API. When you call a paginated List operation, the response indicates additional pages of results by including the opc-next-page header.

Note

A page can be empty even when more results remain. Any time the opc-next-page header appears, there are more list items to get. For more information about resource list control, see Overview of Search.

To get the next page of results
To change the maximum number of results per page

Retry Token

For some operations you can provide a unique retry token (opc-retry-token) so the request can be retried in case of a timeout or server error without the risk of executing that same action again. The token expires after 24 hours, but can be invalidated before then due to conflicting operations (for example, if a resource has been deleted and purged from the system, then a retry of the original creation request may be rejected).

ETags for Optimistic Concurrency Control

The API supports etags for the purposes of optimistic concurrency control. The GET and POST calls return an etag response header with a value you should store. When you later want to update or delete the resource, set the if-match header to the ETag you received for the resource. The resource will then be updated or deleted only if the ETag you provide matches the current value of that resource's ETag.

Null vs. Empty Strings for Optional Parameters

If you send an empty string ("") as the value of an optional parameter, the API validates the value as normal (for example, checks against minimum and maximum allowed length, and so on). Often the minimum allowed length is 1, so an error would be returned. If you don't set the value (it's null), the API performs no validation, and some other action may occur. For example: if you don't set a value for the displayName when creating a new VCN object, the service will auto-generate a value.