RESTful API Overview

ZStack Cloud 5.2.0 provides native RESTful supports. You can design principles and conventions by using the REST-defined framework, and use the HTTP-based programming language for further development.

HTTP Verbs

ZStack Cloud API allows you to perform operations on resources by using the following four HTTP verbs.

HTTP Verb	Description
GET	Obtains resource information. This verb is used by all query APIs and read APIs.
POST	Creates a resource.
PUT	Updates a resource. This verb is used to modify a resource, or perform RPC style calls, for example, start a VM instance.
DELETE	Deletes a resource.

Parameter Passing

URL, Query String, and HTTP Body can all be used to pass parameters. Each method can be used independently, or be used in conjunction with other methods. Note that the specific method is determined by the API you use.

URL Parameter Passing

When you operate on a specific resource, the resource UUID will be encoded and then passed to a URL.

For example, start a VM instance with the UUID f97143d60f1042c9badd9a1336d3c105. Then, the URL format is as follows:

zstack/v1/vm-instances/f97143d60f1042c9badd9a1336d3c105/actions

In the preceding sample, the UUID is encoded and passed to a URL.

Query String Parameter Passing

All APIs that use the HTTP GET verb pass parameters by using query strings.

For example, query all the VM instances that are in the running state. Then, the URL format is as follows:

zstack/v1/vm-instances?q=state=Running

HTTP Body Parameter Passing

When you create a resource by using the POST verb, or modify a resource by using the PUT verb, the rest of the parameters will be passed by using the HTTP body method apart for those passed by using a URL.

For example, start a VM instance on a specified host.

PUT zstack/v1/vm-instances/f97143d60f1042c9badd9a1336d3c105/actions  {   "startVmInstance": {         "hostUuid": "8aef7e3a53b34eedaa05027a919156d9"    } }

In the preceding sample, the UUID of the VM instance is passed by using a URL, while the hostUuid parameter is passed by using the HTTP body.

HTTP Headers

ZStack Cloud API uses the following custom HTTP headers.

Authorization

You need a session before you use all ZStack Cloud APIs, except for a few APIs such as login API. When you call an API, the session UUID will be passed by using the Authorization HTTP header. The header format is as follows:

Authorization: OAuth Session UUID

Example:

Authorization: OAuth 34cbfddd470a47d8bdb0727cd2182618

Note: OAuth and the session UUID must be separated by using a space.

X-Job-UUID

If you use an asynchronous API, you can specify the API Job UUID by using the X-Job-UUID HTTP header. For example,

X-Job-UUID: d825b1a26f4e474b8c59306081920ff2

If an HTTP header is not specified, ZStack Cloud will automatically generate a UUID for API Job.

Note:

X-Job-UUID must be a version 4 UUID (a random UUID) without hyphens (-). ZStack Cloud will authenticate the validity of the X-Job-UUID format, and returns the 400 Bad Request error for invalid strings.

X-Web-Hook

If you use an asynchronous API, you can specify a callback URL by using the X-Web-Hook HTTP header to receive API responses. By using the callback URL method, the caller can avoid using the round-robin policy to query the results of an asynchronous API operation. For example,

X-Web-Hook: http://localhost:5000/api-callback

X-Job-Success

When you obtain the operation results of an asynchronous API by using the X-Web-Hook callback method, ZStack Cloud will include the X-Job-Success HTTP header to the HTTP Post request send to the callback URL. The X-Job-Success HTTP header indicates whether the API operation succeeds or not. For example,

X-Job-Success: true

If the value is true, the operation succeeds, or vice versa.