RESTful API Overview

ZStack Cloud 5.5.30 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.

HTTP Status Code

The following table lists the status codes used by ZStack Cloud .

HTTP Status Code	Description
200	The API operation has succeeded.
202	The API request has been accepted by ZStack Cloud, and you need to obtain the API result by using the round-robin policy or webhook. The status code only appears when you call an asynchronous API.
400	The API request does not include the required parameter, or includes an invalid parameter. The detailed information can be obtained from the HTTP response body.
404	The correct URL was not found, which usually because a wrong API URL is specified. If the URL that you access is the round-robin address returned by the asynchronous API, the round-robin address has expired.
405	The API call uses a wrong HTTP method. For example, when you create a resource, you might mistakenly used the GET method instead of the POST method.
500	The ZStack Cloud RESTful terminal has encountered an internal error.
503	The API operation incurred an error. For example, you cannot create a VM instance because of the resource shortage. The detailed error information can be obtained from the HTTP response body.

API Type

ZStack Cloud API includes the following two types of APIs.

Synchronous API

APIs that use the GET method are all synchronous APIs, and includes API results in HTTP response received by callers. For example,

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"
    }
}

Asynchronous API

Apart from the login APIs, all APIs that do not use the GET method are asynchronous APIs. After you successfully called an asynchronous API, you will receive a 202 status code and a round-robin address and timeout period (the location and apiTimeout fields) contained in Body. The unit of the apiTimeout field value is milliseconds. In addition, by using the GET method, you need to periodically request the round-robin address to obtain API operation results. For example,

Status Code: 202

Body:

{
        "apiTimeout":43200000
	"location": "http://localhost:8989/v1/api-jobs/967a26b7431c49c0b1d50d709ef1aef3"
}

Normally, when you request a round-robin address by using the GET method, you can obtain the following four types of responses:

202 status code: indicates that the API is still being processed, and you need to continuously use the round-robin policy.
200 status code: indicates that the API operation succeeded, and the API result is contained in Body.
503 status code: indicates that the API operation failed, and the error code is contained in Body.
404 status code: indicates that the round-robin address has expired. That means that you probably access a wrong round-robin address, or the round-robin address is deleted because you have not accessed the round-robin address for a long time (for example, 2 days).

If you use an asynchronous API, you can also obtain the operation results by using webhook. The detailed usage can be seen in the following topics or sections.

API Operation

Similar to all RESTful APIs, most of ZStack Cloud APIs can perform create, read, update, and delete (CRUD) operations and remote procedure call (RPC) style operations.

Create Resource

To create resources, use the POST method. The parameters are passed by using the HTTP body. The following is an example of creating a VM instance:

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"
    }
}

Query Resource

To query resources, use the GET method. The query conditions are passed by using a query string. The following is an example of querying the VM instances whose name is not equal to web-vm in the cluster1:

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

Authorization: OAuth 0c234e29a2ad4ff4b0d97d4f3b47c6cf

If you already know the resource UUID and want to obtain directly the resource information, use directly the GET method without adding any query condition. For example,

GET zstack/v1/vm-instances/56f0fd314a2647ffb4f9565f6d05858e

Authorization: OAuth 0c234e29a2ad4ff4b0d97d4f3b47c6cf

This sample above returns information about the VM instance whose UUID is 56f0fd314a2647ffb4f9565f6d05858e.

Delete Resource

To delete resources, use the DELETE method. The UUID of the deleted resource is encoded in a URL. For example,

DELETE zstack/v1/vm-instances/56f0fd314a2647ffb4f9565f6d05858e

Authorization: OAuth 0c234e29a2ad4ff4b0d97d4f3b47c6cf

This sample above deletes the VM instance whose UUID is 56f0fd314a2647ffb4f9565f6d05858e.

Change Resource and Perform RPC-Style Operation

Due to the nature of IaaS businesses, a portion of operations, such as starting a VM instance, are more similar to RPC operations instead of CRUD operations. According to some best practices of RESTful APIs, ZStack Cloud will categorize all these operations into sub-resources of operations. For example, when you start VM instances, or stop VM instances, you are performing operations on the sub-resources.

Start a VM instance:

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

{
    "startVmInstance": {}
}

Stop a VM instance:

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

{
    "stopVmInstance": {}
}

