Some requests take optional query parameters that modify or enhance the data returned. See the documentation for each resource for details. Not every resource supports every query parameter. This section documents only the common query parameters that will be used when a resource does implement the specified query parameter.
|
The props query parameter can be used on GET, POST, and PUT commands to allow the end users to access the metadata. The end user will request this capability by setting query parameter props to true. For GET and PUT operations, the returned JSON object will contain the required data with list of properties' metadata. For POST, only metadata will be returned to help the user to create a resource properly.
|
The limit query can be used on many GET commands that can return a large number of elements in order to limit the maximum number of elements returned.
For resources that support time values, the index can be a time value, such as 20170531T01:13:58, and must be expressed in UTC time.
The depth query parameter can be used with the GET command to retrieve a list of resources. It is used to specify the level of detail for the returned list. The greater depth number, more detail will be returned. For example:
/api/...?depth=0 – Return properties of node and only children names.
/api/...?depth=1 – Return properties of node, names, and properties of children, only names of grandchildren.
/api/...?depth=2 – Return properties of node, names, and properties of children, and depth=0 output of grandchildren.
Example request for query parameter depth:
GET /api/user/v1/users?depth=2 HTTP/1.1 Host: zfs-storage.example.com X-Auth-User: root X-Auth-Key: password-xxx
In this example, a list of users will be returned with details up to depth=2.
Example response:
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1558
X-Zfssa-Access-Api: 1.0
{"users":
[{
"name": "root",
"properties": {
"logname": "root",
"fullname": "Super-User",
"initial_password": "password",
"require_annotation": false
},
"children": [{
"name": "preferences",
"properties": {
"locale": "C",
"login_screen": "status/dashboard",
"session_timeout": 15,
"advanced_analytics": false
},
"children": [{
"name": "keys",
"properties": {},
"children": [],
"list": []
}],
"list": []
}],
"list": [],
"href": "/api/user/v1/users/root"
},
{
"name": "admin2",
"properties": {
"logname": "admin2",
"fullname": "Administrator",
"initial_password": "password",
"require_annotation": false,
"roles": ["basic"],
"kiosk_mode": false,
"kiosk_screen": "status/dashboard"
},
"children": [{
"name": "exceptions",
"properties": {},
"children": [],
"list": [{
"name": "auth-000",
"properties": {
"scope": "stat",
"drilldowns": "*",
"allow_create": false,
"allow_read": true
},
"children": [],
"list": []
},
{
"name": "auth-001",
"properties": {
"scope": "ad",
"name": "*",
"allow_domain": true,
"allow_workgroup": false
},
"children": [],
"list": []
}]
}, {
"name": "preferences",
"properties": {
"locale": "C",
"login_screen": "status/dashboard",
"session_timeout": 15,
"advanced_analytics": false
},
"children": [{
"name": "keys",
"properties": {},
"children": [],
"list": ["key-000"]
}],
"list": []
}],
"list": [],
"href": "/api/user/v1/users/admin2"
}]
}
The match_property-name=value query parameter can be used with the GET command to retrieve a list of resources. It returns a list of data that matches the specified property name and value. For example:
/api/...?depth=0&match_kiosk_mode=true – Return a filtered list for kiosk_mode is true with names of children.
/api/...?depth=1&match_kiosk_mode=true – Return a filtered list for kiosk_mode is true with details up to depth=1.
/api/...?depth=2&match_Fullname='Super*'&kiosk_mode=true – Return a filtered list for fullname containing Super and kiosk_mode is true with details up to depth=2.