Query Parameters

Language:

Some requests will take optional query parameters that will modify or enhance the data returned. See the documentation for each resource for details. Not every resource will support every query parameter. This section only documents the common query parameters that will be used when a resource does implement the specified query parameter.

Table 2 Common Query Parameters

Parameter	Description
props=true	List property metadata for a resource (default is false)
limit=`n`	Limit the number of list elements returned
start=`n`	Index number (or time) used to begin element data returned
depth=`n`	Index number that specifies the level of detail for the returned data
match_`Property-Name`=`Value`	List the data matching the specified property name and value

Query Parameter: props

The props query parameter can be used on GET, POST, 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.

Table 3 Property Metadata Values

Property	Description
name	Property name
label	Description of property
immutable	Flag indicating that property cannot be modified
type	Property type: String, Integer, Boolean...
choices	For enumerated properties, an array of available values

Query Parameter: limit

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.

Query Parameter: start

For resources that support time values, the index may be a time value, such as "20170531T01:13:58", and must be expressed in UTC time.

Query Parameter: depth

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 instance:

/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.

Note - The depth query parameter is not supported for listing logs using /api/log/v1, and listing pools, projects, filesystems, and LUNS using /api/storage/v1.

Example request for query parameters depth:

GET /api/user/v1/users?depth=2 HTTP/1.1                    
Host: zfs-storage.example.com
X-Auth-User: root
X-Auth-Key: letmein-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": "DummyPassword",
		"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": "tom",
	"properties": {
		"logname": "tom",
		"fullname": "Tommy",
		"initial_password": "DummyPassword",
		"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/tom"
    }]
}

Query Parameter: match

The match_Property-Name=Value query parameter can be used with the GET command to retrieve a list of resources. It will return a list of data matching the specified property name and value. For instance:

/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.

Note - The match_Property-Name=Value query parameter is not supported for listing logs using /api/log/v1, and listing pools, projects, filesystems, and LUNS using /api/storage/v1.