Cloud Infrastructure API Requests

Describes the process for requests to the Web service.

The Web service was developed as a simple query Web service. This Web service requires an SSL encrypted HTTP connection. A typical request to the Web service is made through HTTP using a GET or POST method that includes the request parameters for the desired action. The Web service returns the result of a request in XML format that conforms to the XML schema of the Web service.

The Web service implementation added the following servlets deployed into the Common Agent Container of Oracle Enterprise Manager Ops Center:

  • The AKM servlet handles all actions related to account authentication.

  • The IAAS servlet handles all actions related to cloud computing management.

Required Web Service HTTP Request Parameters

All requests to the Web service share some required parameters. Other parameters are only required for requests to the specific servlet, AKM or IAAS. Table 5-1contains the common parameters that are required in an HTTP request to the Web service.

Table 5-1 Required Parameters for an HTTP Request

Servlet Parameter Description

AKM and IAAS

Action

Indicates the name of the IAAS or AKM action to perform

AKM and IAAS

Version

Version of the Web service

IAAS only

AccessKeyId

Access Key ID. This parameter identifies the user and the account. This is the value returned by the RegisterAccessKey action.

AKM and IAAS

Timestamp

Timestamp in milliseconds since January 1, 1970

AKM and IAAS

Expires

Time at which the request expires. Expiry date in milliseconds since January 1, 1970; it must be greater than the timestamp.

IAAS only

Signature

Encoded hash value of the data to be signed. Signature is used to authenticate the data.

IAAS only

SignatureMethod

Type of the signature

IAAS only

SignatureVersion

Version number of the signature

Signing a Web Service Request

Procedure to sign a request for the Web service.

Signing a request to the Web service involves applying the following algorithm.

  1. Collect all parameters for the Web service request (see Table 5-1). The parameters and their values are UTF-8 strings. The signature is not yet included in these parameters because the aim of the algorithm is to calculate the value of this signature parameter.

  2. The URL encodes all parameter names and their values. The following characters are not URL encoded and remain as they are: A to Z, a to z, 0 to 9, minus (-), underscore (_), period (.), and asterisk (*) . All other characters are encoded as %XX (with XX being a hexadecimal number consisting of 0 to 9 and/or uppercase A to F). Extended UTF-8 characters are encoded with %XX%XX. Space is encoded as a plus sign (+). This is what Java's java.net.URLEncoder.encode() method does, using UTF-8 as encoding.

  3. Create a string by concatenating the next elements in the same order. A"\n" is required between every field.

    1. POST or GET, depending on request type. "\n"

    2. Host name as given in the HTTP host header field, all in lower case (for example, opscenter.com) "\n"

    3. Base URL of the Web service."\n"

    4. A sequence of the sorted, encoded parameter names, followed directly by the equal sign (=) and their corresponding encoded parameter value. The parameters are joined together with the ampersand (&)."\n"

Sign this string using the private key and the specified SignatureMethod and SignatureVersion parameters. The signature method must be SHA512withRSA.

The signing result is then used as the value of the signature parameter for the request.

Example 5-1 and Example 5-2 show a complete URL for an HTTP GET request to the IAAS and AKM servlet. For a detailed example of generating requests to the Web service, see Web Service Client Example.

Example 5-1 URL for an HTTP GET request to the IAAS servlet

https://<EnterpriseControllerHostname>/iaas/?Action=DescribeVnets&Version=1&AccessKeyId=AK_1&Timestamp=1331058169938&Expires=1331058469938&SignatureMethod=SHA512withRSA&SignatureVersion=1&Signature=bj8GfJCqvPZZPU2JoWAGzZdCF+N767rQejILMQwNdgKLfoGGqAwDPRYMr/ghUoBc6RB3nKYgAyPdmtCfhzRGTqECgUWy0jCrE99+utGeeJ0/XRQ9LxyYeBgzjO3lHP+hFhUo+gUtQaSYPhUHH7eTkxg/CrolMxibglypJM/rIf90yEqSeqhphQt7hWxlT0DNAy6/cZt8isT/Tu8V7ZFjBFkEpLfN97bIOJ2vIIpOeetmftuw4ObtqjbUp6+7dpVkhhCQnX0MAIDj+mjorEOzcwK+F1pYuzES0fjaW0MowG+cA/9gttDjg7r5H29i3qbbjIlvAt6fk1HPpSxQTSTOTg==

Example 5-2 URL for an HTTP GET request to the AKM servlet

https://<<username>>:<<password>>@<EnterpriseControllerHostname>/akm/?Action= DescribeAccounts&Version=1&Timestamp=1330954619299&Expires=1330954919299