ZStack AIOS

API操作

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

跟所有的RESTful API类似，绝大多数ZStack AIOS API执行的是CRUD（Create, Read, Update, Delete）操作，以及类RPC操作。

创建资源

所有资源的创建都使用POST方法，参数通过HTTP Body传递，例如创建一个虚拟机：

POST zstack/v1/vm-instances

Authorization： OAuth 0c234e29a2ad4ff4b0d97d4f3b47c6cf

{
    "params": {
        "l3NetworkUuids": ["37a701c7fe4a40758da15593aedd8aff"],
        "defaultL3NetworkUuid": "37a701c7fe4a40758da15593aedd8aff",
        "dataDiskOfferingUuids": [],
        "name": "TestVm",
        "description": "Test",
        "systemTags": [],
        "instanceOfferingUuid": "dd53f94b58924510b0122e40799a4114",
        "type": "UserVm",
        "imageUuid": "cc7b56780879409f98c1f992b75a12b0"
    }
}

查询资源

资源的查询使用GET方法，查询条件通过Query String传参，例如查询集群cluster1中名字不等于 web-vm的虚拟机：

GET zstack/v1/vm-instances?condition=name!=web-vm&condition=cluster.name=cluster1

Authorization： OAuth 0c234e29a2ad4ff4b0d97d4f3b47c6cf

如果已知资源的UUID，要直接获取该资源的信息，直接使用GET方法不加任何查询条件，例如：

GET zstack/v1/vm-instances/56f0fd314a2647ffb4f9565f6d05858e

Authorization： OAuth 0c234e29a2ad4ff4b0d97d4f3b47c6cf

返回UUID为56f0fd314a2647ffb4f9565f6d05858e虚拟机的信息。

删除资源

删除资源使用DELETE方法，被删除资源的UUID编码在URL中，例如：

DELETE zstack/v1/vm-instances/56f0fd314a2647ffb4f9565f6d05858e

Authorization： OAuth 0c234e29a2ad4ff4b0d97d4f3b47c6cf

删除UUID为56f0fd314a2647ffb4f9565f6d05858e的虚拟机。

修改资源与类RPC操作

但由于IaaS本身业务的性质，一部分操作更类似于RPC（远程调用）而非CRUD操作，例如启动虚拟机。根据RESTful API的一些最佳实践，ZStack AIOS将这些操作都归为资源的actions子资源，例如启动虚拟机、停止虚拟机都是对虚拟机的actions子资源进行操作。举个例子：

启动虚拟机：

PUT zstack/v1/vm-instances/d46841bd4ebd47f8bf0bed85c3bdf0db/actions

{
    "startVmInstance": {}
}

停止虚拟机：

PUT zstack/v1/vm-instances/d46841bd4ebd47f8bf0bed85c3bdf0db/actions

{
    "stopVmInstance": {}
}

在上面的例子中，两个操作都访问的是相同的URL/v1/vminstances/d46841bd4ebd47f8bf0bed85c3bdf0db/actions，具体的操作类型由包含在Body中的字段名表示，例如stopVmInstance，如果该API包含额外参数，则包含在操作字段名对应的map中。

资源操作的具体字段名和例子参考每个API的详细文档。