Examples
Examples
Each example below does the same thing, so you can pick the language you work in:
async=true), and wait for the job to finish.
Log out.
Run these against a test system. They create and delete a host named rest-demo-host.
In all three, replace storone.example.com with your system's management address, and the user name and password with your own.
About certificates. The examples skip TLS certificate verification (
-k,-SkipCertificateCheck,verify=False) so they work out of the box. For anything beyond a quick test, install your system's certificate on the client, or point the client at it, and leave verification on.
The conventions these examples rely on — where parameters go, what Status means, and how background jobs are tracked — are explained in Requests and responses and Asynchronous operations.
curl
This version uses jq to pick values out of the JSON responses.
BASE=https://storone.example.com
# 1. Log in and keep the session token
TOKEN=$(curl -sk -X POST "$BASE/login" \
-H "Content-Type: application/json" \
-d '{"Username": "alice", "Password": "<password>"}' | jq -r .SessionToken)
AUTH="Authorization: Bearer $TOKEN"
# 2. List hosts
curl -sk "$BASE/hosts/list" -H "$AUTH" | jq .
# 3. Create a host, and show its Status (should be "Ok")
curl -sk -X POST "$BASE/hosts/create" -H "$AUTH" \
-H "Content-Type: application/json" \
-d '{"Name": "rest-demo-host", "Iqn": "iqn.1993-08.org.example:rest-demo-host"}' | jq -r .Status
# 4. Delete it in the background, then find the job and wait for it
curl -sk -X DELETE "$BASE/hosts/delete?name=rest-demo-host&force=true&async=true" -H "$AUTH" | jq -r .Status
# The newest background job in this session:
JOB=$(curl -sk "$BASE/configurations/session/list?async=true&top=1&descendingOrder=true" -H "$AUTH" \
| jq '.Result | to_entries[0].value[0].Id')
while true; do
STATE=$(curl -sk "$BASE/configurations/session/list?jobids=$JOB" -H "$AUTH" \
| jq -r '.Result | to_entries[0].value[0].State')
if [ "$STATE" = "Success" ] || [ "$STATE" = "Failed" ]; then break; fi
sleep 2
done
curl -sk "$BASE/configurations/session/list?jobids=$JOB" -H "$AUTH" \
| jq '.Result | to_entries[0].value[0] | {Id, State, Message}'
# 5. Log out
curl -sk -X DELETE "$BASE/logout" -H "$AUTH" | jq -r .Status
PowerShell
This version needs PowerShell 7 or later. (Windows PowerShell 5.1 doesn't have -SkipCertificateCheck; trust the system's certificate on the machine instead and remove that switch.)
$base = "https://storone.example.com"
# 1. Log in and keep the session token
$login = Invoke-RestMethod -Method Post -Uri "$base/login" -SkipCertificateCheck `
-ContentType "application/json" `
-Body (@{ Username = "alice"; Password = "<password>" } | ConvertTo-Json)
$headers = @{ Authorization = "Bearer $($login.SessionToken)" }
# A small helper: call an endpoint, and stop if Status isn't "Ok"
function Invoke-S1 {
param([string]$Method, [string]$Path, $Body)
$req = @{ Method = $Method; Uri = "$base$Path"; Headers = $headers; SkipCertificateCheck = $true }
if ($Body) { $req.ContentType = "application/json"; $req.Body = ($Body | ConvertTo-Json) }
$r = Invoke-RestMethod @req
if ($r.Status -ne "Ok") { throw "$Method $Path failed: $($r.Status) $($r.ErrorMessage)" }
return $r
}
# 2. List hosts
(Invoke-S1 GET "/hosts/list").Result | ConvertTo-Json -Depth 5
# 3. Create a host
Invoke-S1 POST "/hosts/create" @{ Name = "rest-demo-host"; Iqn = "iqn.1993-08.org.example:rest-demo-host" } | Out-Null
# 4. Delete it in the background, then find the job and wait for it
Invoke-S1 DELETE "/hosts/delete?name=rest-demo-host&force=true&async=true" | Out-Null
function Get-S1Job($query) { ((Invoke-S1 GET "/configurations/session/list?$query").Result.PSObject.Properties | Select-Object -First 1).Value[0] }
$job = Get-S1Job "async=true&top=1&descendingOrder=true" # the newest background job in this session
while ((Get-S1Job "jobids=$($job.Id)").State -in "Pending", "Running") { Start-Sleep -Seconds 2 }
Get-S1Job "jobids=$($job.Id)" | Select-Object Id, State, Message
# 5. Log out
Invoke-S1 DELETE "/logout" | Out-Null
Python
This version uses the requests library (pip install requests).
import time
import requests
BASE = "https://storone.example.com"
session = requests.Session()
session.verify = False # for testing only; see the note on certificates above
# 1. Log in and keep the session token (a wrong password raises here, on the 401)
login = session.post(f"{BASE}/login", json={"Username": "alice", "Password": "<password>"})
login.raise_for_status()
session.headers["Authorization"] = "Bearer " + login.json()["SessionToken"]
def call(method, path, **kwargs):
"""Call an endpoint and stop if Status isn't "Ok"."""
response = session.request(method, BASE + path, **kwargs)
response.raise_for_status()
body = response.json()
if body["Status"] != "Ok":
raise RuntimeError(f'{method} {path} failed: {body["Status"]} {body.get("ErrorMessage")}')
return body
def first_item(body):
"""Result is an object with one property that holds the list of items."""
return next(iter(body["Result"].values()))[0]
# 2. List hosts
print(call("GET", "/hosts/list")["Result"])
# 3. Create a host
call("POST", "/hosts/create",
json={"Name": "rest-demo-host", "Iqn": "iqn.1993-08.org.example:rest-demo-host"})
# 4. Delete it in the background, then find the job and wait for it
call("DELETE", "/hosts/delete", params={"name": "rest-demo-host", "force": "true", "async": "true"})
job_id = first_item(call("GET", "/configurations/session/list",
params={"async": "true", "top": 1, "descendingOrder": "true"}))["Id"]
while True:
job = first_item(call("GET", "/configurations/session/list", params={"jobids": job_id}))
if job["State"] in ("Success", "Failed"):
break
time.sleep(2)
print(job["State"], job.get("Message"))
# 5. Log out
call("DELETE", "/logout")
Next steps
https://<management-address>/docs on your system to try endpoints interactively.
To see the REST form of a CLI command you already know, run examples generate --command "<command>" --convertToRest in the CLI.