In the preceding samples, both operations access the same URL /v1/vminstances/d46841bd4ebd47f8bf0bed85c3bdf0db/actions, and the specific operation types are indicated by the field name contained in Body. For example, if the stopVmInstance API contains additional parameters, these parameters are contained in the map to which the operation field name corresponds.

For more information about the specific field names of resource operations and examples, refer to detailed topics of each ZStack Cloud API.

Basic Workflow

In the following example, we will create a zone to describe the basic workflow for using the RESTful API.

Log In

The first step to use APIs is to log in to your account to obtain a session UUID for subsequent API calls.

PUT zstack/v1/accounts/login

body:

{
    "logInByAccount": {
        "password": "b109f3bbbc244eb82441917ed06d618b9008dd09b3befd1b5e07394c706a8bb980b1d7785e5976ec049b46df5f1326af5a2ea6d103fd07c95385ffab0cacbc86",
        "accountName": "admin"
    }
}

In the preceding sample, the account password is the result generated by SHA-512.

The API response is as follows:

status code: 200

body:

 {
    "inventory": {
        "uuid": "00d038b699b74e76a01705918d48d939",
        "accountUuid": "36c27e8ff05c4780bf6d2fa65700f22e",
        "userUuid": "36c27e8ff05c4780bf6d2fa65700f22e",
        "expiredDate": "Jan 1, 2017 11:31:06 AM",
        "createDate": "Jan 1, 2017 9:31:06 AM"
    }
 }

The response content contains the account UUID and other fields. The session UUID that you need is contained in the uuid field: 00d038b699b74e76a01705918d48d939.

Create Zone

POST zstack/v1/zones

headers:

Authorization: OAuth 00d038b699b74e76a01705918d48d939

body:

{
    "params": {
        "name": "Zone1",
        "description": "Test"
    }
}

The CreateZone API is an asynchronous API. Therefore, the API response is a round-robin address and a timeout period instead of a direct result. For example,

status code: 202

body:

{
    "apiTimeout":1800000
    "location": "http://localhost:8080/v1/api-jobs/d0345d3ddcae485f8170572b15a2b581"
}

You need to obtain API results periodically by using the round-robin policy. For example,

GET http://localhost:8989/v1/api-jobs/d0345d3ddcae485f8170572b15a2b581

Authorization: OAuth 00d038b699b74e76a01705918d48d939

If the API operation does not complete, the preceding GET operation still obtains a 202 status code and the round-robin address. After the API operation succeeded, you will get the following result:

status code: 200

body:

{
    "inventory": {
        "uuid": "f52fe55b64094ceb99b3893a238c4931",
        "name": "Zone1",
        "description": "Test",
        "state": "Enabled",
        "type": "zstack",
        "createDate": "Jan 1, 2017 9:31:07 AM",
        "lastOpDate": "Jan 1, 2017 9:31:07 AM"
    }
}

Query Zone

You can use the GET method to obtain the information about the zone you created. For example,

GET zstack/v1/zones/f52fe55b64094ceb99b3893a238c4931

Authorization: OAuth 00d038b699b74e76a01705918d48d939

The response is as follows:

status code: 200

body:

{
    "inventory": {
        "uuid": "f52fe55b64094ceb99b3893a238c4931",
        "name": "Zone1",
        "description": "Test",
        "state": "Enabled",
        "type": "zstack",
        "createDate": "Jan 1, 2017 9:31:07 AM",
        "lastOpDate": "Jan 1, 2017 9:31:07 AM"
    }
}

Log Out

When all API calls are completed, you need to log out the session. For example,

DELETE zstack/v1/accounts/sessions/00d038b699b74e76a01705918d48d939

The response is as follows:

status code: 200

Webhook

Using the round-robin policy to query the operation results of asynchronous APIs is inefficient. In this regard, zstack provides the webhook method to actively send API results to callers.

To use the webhook feature, you only need to specify X-Job-UUID and X-Web-Hook in the HTTP headers. In the preceding example of creating a zone, the version of the API that use the webhook method is as follows:

POST zstack/v1/zones

headers:

Authorization: OAuth 00d038b699b74e76a01705918d48d939
X-Job-UUID: d0345d3ddcae485f8170572b15a2b581
X-Web-Hook: http://127.0.0.1:8989/rest-webhook

body:

{
    "params": {
        "name": "Zone1",
        "description": "Test"
    }
}

