Skip to main content

Examples

Each example below does the same thing, so you can pick the language you work in:

  1. Log in and get a session token.
  2. List the hosts on the system.
  3. Create a test host and check that it worked.
  4. Delete it again in the background (async=true), and wait for the job to finish.
  5. 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

  • Browse the Endpoint Reference for the operation you need.
  • Open 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.

No comments to display