Curl Rest Client

Language:

Curl clients must use curl version 7.34.0 or higher. Two common CLI-based HTTP clients are wget and curl. This section shows several examples of using curl to make RESTful API calls and similar functionality can be accomplished using wget.

Get Resource Data

This example shows how to use a simple HTTP GET request to obtain some JSON data:

$ curl --user ${USER}:${PASSWORD} -k -i https://hostname:215/api/nas/v1/pools/p1

 HTTP/1.1 200 OK
 Date: Tue, 23 Jul 2018 12:57:02 GMT
 Server: WSGIServer/0.1 Python/2.6.4
 Content-Length: 284
 Content-Type: application/json
 X-Zfs-Sa-Nas-Api: 1.0

{
   "pool": {
      "profile": "mirror",
      "name": "p1",
      "usage": {
         "available": 895468984832.0,
         "total": 895500681216.0,
         "dedupratio": 100,
         "used": 31696384.0
      },
      "peer": "00000000-0000-0000-0000-000000000000",
      "state": "online",
      "owner": "admin1",
      "asn": "314d252e-c42b-e844-dab1-a3bca680b563"
    }
}

Create a New Resource

This example shows how to send JSON data in a request to create a new resource:

$ curl --user ${USER}:${PASSWORD} -s -k -i -X POST -d @-  \
  -H "Content-Type: application/json" \
  https://zfs-storage.example.com:215/api/user/v1/users <<JSON
> {"logname": "rest_user",
> "fullname": "REST User",
> "initial_password": "password"}
> JSON

HTTP/1.1 201 Created
Date: Tue, 23 Jul 2018 13:07:37 GMT
Server: WSGIServer/0.1 Python/2.6.4
X-Zfs-Sa-Appliance-Api: 1.0
Content-Type: application/json
Content-Length: 357

{
   "user": {
      "logname": "rest_user",
      "fullname": "REST User",
      "initial_password": "password",
      "require_annotation": false,
      "kiosk_mode": false,
      "kiosk_screen": "status/dashboard",
      "roles": ["basic"],
      "exceptions": {},
      "preferences": {
         "href": "/api/user/v1/users/admin1/preferences",
         "locale": "C",
         "login_screen": "status/dashboard",
         "session_timeout": 15,
         "advanced_analytics": false,
         "keys": {}
      }
   }
}

Modify an Existing Resource

This example modifies a user's session timeout:

$ curl --user admin1:password -3 -s -k -i -X PUT \
  -H "Content-Type: application/json" -d @-  \
  https://zfs-storage.example.com:215/api/appliance/v1/users/admin1/preferences <<JSON
> {"session_timeout":60}
> JSON

HTTP/1.1 202 Accepted
Date: Wed, 24 Jul 2018 05:43:17 GMT
X-Zfs-Sa-Appliance-Api: 1.0
Content-Type: application/json
Content-Length: 0

{
    "preferences": {
        "href": "appliance/v1/users/admin1/preferences",
        "locale": "C",
        "login_screen": "status/dashboard",
        "session_timeout": 60,
        "advanced_analytics": false,
        "keys": {}
    }
}

Delete an Existing Resource

This command removes a user from the system:

$ curl --user ${USER}:${PASSWORD} -s -k -i -X DELETE \
  https://zfs-storage.example.com:215/api/appliance/v1/users/admin1
HTTP/1.1 204 No Content
Date: Tue, 23 Jul 2018 13:21:11 GMT
Server: WSGIServer/0.1 Python/2.6.4
X-Zfs-Sa-Appliance-Api: 1.0
Content-Length: 0