The API response is still a 202 status code and a round-robin address. However, you do not need to use the round-robin policy again. After the API operation succeeded, the result will be sent to:

http://127.0.0.1:8989/rest-webhook

POST http://127.0.0.1:8989/rest-webhook

headers:

X-Job-Success: true
X-Job-UUID: d0345d3ddcae485f8170572b15a2b581

body:

{
    "inventory": {
        "uuid": "f52fe55b64094ceb99b3893a238c4931",
        "name": "Zone1",
        "description": "Test",
        "state": "Enabled",
        "type": "zstack",
        "createDate": "Jan 1, 2017 9:31:07 AM",
        "lastOpDate": "Jan 1, 2017 9:31:07 AM"
    }
}

In the result above, X-Job-Success indicates whether the API operation succeeds. In addition, the value contained in X-Job-UUID is the same as that of X-Job-UUID when you call APIs. Note that you can compare the result with the API.

Query API

You can query a resource by using the GET method. Similar to MySQL, you can specify multiple query conditions and the order method, or select fields and perform cross-table query.

ZStack Cloud supports more than 4 million query conditions as well as factorial of 4 million combinations of conditions.

Single Table Query

Query the VM instance whose name is vm1. For example,

GET zstack/v1/vm-instances?q=name=vm1

Query the VM instance whose name is vm1 and is in the Running state. For example,

GET zstack/v1/vm-instances?q=name=vm1&q=state=Running

These two samples are about querying the VM resource itself, which belongs to the single table query in the database level.

Cross-Table Query

You can perform cross-table queries by using the . delimiter. The following are two examples:

Query the VM instance whose IP address is 192.168.10.100. The cross-table query is performed for the VM instance table and the NIC table.

GET zstack/v1/vm-instances?q=vmNics.ip=192.168.10.100

Query all the VM instances that are running on the 10.10.20.3 IP address. The cross-table query is performed for the VM instance table and the host table.

GET zstack/v1/vm-instances?q=host.managementIp=10.10.20.3

Query API Parameters

Name	Type	Location	Description	Optional Value	Starting Version
q	List	query	Optional. The query condition. For more information, see Query Condition. If omitted, all records will be returned. The number of returned records is subject to the limit field.		0.6
limit	Integer	query	Optional. The maximum number of returned records. This field is equivalent to the limit field of MySQL. Default value: 1000.		0.6
start	Integer	query	Optional. The first record to query. This field is equivalent to the offset field of MySQL. You can perform paginated query by using both the start and limit fields.		0.6
count	Boolean	query	Optional. The count query. This field is equivalent to the count() function of MySQL. If true, the API only returns the number of records that meet the query condition.		0.6
groupBy	String	query	Optional. Groups rows into subgroups based on values of columns or expressions. This field is equivalent to the Group By clause in MySQL, such as groupBy=type.		1.9
replyWithCount	Boolean	query	Optional. If true, the query response returns both the records and the record count. Default value: false. For more information, see Paginated Query.		0.6
sort	String	query	Optional. The sort field, which is equivalent to the sortBy keyword of MySQL. This field must be used with '+' or '-' followed by the sort field name. Note that '+' means sort ascending, while '-' means sort descending. For example, sort=+key: sorts ascending according to the key sort=-key: sorts descending according to the key	'+' field name, '-' field name	0.6
fields	List	query	Optional. The returned fields. This field is equivalent to the select field of MySQL. For example, if fields=name,uuid, only names and UUIDs that meet the query conditions are returned.		0.6

Query Condition

The query conditions of ZStack Cloud query API are similar to the MySQL database.

For example,

uuid=bfa67f956afb430890aa49db14b85153
totalCapacity>2000
vmInstanceUuid not null

Note:

Any space must not be contained between the field name, query operator, and match value.
For example, uuid = 25506342d1384c07b7342373a57475b9 is a wrong query condition. The correct format is uuid=25506342d1384c07b7342373a57475b9.

The relations among multiple query conditions are and. ZStack Cloud supports the following 10 query operators:

=: Equal. For example,

vmInstanceUuid=c4981689088b40f98d2ade2548c323da

