RESTful API Overview

ZStack 3.10.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 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?condition=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 API uses the following custom HTTP headers.

Authorization

You need a session before you use all ZStack 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 will automatically generate a UUID for API Job.

Note:

X-Job-UUID must be a version 4 UUID (a random UUID) without hyphens (-). ZStack 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 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.








Back to Top

Download

Already filled the basic info?Click here.

Enter at least 2 characters.
Invalid mobile number.
Enter at least 4 characters.
Invalid email address.
Wrong code. Try again. Send Code Resend Code (60s)

An email with a verification code will be sent to you. Make sure the address you provided is valid and correct.

Download

Not filled the basic info yet? Click here.

Invalid email address or mobile number.

Email Us

contact@zstack.io
ZStack Training and Certification
Enter at least 2 characters.
Invalid mobile number.
Enter at least 4 characters.
Invalid email address.
Wrong code. Try again. Send Code Resend Code (60s)

Email Us

contact@zstack.io
Request Trial
Enter at least 2 characters.
Invalid mobile number.
Enter at least 4 characters.
Invalid email address.
Wrong code. Try again. Send Code Resend Code (60s)

Email Us

contact@zstack.io

The download link is sent to your email address.

If you don't see it, check your spam folder, subscription folder, or AD folder. After receiving the email, click the URL to download the documentation.

The download link is sent to your email address.

If you don't see it, check your spam folder, subscription folder, or AD folder.
Or click on the URL below. (For Internet Explorer, right-click the URL and save it.)

Thank you for using ZStack products and services.

Submit successfully.

We'll connect soon.

Thank you for using ZStack products and services.