Cloud computing is a style of computing in which dynamically scalable and deployed resources are provided as a service over the network.
Users need not have knowledge of, expertise in, or control over the underlying infrastructure in the cloud that supports the services rendered to the users. As enterprises (companies, governments, and other organizations) integrate their existing IT infrastructures and IT resources with the sharable cloud paradigm, it is imperative for cloud enablers to provide a uniform API that these enterprises can use to tailor the cloud to their business processes and economic models.
The Representational State Transfer (REST) API presented here focuses on the resource models and their attributes.
This chapter contains the following sections:
As IT deployments become more complex, an abstraction of the infrastructure resources becomes more relevant to address concerns of compliance and configuration. Furthermore, such abstractions enable consumers to self serve the exact service they need and operationally control these services without any significant administrator involvement.
The REST API enables an infrastructure provider to service their customers by allowing them to perform the following:
Browse templates that contain definitions and metadata of a logical unit of service.
Deploy a template into the cloud and form an IT topology on demand.
Perform operations (such as ONLINE, OFFLINE) on the resources.
The REST API is based on the HTTP protocol and GET, POST, PUT, and DELETE requests are all used. Resource representations documented here are in JavaScript Object Notation (JSON).
The REST API presupposes no particular structure in the Uniform Resource Identifier (URI) space. The starting point is a URI, supplied by the cloud service provider, that identifies the cloud itself. The cloud's representation contains URIs for the other resources in the cloud. Operations on the cloud resources are performed by making an HTTP request against the URI of the resource.
The specification of this Cloud REST API includes the following:
Common behaviors that apply across all requests and responses, error messages, and common resource attributes.
Resource models, which describe the JSON data structures used in requests and responses.
Requests that may be sent to cloud resources and the responses expected.
The Cloud REST APIs can be used to integrate Enterprise Manager with custom-built or 3rd party self service consoles and service desks. A few example scenarios include:
Deploying databases and Oracle VM assemblies from custom-built self-service consoles.
Integration into a bigger orchestration flow, such as a provisioning preceded with approval workflows.
Deploying databases and Oracle VM assemblies from service desks.
As a part of public clouds where the tenant interface of the cloud is typically different and serves service procurement, tenant registration, and so on.
The following table describes the high level changes to Enterprise Manager Cloud Control's Cloud Service Portal Plug-in 12.1.0.4 to 12.1.0.5.
Table 43-1 Changes to the Resource Model (from 12.1.0.4 to 12.1.0.5)
| Abstract | Decsription | Impacts |
|---|---|---|
|
Availability of QuotaUsage resource. |
Service family type may provide resource quota usage information through the API. |
Additional attributes are added to the respective resource models to reference the quota usage. |
|
Availability of ServiceTemplateFinds resource. |
Service family type may provide supports to query for Service Template resources. |
Cloud level interactions return a list of service templates satisfying the listing criteria. |
The following table describes the high level changes to Enterprise Manager Cloud Control's Cloud Service Portal Plug-in 12.1.0.2 to 12.1.0.4.
Table 43-2 Changes to the Resource Model (from 12.1.0.2 to 12.1.0.4)
| Abstract | Description | Impacts |
|---|---|---|
|
Introduction of x-specification-version header. |
x-specification-version is a new header introduced in this release. The purpose of this header is to inform the backend server to switch between various supported versions of the Cloud Resource Model. By default, if this header is not specified, the server will automatically use the latest version of the resource model. Each server response will also now include x-specification-version. |
If a client wishes to interact with the web service using the previous (pre-12.1.0.4 Cloud Service Portal release) resource model in 12.1.0.4 Cloud Service Portal, the following header can be specified. x-specification-version: 10000 For example, GET /em/cloud with x-specifcation-version: 10000 will return the pre 12.1.0.4 release CloudServicePortal Cloud resource. |
|
Cloud media type is updated to be service oriented. |
Before this release, top level Cloud media type is IaaS centric. However, with the additions of Middleware as a Service in this release, the Cloud media type is transformed into a generic service model where additional XaaS can be plugged into the system without further remodel of the media type. |
The Cloud media type is no longer backward compatible. (However, using the x-specifiction-version header can still allow a client to switch back to the older media type). |
|
Consolidate the concept of VDC into Zone. |
Resource relationships that are supported by the IaaS centric VDC are now consolidated into the generic Zone resource. The VDC resource is currently not visible from the 12.1.0.4 Cloud Service Portal resource model. |
Interacting with the 12.1.0.4 Cloud Service Portal resource model would be centric around Zone instead of VDC. |
|
"media_type" attribute for resources. |
Each resource will have a "media_type" attribute to support client introspections in the generic service model. In other words, a Collection attribute in a resource may contain list of resources that are of different media type extending the same abstract media type. |
The interaction with the web service may be introspective. For example, the Cloud resource contains "service_templates" attribute that describes the list of service templates that are from various XaaS. Each service template item in the "service_templates" may be of different media types, but these media types should contain all the attributes of the generic ServiceTemplate model. |
|
"Accept" header may be optional. |
If the intention of the interaction is clear, you do not need to specify the "Accept" header. |
The web service will introspect the resource URI automatically to return the resource with the most specific media type. |
|
Generic and Specific media types. |
This version introduces the concept of Generic and Specific media types to support inheritance. For example, application/oracle.com.cloud.common.ServiceTemplate is a Generic media type and application/oracle.com.cloud.common.VMTemplate is a specific type that extends the above generic type. A specific type can extend another specific type (just like object inheritance). |
It is now possible to use the Generic type to inquire about the resource. For example, if an URI represents a resource of specific type Y that extends generic type X, then, GET URI shall also accept the "accept" header of value X. Furthermore, attributes in specific type Y are expected to include the attributes in generic type X, and therefore clients shall be able to interact with the resource on the generic type. |
The following sections specify constraints that apply to all the requests and responses that occur in the REST APIs supported by the Oracle Cloud Computing Platform.
All of the platform APIs are based on the Hypertext Transfer Protocol (HTTP), version 1.1 (RFC 2616). Each request will be authenticated using HTTP Basic Authentication (RFC 2617) unless otherwise noted. Therefore, requests sent from the public Internet (and not on a secure channel such as a VPN) must use the HTTPS protocol.
The resources in the system are identified by URIs. To begin operations, the URI for a resource must be known. Dereferencing the URI yields a representation of the resource containing resource attributes and links to associated resources.
Assumptions about the layout of the URIs or the structure of resource URIs should not be made.
In this specification, resource representations and request bodies are encoded in JavaScript Object Notation (JSON), as specified in RFC 4627. Each type of resource has its own media-type, which matches the following pattern:
application/oracle.com.cloud.common.Xxxxx+json
where Xxxxx represents the portion of the identifier unique to a particular representation format for each resource. The identifier must be globally unique in the space of vnd.com.oracle.cloud, and the media type should be registered in accordance to RFC 4288.
The Platform must provide representations of all resources available in JSON. The Platform must accept requests encoded in JSON.
In requests made to services implementing Oracle Cloud Platform APIs, several specific HTTP headers are used as described in the following table:
Table 43-3 Request Headers
| Header | Supported Values | Description | Required |
|---|---|---|---|
|
Accept |
Comma-delimited list of media types or media type patterns |
Indicates to the server what media types are acceptable. |
Recommended on requests that will produce a response message body. |
|
Authorization |
“Basic“ plus user name and password (per RFC 2617). |
Identifies the user making this request. |
Yes on most of the requests. |
|
Content-Length |
Length (in bytes) of the request message body. |
Describes the size of the message body. |
Yes on requests that contain a message body. |
|
Content-Type |
Media type describing the request message body. |
Describes the representation and syntax of the request message body. |
Yes on requests that contain a message body. |
|
Host |
Identifies the host receiving the message. |
Required to allow support of multiple origin hosts at a single IP address. |
All requests. |
|
X-YYYYYClient-Specification-Version |
String containing a specification version number. |
Declares the specification version of the YYYYY API that this client was programmed against. |
No. |
Specific HTTP headers included in the responses returned from the platform are described in the following table:
Table 43-4 Response Headers
| Header | Supported Values | Description | Required |
|---|---|---|---|
|
Content-Type |
Media type describing the response message body. |
Describes the representation and syntax of the response message body. |
Yes, on responses that contain a message body. |
|
Location |
Canonical URI of the resource, either newly created, or the original referenced resource. |
Returns a URI that can be used to request a representation of the resource. |
Yes, on responses to requests that create a new resource, or change an existing resource. |
|
Max-age, public, no-store, mustrevalidate, proxyrevalidate. |
How the representation of the resource should be cached, and its freshness. |
No. For public resources (such as a list of public assemblies or templates) that do not change frequently, allowing lenient cache-control to optimize the response. This will never be returned on a privileged resource or a resource request that contains an authorization header. |
Oracle Cloud Computing Platform APIs return standard HTTP response codes as described in the following table, under the conditions listed in the description.
Table 43-5 HTTP Response Codes
| Header | Description |
|---|---|
|
100 Continue |
The client should continue with its request. This interim response is used to inform the client that the initial part of the request has been received and has not yet been rejected by the platform. The client should continue by sending the remainder of the request or, if the request has already been completed, ignore this response. |
|
200 OK |
The request was successfully completed. If this request created a new resource that is addressable with a URI, and a response body is returned containing a representation of the new resource, a 200 status will be returned with a location header containing the canonical URI for the newly created resource. |
|
201 Created |
A request that created a new resource was completed and no response body containing a representation of the new resource is being returned. A location header containing the canonical URI for the newly created resource will be returned. |
|
202 Accepted |
The request has been accepted for processing, but the processing has not been completed. Per the HTTP/1.1 specification, the returned entity (if any) should include an indication of the request's current status. A location header containing the canonical URI for the not-yet completed resource is returned along with the status attribute indicating its progress. |
|
400 Bad Request |
The request could not be processed because it contains missing or invalid information (such as validation error on an input field, a missing required value, and so on). |
|
401 Unauthorized |
The authentication credentials included with this request are missing or invalid. |
|
403 Forbidden |
The server recognized your credentials, but you do not possess authorization to perform this request. |
|
404 Not Found |
The request specified a URI of a resource that does not exist. |
|
405 Method Not Allowed |
The HTTP verb specified in the request (DELETE, GET, HEAD, POST, PUT) is not supported for this request URI. |
|
406 Not Acceptable |
The resource identified by this request is not capable of generating a representation corresponding to one of the media types in the Accept header of the request. |
|
409 Conflict |
A creation or update request could not be completed because it would cause a conflict in the current state of the resources supported by the platform. For example, an attempt is made to create a new resource with a unique identifier that is already assigned to some existing resource or an attempt is made to modify a resource attribute which is not yet completed. |
|
410 Gone |
The requested resource is no longer available at the server and no forwarding address is known. This condition is expected to be considered permanent. Clients with link editing capabilities should delete references to the Request-URI after user approval. If the server does not know, or has no facility to determine, whether or not the condition is permanent, the status code 404 (Not Found) should be used instead. This response is cacheable unless indicated otherwise. |
|
412 Precondition Failed |
The precondition given in one or more of the request-header fields evaluated to + when it was tested on the server. This response code allows the client to place preconditions on the current resource meta-information (header field data) and thus prevent the requested method from being applied to a resource other than the one intended. |
|
500 Internal Server Error |
The server encountered an unexpected condition which prevented it from fulfilling the request. |
|
501 Not Implemented |
The server does not (currently) support the functionality required to fulfill the request. |
|
503 Service Unavailable |
The server is currently unable to handle the request due to temporary overloading or maintenance of the server. |
All the resource entities in this specification may contain the following common resource attributes.
This attribute denotes the state of the resource describing the lifecycle of the resource. This differs from the status of the entity represented by the resource which has entity specific semantics.
The following table shows the Data Model of this attribute.
Table 43-6 ResourceState Data Model
| Field | Type | Description | Occurs |
|---|---|---|---|
|
state |
String |
The current state of the resource as last known. This is a label containing lifecycle state (for example, INITIATED, CREATING, CREATED, DESTROYING, DESTROYED, READY). When there are vendor extensions, the vendor shall publish and document their semantics. |
1 |
|
progress |
Integer between 0 and 100 |
This indicates the progress made as an approximate percentage. Not all state labels assign semantic meaning to this field. |
0..1 |
|
messages |
Message[] |
Include the message data model instances to denote noteworthy communications. |
0..1 |
This attribute is a meta resource that represents a collection field in a resource. For example, a VDC contains a collection of VMs and the field that represents the list of VMs is implemented in this type.
In the resource model, a collection field is denoted as Collection<type>, for example, Collection<VM>.
Table 43-7 Collection<type> Data Model
| Field | Type | Description | Occurs |
|---|---|---|---|
|
uri |
URI |
URI that represents the collection of entities. |
1 |
|
type |
String |
Type of the entity that this collection contains. |
1 |
|
total |
Integer |
Total number of elements that can be safely assumed to be in the elements list. |
0..1 |
|
elements |
<TYPE>[] |
List of entities in this collection. The URI of the entities must be populated by the platform. When dereferencing the URI, the client must use the type field in the Accept header (except in the case where type = URI). If this is not returned, then the collection is an empty list. |
0..1 |
In addition to the resource type, the collection also supports Collection<URI> where the type field is “URI". This basic type collection requires additional type casting where the URI can be dereferenced properly.
This basic type collection requires additional type casting where the URI can be dereferenced properly. It is also permissible to have a collection of type collection, for example, Collection<Collection<Server>>.
Successful requests will generally return an HTTP status code of 200 (OK), 201 (Created), 202 (Accepted), or 204 (No Content) to indicate that the requested action has been successfully performed or submitted.
In addition, a response message body (with an appropriate media type) containing a representation of the requested information might also be included. However, it is possible for a number of things to go wrong.
The various underlying causes are described by various HTTP status codes in the range 400-499 (for client side errors) or 500-599 (for server side problems).
If a response is returned with an error status code (400-499 or 500-599), the server will also return a response message body containing a message data model, with zero or more message data models, describing what went wrong. The text values of such messages might be used, for example, to communicate with a human user of the client side application.
The entire list of messages included in a single error response is encapsulated in a messages data model. The media type shall be returned in the Content-Type header. The client shall not include the Messages media type in the Accept header.
Table 43-8 Messages Data Model
| Field | Type | Description | Occurs |
|---|---|---|---|
|
messages |
Message |
Zero or more message data for each individual message. |
0..n |
An individual message contains the following fields:
Table 43-9 Individual Message Data Model
| Field | Type | Description | Occurs |
|---|---|---|---|
|
code |
String |
Zero or more message data for each individual message. |
0..1 |
|
field |
String |
Name of the field from the request data model that this message is associated with. |
0..1 |
|
hint |
String |
Localized text further describing the nature of the problem, possibly including potential workarounds that the client could try. |
0..1 |
|
text |
String |
Localized text describing the nature of the problem reported by this message. |
1 |
|
severity |
String |
Label indicating the severity of the error condition represented by this message. Vendor shall publish the enumerators that are associated with this field and their semantics. |
0..1 |
|
stack_trace |
String |
Vendor specific stack trace associated with this message. |
0..1 |
|
source |
String |
Symbolic identifier of the service implementation component that triggered this message. |
0..1 |