!=: Not equal. For example,
```
vmInstanceUuid!=c4981689088b40f98d2ade2548c323da
```
>: Greater than.
<: Less than.
>=: Greater than or equal.
<=: Less than or equal.
?=: in operator. This operator is used to check whether a value is within a set of values. Values in the set are separated by using commas (,). For example, check whether uuid is within a set of values.
```
uuid?=25506342d1384c07b7342373a57475b9,bc58d68090ac42358c0cb0fe72e3287f
```
!?=: not int operator. This operator is used to check whether a value is not within a set of values. Values in the set are separated by using commas (,). For example, check whether name is not equal to VM1 and VM2.
```
name!?=VM1,VM2
```
~=: Simple pattern matching, which is similar to the like operation in MySQL. Use % to match any number of characters, even zero characters. Use _ to match exactly one character. For example, query a name that starts with IntelCore.
```
name~=IntelCore%
```
Or query a name that starts with IntelCore and ends with 7. A character will be fuzzily matched between IntelCore and 7.
```
name~=IntelCore_7
```
Here, names with IntelCoreI7 and IntelCoreM7 will be matched.
!~=: Negation of simple pattern matching. This operator is used to query a field that cannot be matched by using simple pattern matching. In addition, the match condition is the same as that of ~=.
is null: Checks whether a value is NULL.
```
name=null
```
not null: Checks whether a value is not NULL.
```
name!=null
```

Paginated Query

start, limit, and replyWithCount can all be used in conjunction to achieve paginated queries.

start: Specifies the first record to query.
limit: Specifies maximum number of returned records.
replyWithCount: If true, the query response returns both the records and the record count that meet the query condition. You can know how many times of paginated queries are required by comparing this field with the start field.

For example,

If a total of 1000 records meet the query condition, you can use the following combination:

start=0 limit=100 replyWithCount=true

Then, the API response will contain the first 100 records, and the total field is equal to 1000, indicating that a total number of 1000 records meet the query condition.

Obtaining Query Fields of a Resource

We support a large number of query conditions. The query conditions listed in this documentation are only a part of them.

You can check the queryable fields of a resource and the fields that can be queried across tables by using the autocomplete feature of zstack-cli.

For example, to query a VM instance, enter QueryVmInstance in zstack-cli, and complete the rest of the fields by pressing the Tab key. Then, you can see the following prompt page:

- >>>QueryVmInstance
[Query Conditions:]
allVolumes.            cluster.               host.                  image.                 instanceOffering.      rootVolume.
vmNics.                zone.

__systemTag__=         __userTag__=           allocatorStrategy=     clusterUuid=           cpuNum=                cpuSpeed=
createDate=            defaultL3NetworkUuid=  description=           groupBy=               hostUuid=              hypervisorType=
imageUuid=             instanceOfferingUuid=  lastHostUuid=          lastOpDate=            memorySize=            name=
platform=              rootVolumeUuid=        state=                 type=
uuid=                  zoneUuid=

[Parameters:]
count=                 fields=                limit=                 replyWithCount=        sortBy=                sortDirection=
start=                 timeout=

Information in the middle rows is displayed as follows:
```
__systemTag__=         __userTag__=           allocatorStrategy=     clusterUuid=           cpuNum=                cpuSpeed=
createDate=            defaultL3NetworkUuid=  description=           groupBy=               hostUuid=              hypervisorType=
imageUuid=             instanceOfferingUuid=  lastHostUuid=          lastOpDate=            memorySize=            name=
platform=              rootVolumeUuid=        state=                 type=
uuid=                  zoneUuid=     
```
Except for both __systemTag__ and __userTag__, the rest are all native fields in the VM table. You can specify them in the API query condition, and specify these fields in fields to filter other fields that you do not want the API to return. For example,
```
GET zstack/v1/vm-instances?q=cpuNum>5
```
The sample above returns the VM instances whose CPU number is larger than 5.
```
GET zstack/v1/vm-instances?q=hypervisorType=KVM&fields=uuid&fields=name
```
The sample above returns the VM instances whose hypervisor type is KVM. The API response will only contain the name and UUID of the KVM instances, because both uuid and name are specified in fields.
Note:
Only native fields of resources are selected by fields. __userTag__, __systemTag__, and the following cross-table fields cannot appear in fields.
The first prompt row indicates which VM resources can be queried across tables with other resources. For example,
```
allVolumes.            cluster.               host.                  image.                 instanceOffering.      rootVolume.
vmNics.                zone.
```
In the sample above, allVolumes means all volumes, cluster means the cluster, and vmNics means the VM NICs.
If you need to check the specific fields of these resources, enter the resource name followed by a period (.), and complete the rest of the fields by pressing the Tab key.
For example,
```
- >>>QueryVmInstance vmNics.
[Query Conditions:]
vmNics.eip.                   vmNics.l3Network.             vmNics.loadBalancerListener.  vmNics.portForwarding.        vmNics.securityGroup.
vmNics.vmInstance.

vmNics.__systemTag__=         vmNics.__userTag__=           vmNics.createDate=            vmNics.deviceId=              vmNics.gateway=
vmNics.ip=                    vmNics.l3NetworkUuid=         vmNics.lastOpDate=            vmNics.mac=                   vmNics.metaData=
vmNics.netmask=               vmNics.uuid=                  vmNics.vmInstanceUuid=  
```
In the sample above, we entered the vmNics resource followed by a period (.) to indicate that a cross-table query will be performed. Pressing the Tab key completes the rest native fields of vmNics and other resources that can be queried cross tables.
- vmNics.ip means the ip native field of a NIC.
```
GET zstack/v1/vm-instances?q=vmNics.ip=192.168.0.100
```
  In the sample above, we performed a cross-table query by using the ip field of the NIC table as the query condition. In the response, the VM instance whose IP address is 192.168.0.100 is returned.
