Jump to content
Sign in to follow this  
YongSan

OACI REST API Basics

Recommended Posts

OACI REST API Basics

The OACI RESTful API provides programmatic access to REST resources. Using the API you can obtain information about the resources and perform actions on them. For example, you can obtain a list of the existing servers, start or stop a server, modify server configuration, create a new or delete an existing server, and perform many other management tasks. This chapter provides an overview of the API and describes the basics of using it in your programs.

Accessing a Resource

A OACI resource is accessed by sending an HTTPS request to a OACI server. When the server receives a request, it processes it accordingly (performs actions or retrieves data) and sends back a response that can contain the data that you requested, an operation status code, or an error message. All OACI resources are accessed at the following base URL (referred to as baseURL in the API reference topics of this guide):

https://{ip_address | hostname}:port/paci/version

where:

ip_address | hostname is the OACI server IP address or hostname.

port is the port number on which the server is listening for REST requests

paci must be typed exactly as shown

version is the API version number

Note: Ask your service provider for the values listed above (except the "paci" string) and then use them when composing the base URL in your code.

Base URL example

The following base URL sample contains the OACI server hostname ("paci-web"), port number (4465), the "paci" string, and the version number (v1.0).

https://paci-web:4465/paci/v1.0

Resource path and parameters

When accessing a particular resource, you append the following values to the base URL:

The path that identifies the resource

Optional resource-specific parameters (where available)

Each resource is identified by a path within the base URL. An individual resource may have subresources within its own path, each of which is also identified by a path. For example, the following sample URL references the ve resource, which is "server" in general:

https://paci-web:4465/paci/v1.0/ve

The following sample URL references a specific server identified by its name, which in this instance is my-server-01:

https://paci-web:4465/paci/v1.0/ve/my-server-01

Resource-specific parameters

Some requests allow to specify additional (usually optional) parameters. For example, when obtaining the list of the operating system templates, you may add a filter to retrieve the templates for a particular operating system (e.g. a particular Linux distribution). Additional parameters are included in the URL after the question mark (?).

HTTP Request Headers

When sending an HTTPS request, the request headers must contain authentication and content type information as described below.

Authentication

OACI REST API uses the basic authentication scheme as defined by RFC 1945 (Hypertext Transfer Protocol – HTTP/1.0). An HTTP request header must contain credentials in the form of user name and password separated by a colon and encoded using the Base64 encoding scheme. The following is an example of an authorization header:

Authorization: Basic dG9ib3RyYXM6cTE=

Please note that the password to be used in OACI REST API calls must be obtain from the Operations Automation customer's control panel as follows:

In the customer's control panel, open the Cloud Infrastructure tab.

Switch to the API Access tab and click the Generate API Access Key button.

Your key appears in a message box. Use this key as the password in your API calls.

Service providers can obtain the REST API access key using the provider's control panel. Please see the provider's guide for additional information.

Content Type

Input data is included in the OACI REST API request in the form of an XML document. Therefore, Content-type should be specified as "application/xml":

Content-type: application/xml

Callbacks

OACI REST API provides a callback functionality that allows you to receive responses from OACI server asynchronously. To use a callback, the request header must include the "x-callback-url:" string followed by the URL at which your HTTP server listens for callbacks from OACI server. For example:

x-callback-url: http://192.168.3.77:8081/bd6fsdb4-24sd-4a64-8fd1-403d1b11tf0a

HTTP Methods

REST requests are sent to the OACI server as HTTP POSTGETPUT, and DELETE messages. In many cases different methods can be used on the same resource to achieve different goals. For example, you can obtain the information about a server using the GET method, modify its configuration using the PUT method, and delete it using the DELETEmethod. The resource (identified by a path) will be the same in all three instances, but each request parameters and input/output data will be different. In this guide, each API reference topic describes a particular operation and provides information about the HTTP method that must be used.

Data Input and Output

