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

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

Oracle Cloud Infrastructure provides 12 months advance notice before the date of removing or changing an existing API of a Cloud Service that you have deployed which would require you to update the code.

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

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."}

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).

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

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 thedisplayName when creating a new VCN object, the service will auto-generate a value.