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.
|
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.
|
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 may 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 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.
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" }] }
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.