When sending or receiving data, it is included in a request or received from the OACI server as an XML document. Each request that sends or receives data has a corresponding XML specification that defines the XML document structure. When composing a request, the specification must be followed precisely. The validation of the request is performed on the server side against the XML specification. If a mandatory parameter is missing or an invalid parameter is passed, you will receive an HTTP error. An XML specification for each request and response is described in individual request topics of this guide.

The sample XML document below contains a server information. A document like this is received when a server information is requested or is included in the request when a new server is created (or an existing server is modified).

<?xml version="1.0" encoding="UTF-8"?>
<ve>
  <name>my-server-01</name>
  <description>Test server</description>
  <cpu number="2" power="1600"/>
  <ram size="512"/>
  <disk local="true" size="1"/>
  <platform>
    <template-info name="ubuntu-9.10-x86_64"/>
  </platform>
  <backup-schedule name="daily"/>
</ve>

In general, the same XML specification is used in the API for input and output when dealing with the same resource type. Certain parameters, however, cannot be used in the input version and therefore must be omitted. The reference topics in this guide describe the input and output XML specifications separately.

Error Handling

If there's an error executing a OACI REST API request, an HTTP page containing the error information is returned to the caller. The page contains an HTTP code and the description of the error. HTTP error 406 usually means that there was an error in the request or the operation cannot be completed for other reasons. In this case, the error page will also contain a OACI REST API error code and a text describing the error. The following is an example of such code and description:

P80100: Template [centos-6-x86_64] is already registered at the node ...

The code in the example above (P80100) can be interpreted as follows:

The first letter can be either P (permanent error) or T (transient error).

The first digit after the letter means one of the following:

1 — internal error

2 — resource is in use

3 — resource is not available

4 — unsupported operation

5 — invalid modification

6 — the operation cannot be performed at this time

7 — the request is missing required information

8 — invalid data was passed in the request

9 — invalid operation

The rest of the number is formed by multiplying the first digit by 10000 and adding an actual error code to it. In the example above, the actual error code is 100, therefore: 8 * 10000 + 100 = 80100.

HTTP errors other than 406 could mean other, usually general, errors and will contain a proper description of the problem.

Format and Conventions

The baseURL convention

The string "baseURL" is used in the API reference topics as a shorthand for the base URL at which the OACI resources can be accessed. When composing an HTTP request, the "baseURL" string must be substituted with the base URL specific to your OACI environment.

API reference topics

Each API reference topic in this guide provides information on how to compose an HTTP request that will perform a particular operation on a particular resource. Each entry contains the following information:

An HTTP method (POST, GET, PUT, DELETE) used to access the resource. Depending on the type of the operation, different methods may be used to access the same resource. Each operation type has its own topic in this documentation.

A full path to the resource in the form baseURL/resource_path.

A description of the resource and the operation.

A list of additional parameters that can be used with the request (where applicable).

An XML specification of the input and/or output XML documents (included only with the requests that send and/or receive data). Use these specifications to compose an XML input and parse the XML output.

Samples of HTTP request, HTTP response, and input/output XML documents.

To compose an HTTP request that will perform a particular task on a particular resource, find the corresponding reference topic (each topic name contains the short task description) and follow the provided instructions.

API reference format

Each topic describing an HTTP request has the following sections:

Description

Explains the purpose of the request.

Syntax

Specifies which HTTP method is used with the request (GET, POST, PUT, DELETE) and the resource URL.

Request Parameters

Describes the XML specification used to specify the request parameters.

Response

For requests that don't output data, describes the HTTP message returned. For requests that return data, describes the XML Schema of the output XML document.

Example

Provides samples of HTTP request, HTTP response, and XML input/output.

Testing code samples and creating your own programs

You can test the samples provided in this guide using a REST client for a Web browser. For example, you can use a simple but effective RESTClient extension for Firefox or any other available REST plug-in and a browser of your choice.

To write your own programs using the API, you will need a development tool that will allow you to make Web requests from the command line or from a program (e.g a program written in C or Python). One of the commonly used tools is cURL. With cURL you can use the API in a script or a C program.

View the full article

Share this post


Link to post
Share on other sites
Sign in to follow this  

×