ZStack Logo

ZStack AIOS

API种类

面向开发者的 API 使用规范、SDK 调用方式和 AIOS 相关接口说明。

ZStack AIOS的API分为同步API和异步API两种：

同步API

所有使用GET方法的API都是同步API，调用方收到的HTTP Response中直接包含了API的结果。例如：

GET zstack/v1/zones/f3fa7671894a40f6a73f5bfc7d90c126

{
    "inventory": {
        "uuid": "f3fa7671894a40f6a73f5bfc7d90c126",
        "name": "zone1",
        "description": "test",
        "state": "Enabled",
        "type": "zstack",
        "createDate": "Jan 6, 2017 3:51:16 AM",
        "lastOpDate": "Jan 6, 2017 3:51:16 AM"
    }
}

异步API

除了登录相关的API外，所有不使用GET方法的API都为异步API。用户调用一个异步API成功后会收到202返回码以及 Body中包含的一个轮询地址和超时时间（location字段和apiTimeout字段），超时时间数值单位为毫秒,用户需要周期性的GET该轮询地址以获得API的执行结果。例如：
Status Code: 202

Body: 

{
        "apiTimeout":43200000
	"location": "http://localhost:8989/v1/api-jobs/967a26b7431c49c0b1d50d709ef1aef3"
}
通常情况下GET一个轮询地址可以得到四种返回：
  1. 202返回码表示该API仍在处理中，用户需要继续轮询。
  2. 200返回码表示API执行成功，Body中包含API结果。
  3. 503返回码表示API执行失败，Body中包含错误码。
  4. 404返回码，则表示轮询地址已经过期，产生这种结果的原因可能是用户访问了一个错误的轮询地址，或者太久没有访问该轮询地址（例如超过2天没有访问），该轮询地址已经被删除。

异步API也可以用Web Hook的方式获得结果，具体方法见后面章节。