API规范概述

ZStack 3.2.0提供原生RESTful支持。您可以通过REST定义的架构设计原则和约束条件,并使用支持HTTP的编程语言进行开发。


HTTP方法 (HTTP Verbs)

当前API支持如下操作资源的方法:
方法名 描述
GET
获取资源信息。
  • 所有的查询API以及读API均使用该方法。
POST

创建一个资源。

PUT 修改一个资源。
  • 所有对资源的修改操作,以及类RPC调用的操作,例如启动虚拟机,均使用该方法。
DELETE 删除一个资源。

传参方式

URL、Query String、HTTP body三种方式均可用于传参。每种方式可以单独使用,也可以混合使用,具体使用哪种传参方式由具体API决定。

URL传参

当对某具体资源进行操作时,资源的UUID通过编码到URL的方式进行传参。

例如启动一个UUID为 f97143d60f1042c9badd9a1336d3c105的虚拟机,URL格式为:
zstack/v1/vm-instances/f97143d60f1042c9badd9a1336d3c105/actions

这里UUID编码到URL路径当中。

Query String传参

所有使用HTTP GET方法的API均使用Query String传参。

例如查询所有状态为Running的虚拟机, URL格式为:
zstack/v1/vm-instances?condition=state=Running

HTTP Body传参

当使用POST方法创建一个资源,或PUT方法修改一个资源时,除通过URL传参的部分外,剩余参数均通过HTTP Body传参。

例如在指定物理主机上启动一个虚拟机:
PUT zstack/v1/vm-instances/f97143d60f1042c9badd9a1336d3c105/actions

{
  "startVmInstance": {
        "hostUuid": "8aef7e3a53b34eedaa05027a919156d9"
   }
}

这里虚拟机的UUID通过URL传参,参数hostUuid则通过HTTP Body传递。


HTTP Headers

当前API使用如下自定义HTTP Headers:

Authorization

除了少数API外(例如登录API),使用ZStack API前都需要一个会话(session),在调用API时通过Authorization HTTP Header传递会话UUID。该Header的格式为:
Authorization: OAuth 会话UUID
举例:
Authorization: OAuth 34cbfddd470a47d8bdb0727cd2182618
说明: OAuth和会话UUID之间用空格分隔。

X-Job-UUID

对于异步API,可以通过X-Job-UUID HTTP Header来指定该API Job的UUID,例如:
X-Job-UUID: d825b1a26f4e474b8c59306081920ff2

如果未指定该HTTP Header,ZStack会自动为API Job生成一个UUID。

说明:

X-Job-UUID必须为一个v4版本的UUID(即随机UUID)字符串去掉连接符-ZStack会验证X-Job-UUID格式的合法性,并对非法的字符串返回一个400 Bad Request的错误。

X-Web-Hook

对于异步API,可以通过X-Web-Hook HTTP Header指定一个回调URL用于接收API 返回。通过使用回调URL的方法,调用者可以避免使用轮询去查询一个异步API的执行结果。举例:
X-Web-Hook: http://localhost:5000/api-callback

X-Job-Success

当使用了X-Web-Hook回调的方式获取异步API结果时,ZStack推送给回调URL的HTTP Post请求中会包含X-Job-Success HTTP Header指明该异步API的执行结果是成功还是失败。例如:
X-Job-Success: true

当值为true时执行成功,为false时执行失败。







下载ZStack企业版

您已填写过基本信息?点击这里

姓名应该不少于两个字符
手机号格式错误
公司名称不应该少于4个字符
邮箱格式错误

下载链接将会通过邮件形式发送至您的邮箱,请谨慎填写。

下载ZStack企业版

还未填写过基本信息?点击这里

邮箱或手机号码格式错误

商务咨询:

400-962-2212 转 1

售后咨询:

400-962-2212 转 2

商务联系:

sales@zstack.io
申请ZStack多机版
姓名应该不少于两个字符
手机号格式错误
公司名称不应该少于4个字符
邮箱格式错误

商务咨询:

400-962-2212 转 1

售后咨询:

400-962-2212 转 2

商务联系:

sales@zstack.io

下载链接已发送至您的邮箱。

如未收到,请查看您的垃圾邮件、订阅邮件、广告邮件。 当您收到电子邮件后,请点击 URL 链接,以完成下载。

下载链接已发送至您的邮箱。

如未收到,请查看您的垃圾邮件、订阅邮件、广告邮件。
或点击下方URL链接 (IE内核浏览器请右键另存为), 完成下载:

感谢您使用 ZStack 产品和服务。

成功提交申请。

我们将安排工作人员尽快与您取得联系。

感谢您使用 ZStack 产品和服务。