2 Overview of Oracle Compute REST API

This section is an overview about using Oracle Compute Cloud Service REST API commands to manage Oracle Compute sites on Oracle Public Cloud Machine.

Topics:

About REST API Requests and Responses

A REST API transaction consists of an API request and a corresponding API response.

An API request consists of the following parts:

API request method—Specifies the operation that you would like to perform on the Oracle Compute object. See Supported REST API Methods.
Resource URL—Specifies the fully qualified URI of the target Oracle Compute object on Oracle Public Cloud Machine. See About Object Names.
Request headers—Specifies the REST API request headers. See REST API Request Headers.
Request body—Specifies a list of customized parameters that are required to perform an operation on the Oracle Compute object.

An API response consists of the following parts:

HTTP response code—Specifies if the REST API request was a success or a failure. See HTTP Response Codes.
Response headers—Specifies the REST API response headers.
Response body—Specifies the JavaScript Object Notation (JSON) encoded data returned in response to the REST API request.

Supported HTTP Methods

The following table describes the REST HTTP methods you can invoke for Oracle Public Cloud Machine objects.

Note:

Some methods are not supported for certain objects.

Method	Description
`POST`	Creates an object by using the JSON-formatted data in the request body
`GET`	Retrieves information about the object/s specified in the request URI
`PUT`	Updates the attributes of an object by using the JSON-formatted data in the request body
`DELETE`	Deletes the object specified in the request URI

About Object Names

Each Oracle Compute object for which you can perform REST API calls is identified uniquely by its URI. Objects such as an instance, a storage volume or an SSH key have a name based on its position in a hierarchy of containers.

For example, the object name /mytenant/public/8e7c16ad-1bc4-4743-a9ce-781be4e26f24 indicates that this instance 8e7c16ad-1bc4-4743-a9ce-781be4e26f24 is in the container public, and public is in the container mytenant.

REST API Request Headers

Ensure that the following headers are specified correctly in HTTP requests.

Request Header	Description
`Accept:`	With a few exceptions, the REST API returns JavaScript Object Notation (JSON) encoded data in its responses. The `Accept:` header must be set to indicate both JSON format and the API's version number. The supported API protocol version is v3. For `GET` calls that retrieve just the names (not details) of objects in a container, set this header to `application/oracle-compute-v3+directory+json` For all other purposes, set the header to `application/oracle-compute-v3+json` Example: Accept: application/oracle-compute-v3+json
`Accept-Encoding:`	Ensure that the HTTP client is set to supported encoding values. Example: Accept-Encoding: gzip;q=1.0, identity; q=0.5
`Accept-Charset:`	The API sends and receives only UTF-8 encoded data. Ensure that your HTTP client encodes and decodes character data, including JSON data. Example: Accept-Charset: UTF-8
`Content-Type:`	All the content in an HTTP request body must be encoded in JSON. The API protocol version is also specified in both request and response messages. The content types are: `application/oracle-compute-v3+json` `multipart/oracle-compute-v3+form-data` `application/x-tar` The server specifies the expected version of the data in the response in the `Content-Type:` header. If the server does not support the version specified by the client in the request, then it responds with HTTP status code 415 (Unsupported Media Type). If the server can't provide a response in any of the versions supported by the client, then it responds with status code 406 (Not Acceptable). Example: Content-Type: application/oracle-compute-v3+json
`Cookie:`	Include the `Cookie:` header with every request to the service. Set the value of the `Set-Cookie` header in the response received to the `POST /authenticate/` call. See Authentication.

HTTP Response Codes

The following table lists the HTTP response codes and their meanings.

HTTP Response Code	Description
2XX	API Successful Indicates that the request is successful.
201	Created An add/update request is successful.
204	No Content. Deletion request is successful with no response content.
4xx	APIClientError A client side error, in line with 4xx errors in HTTP.
401	APIUnauthorizedError The request requires user authentication or authorization.
403	APIForbiddenError The request is formed properly, but the server cannot fulfill it. The issue is not related to authorization. Do not repeat the request.
404	APINotFoundError The server has not found a match for the URI in the request. This state might be temporary so repeat the request.
405	APIMethodNotAllowedError The method specified in the Request-Line is not allowed for the resource identified by the Request-URI. This exception occurs when the request includes a method that is not supported for the object.
406	APINotAcceptableError The resource specified in the request generates response that has characteristics that are not allowed by the accept headers in the request.
409	APIConflictError The request could not be completed because of a conflict with the state of the resource or the resource already exists. You can either delete the existing object to allow the request to create it, or you can create a new object with a unique identifier.
410	APIGoneError The requested resource does not exist. This error occurs when an instance exists but is not running so a duplicate of this instance with the same identifier can not be created.
413	APIRequestTooLarge The request attempts to upload an image that exceeds the maximum upload size. The default maximum upload size is 10 GB. To change this limit, edit the `site.conf` file to change the line:`[services] [[api] [[[max_upload]]]`.
415	APIUnsupportedTypeError The server cannot complete the request because the request contains a format that is not supported by the method for the resource. This error indicates an error in JSON formatting.
5xx	APIServerError An internal error occurred, and the server cannot fulfill the request.
500	APIUncaughtExceptionError The server encountered an unexpected condition that prevented it from fulfilling the request. The error includes a code. Use this code when you report the problem to My Oracle Support.
501	APINotImplementedError The server does not support the functionality required to fulfill the request.
503	APIServiceUnavailable The server is unable to handle the request due to temporary overloading or maintenance. This error is usually related to the load on the server and is temporary. Repeat the request.
502/504	APIGatewayError The Oracle Compute service layer is not able to respond. This is usually related to a failover of the service and is temporary. Repeat the request.
507	APIInsufficientStorage The server is unable to store the data needed to complete the request. This condition is temporary. Repeat the request.