- Similarly, the NIC resource can be queried across tables with other resources, such as vmNics.eip.
  For example, you can perform query across the NIC table and the EIP table.
```
GET zstack/v1/vm-instances?q=vmNics.eip.ip=192.168.0.100
```
  In the sample above, the query is performed across 3 tables. In the response, the VM instance whose EIP is 192.168.0.100 is returned.
The cross-table query allows you to perform query across resources that are logically related in the system. For example,
```
- >>>QueryVmInstance zone.cluster.l2Network.l3Network.
[Query Conditions:]
zone.cluster.l2Network.l3Network.ipRanges.         zone.cluster.l2Network.l3Network.l2Network.        zone.cluster.l2Network.l3Network.networkServices.
zone.cluster.l2Network.l3Network.serviceProvider.  zone.cluster.l2Network.l3Network.vmNic.            zone.cluster.l2Network.l3Network.zone.


zone.cluster.l2Network.l3Network.__systemTag__=    zone.cluster.l2Network.l3Network.__userTag__=      zone.cluster.l2Network.l3Network.createDate=
zone.cluster.l2Network.l3Network.description=      zone.cluster.l2Network.l3Network.dnsDomain=        zone.cluster.l2Network.l3Network.l2NetworkUuid=
zone.cluster.l2Network.l3Network.lastOpDate=       zone.cluster.l2Network.l3Network.name=             zone.cluster.l2Network.l3Network.state=
zone.cluster.l2Network.l3Network.system=           zone.cluster.l2Network.l3Network.type=             zone.cluster.l2Network.l3Network.uuid=
zone.cluster.l2Network.l3Network.zoneUuid= 
```
In the sample above, the query is performed across the tables of zone, cluster, L2 network, and L3 network.
Note:
- Since a resource logic has a loop, the loop path can be created. For example, assume that the VM instance is a query body, and can be queried across tables, such as using QueryVmInstance vmNics.. Meanwhile, assume that the NIC is also a query body, and can be queried across tables with the VM instance, such as using QueryVmNic vmInstance.. Hence, a loop path is created.
- You must avoid performing the cross-table query for the loop. For example, use QueryVmInstance vmNics.vmInstance.name=vm1 to perform the cross-table query for the VM instance of name=vm1. In fact, it is totally equal to using QueryVmInstance name=vm1. This is meaningless, because it will only generate complex SQL statements, which will lead to inefficient database queries.
Both __systemTag__ and __userTag__ are special query conditions, allowing you to query resources by using a tag.
For example, you can query a VM instance that has the staticIp:10.10.1.20 tag.
```
QueryVmInstance __systemTag__=staticIp:10.10.1.20
```

Changing API Service Port

Assume that you need to change an API service port. For example, to change the original API service port 8080 to the API service port 8989, follow the following steps:

Go to /usr/local/zstacktest/apache-tomcat/webapps/zstack/WEB-INF/classes/zstack.properties, and configure the following parameters in the zstack.properties configuration file:
```
CloudBus.httpPort = 8989
RESTFacade.port = 8989
```
Go to /usr/local/zstacktest/apache-tomcat-8.5.35/conf/server.xml, and change port 8080 to port 8989 in the server.xml configuration file of tomcat.
Run the following command to change the management node port to 8989:
```
zstack-ctl config_ui --mn-port 8989
```
Restart the management node and UI.
```
zstack-ctl stop
zstack-ctl start
```
Specify the port to 8989 when you are using zstack-cli.
```
zstack-cli --port 8989
```

Note:

The configured API service port must be in the valid range, and must not be in conflict with the API service port occupied by ZStack Cloud.

Batch API Response

Batch API responses can be classified into two categories: responses of long jobs and responses of non-long jobs.

Non-Long Job API Response

For error responses of non-long jobs, the value of the success field in the first layer is true. The value of the success field in inner layers vary depending on the sub-task result. If a sub-task succeeded, success=true is returned. Otherwise, success=false is returned. The following shows a sample response of the APIBatchDeleteVolumeSnapshotMsg operation:

Error Response:

{
    "results": [
        {
            "error": {
                "code": "VOLUME_SNAPSHOT.1000",
                "description": "Snapshot is not in correct status for operation.",
                "details": "snapshot[uuid:e9c43724c6614aa488b63d6b33e30ebd, name:test1]'s status[Ready] is not allowed for message[org.zstack.header.storage.snapshot.VolumeSnapshotDeletionMsg], allowed status[Ready, Creating, Deleting]"
            },
            "snapshotUuid": "e9c43724c6614aa488b63d6b33e30ebd",
            "success": false
        },
        {
            "error": {
                "code": "VOLUME_SNAPSHOT.1000",
                "description": "Snapshot is not in correct status for operation.",
                "details": "snapshot[uuid:e9c43724c6614aa488b63d6b33e30ebd, name:test2]'s status[Ready] is not allowed for message[org.zstack.header.storage.snapshot.VolumeSnapshotDeletionMsg], allowed status[Ready, Creating, Deleting]"
            },
            "snapshotUuid": "63daa66726b24f9390216b8edf32190d",
            "success": false
        }
    ],
    "success": true
}

Successful Response:

{
    "results": [
        {
            "snapshotUuid": "1c8408e0f05d4fc39465d7db27d6bc32",
            "success": true
        },
        {
            "snapshotUuid": "e071e0ec42de4323bff23993a6a236d2",
            "success": true
        }
    ],
    "success": true
}

Long Job API Response

For error responses of long jobs, the value of the success field in the first layer is true. The value of the success field in inner layers vary depending on the sub-task result. If a sub-task succeeded, success=true is returned. Otherwise, success=false is returned. The following shows a sample response of the APIAddHostFromConfigFileMsg operation:

Error Response:

{
    "results": [
        {
            "error": {
                "code": "SYS.1006",
                "cost": "5ms",
                "description": "An operation failed",
                "details": "the host[10.0.231.23] ssh port[22] not open after 300 seconds, connect timeout",
                "elaboration": "错误信息: 物理机[10.0.231.23]的ssh端口[22]在 300 秒内未开放，连接超时",
                "location": "HostManagerImpl.java: send-connect-host-message (location:2/4)"
            },
            "ip": "10.0.231.23",
            "success": false
        },
        {
            "error": {
                "code": "SYS.1007",
                "description": "One or more API argument is invalid",
                "details": "已经存在一个管理IP是[10.0.93.160]的物理机"
            },
            "ip": "10.0.93.160",
            "success": false
        }
    ],
    "success": true
}

Successful Response:

{
    "results": [
        {
            "ip": "10.0.231.231",
            "success": true
        },
        {
            "ip": "10.0.93.160",
            "success": true
        }
    ],
    "success": true
}

Conclusion

The value of the success field in the first layer of the two categories of API responses istrue.
The value of the success field in the first layer indicates the result of a Restful API request. If the request succeeds, the value of the success field is true.
The value of the successfield in the inner layers indicates the result of a sub-task of a Restful API request. If a sub-task succeeds, succuess=true is returned for the sub-task. Otherwise, succee=false is returned for the sub-task.

Note: API responses displayed on the UI may be modified. For example, the successCount and failCount fields may be added to the API response.

PreviousIntroduction NextSDK Overview