Curl Rest Client

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://zfssa.example.com:215/api/nas/v1/pools/gold

 HTTP/1.1 200 OK
 Date: Tue, 23 Jul 2013 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": "gold",
      "usage": {
         "available": 895468984832.0,
         "total": 895500681216.0,
         "dedupratio": 100,
         "used": 31696384.0
      },
      "peer": "00000000-0000-0000-0000-000000000000",
      "state": "online",
      "owner": "tanana",
      "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://zfssa-host.example.com:215/api/user/v1/users <<JSON
> {"logname": "rest_user",
>  "fullname": "REST User",
>  "initial_password": "letmein"}
> JSON

HTTP/1.1 201 Created
Date: Tue, 23 Jul 2013 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": "DummyPassword",
      "require_annotation": false,
      "kiosk_mode": false,
      "kiosk_screen": "status/dashboard",
      "roles": ["basic"],
      "exceptions": {},
      "preferences": {
         "href": "/api/user/v1/users/larry/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 larry:letmein -3 -s -k -i -X PUT \
  -H "Content-Type: application/json" -d @-  \
  https://tanana:215/api/appliance/v1/users/larry/preferences <<JSON
> {"session_timeout":60}
> JSON
HTTP/1.1 202 Accepted
Date: Wed, 24 Jul 2013 05:43:17 GMT
X-Zfs-Sa-Appliance-Api: 1.0
Content-Type: application/json
Content-Length: 0

{
    "preferences": {
        "href": "appliance/v1/users/larry/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://tanana:215/api/appliance/v1/users/jschwartz

HTTP/1.1 204 No Content
Date: Tue, 23 Jul 2013 13:21:11 GMT
Server: WSGIServer/0.1 Python/2.6.4
X-Zfs-Sa-Appliance-Api: 1.0
Content-Length: 0