Invoking REST API Calls Using cURL

You can interact with the REST API of Oracle Compute Cloud Service by sending HTTP requests to the appropriate resource URIs. Several tools are available for making REST API calls, including clients that are extensions or plug-ins for popular browsers. cURL is a command-line tool that you can use to construct and send HTTP requests. This topic illustrates how to use cURL to send REST API calls to Oracle Compute Cloud Service.

Prerequisites

SSL-enabled version of cURL, or any other REST API client.

Most Linux installations include cURL. To download and install cURL, go to http://curl.haxx.se/download.html.
The REST endpoint URL for your Oracle Compute Cloud Service . See Oracle Compute Resource URIs
The resource URI to which you want to send the request and the parameters that you want to include in the request.

See Summary of REST APIs, Alphabetical by Resource Path. It lists all the available resources. For each resource, it also provides a link to the reference documentation for the supported parameters.
The user name and password, for your Oracle Compute Cloud Service instance. See Getting Started with Using Oracle Compute Cloud Services in Using Oracle Compute Cloud Service.

If you don’t have this information, contact your Oracle Cloud Administrator, or Tenant Administrator.

Procedure

Get an authentication token from Oracle compute Cloud Service, as shown in the following cURL command example:

Enter the command on a single line. Line breaks are used in this example for readability.
```
curl -i -X POST
     -H "Content-Type: application/oracle-compute-v3+json"
     -d '{"user":"/mytenant/myuser","password":"ft7)Dvjo"}'
        https://api.oc.example.com/authenticate/
```

In the response to the POST request, look for the Set-Cookie header, as shown in the following example.

Set-Cookie: nimbula={"identity": "{\"realm\": \"mytenant\", \"value\": \"{\\
\"customer\\\": \\\"acme\\\", ....Bb2U5uoJ2nwU7g1fDBcII/US6e7yLYqWSdb/U
ItvUiLo7/SARyfG+RmqnuFcJDoczaNssUmLLBikq8IPNAxaSIvGZmzK7K4anTwXcAhVg==\"}
"}; Path=/; Max-Age=300

Note:

Note that the Set-Cookie header and value are in a single line. Line breaks are used in this example for readability.

Store the authentication cookie in an environment variable, as shown in the following example for a Linux host. The example shown here was shortened for readability. Your command must include the entire cookie value embedded between the single quotes.
```
export ORACLE_COMPUTE_COOKIE='nimbula={"identity": "{\"realm\": \"mytenant\", \"value\": ...cAhVg==\"}"}; Path=/; Max-Age=300'
```

Send the required HTTP request to Oracle Compute Cloud Service, as shown in the following examples:

EXAMPLE 1: Getting a list of the available shapes

Send the following GET request:

curl -X GET -H "Cookie: $ORACLE_COMPUTE_COOKIE" https://api.oc.example.com/shape/

ORACLE_COMPUTE_COOKIE is the name of the variable in which you stored the authentication cookie earlier.

This command returns details of all the available shapes, in JSON format, as shown in the following example:

Note:

This sample response is formatted for readability and truncated for brevity.

{
  "result": [
    {
      "ram": 7680,
      "cpus": 2.0,
      "uri": "https://api.oc.example.com/shape/oc3",
      "name": "oc3"
    },
    {
      "ram": 15360,
      "cpus": 4.0,
      "uri": "https://api.oc.example.com/shape/oc4",
      "name": "oc4"
    },
    {
      "ram": 30720,
      "cpus": 8.0,
      "uri": "https://api.oc.example.com/shape/oc5",
      "name": "oc5"
    }
  ]
}

Summary of REST APIs, Alphabetical by Resource Path

This table lists the REST resources alphabetically by resource path and lists the supported methods for each resource.

REST Resource	Supported Methods	More Information
`/authenticate/`	`POST`	Authenticate User
`/info/`	`GET`	Get Site Information
`/imagelist/`	`DELETE`, `GET`, `POST`, `PUT`	Managing Image Lists
`/imagelist/name/entry/`	`DELETE`, `GET`, `POST`, `PUT`	Managing Image List Entries
`/instance/`	`DELETE`, `GET`, `POST`, `PUT`	Managing Instances
`/machineimage/`	`DELETE`, `GET`, `POST`, `PUT`	Managing Machine Images
`/orchestration/`	`DELETE`, `GET`, `POST`, `PUT`	Managing Orchestrations
`/property/storage/`	`GET`	Viewing Storage Properties
`/quota/`	`GET`	Viewing Tenant Quotas
`/svcnet/`	`GET`	Viewing Service Networks
`/shape/`	`GET`	Viewing Shapes
`/snapshot/`	`DELETE`, `GET`, `POST`, `PUT`	Managing Snapshots
`/sshkey/`	`DELETE`, `GET`, `POST`, `PUT`	Managing SSH Keys
`/storage/attachment/`	`DELETE`, `GET`, `POST`, `PUT`	Managing Storage Attachments
`/storage/volume/`	`DELETE`, `GET`, `POST`, `PUT`	Managing Storage Volumes
`/tenant/`	`GET`	Viewing Tenants
`/user/`	`DELETE`, `GET`, `POST`, `PUT`	Managing Users
`/vcable/`	`GET`	Viewing vCables
`/vethernet/`	`DELETE`, `GET`, `POST`, `PUT`	Managing vEthernet
`/vnet/`	`DELETE`, `GET`, `POST`, `PUT`	Managing vNET
`/vnetaccess/`	`GET`	Viewing vNET Access
`/vnetreservation/`	`DELETE`, `GET`, `POST`, `PUT`	Managing vNET Reservations