Using RESTfull API against IBM Storage Virtualize

So what is RestAPI or RESTFullAPI? ☁️
As stated in IBM Doc and RestAPI Explorer.

The Storage Virtualize Representational State Transfer (REST) model Application Programming Interface (API) consists of command targets that are used to retrieve system information and to create, modify, and delete system resources. These command targets allow command parameters to pass through unedited to the IBM Storage Virtualize command-line interface, which handles parsing parameter specifications for validity and error reporting. Use Hypertext Transfer Protocol Secure (HTTPS) to successfully communicate with the RESTful API server.

So it’s a way to send commands to the SpecV OS in a programmatic way, this way of using an API to communicate to software has been around for a while now and “is” the common and known way for programmers to write code against. By sending an API call, it will return a standardized code for success or failure or something between. long-running tasks can be checked regularly with an ID, and the output is in JSON format (normally).

There are many ways that you can send commands using REST APIs, in this part I’m we are going to use the “explorer” that uses CURL, and then we most likely revisit this and use python.

FYI. The SpecV Ansible modules are using the RestAPI interface, which is written in Python.

For more information and documentation check out IBM Doc at: https://www.ibm.com/docs/en/flashsystem-9x00/8.6.x?topic=861-storage-virtualize-restful-api

There is also a good article over at Barry’s blog, but keep in mind this is written for v0 of the interface, still valid but there are major enhancements since.
https://barrywhytestorage.blog/2020/08/03/tips-and-tricks-using-the-spectrum-virtualize-rest-api/

IBM Storage Virtualize REST API Explorer:

In version, 8.4.2. code of Storage Virtualize the RESTFulAPI function got an “overhaul” and have now more of a common usage pattern that is used elsewhere.

And one many parts that are improved is the RestAPI Explorer to help users get started.

REST API Explorer
REST API documentation is available on IBM Documentation web page. Support also can be found directly on the system within the REST API Explorer. The REST API Explorer is based on the OpenAPI/Swagger UI and runs within a browser from SpecV. It offers an easy way to become familiar with the API and to test the commands that it contains.

To access the REST API Explorer, enter the following URL in a browser:
https://<SpecV_ip_address | FQDN>:7443/rest/explorer

After login in you will be greeted with some example that is using CURL (v8.5)

Authenticate

To be able to run RestAPI calls, we need to authenticate.
Some system support using the UserName, Password or a Secret. for Storage Virtualize we will use an access token that the system is generate. To get hold of that access token we need run /auth post.

Then we should receive response code 200 and a response body that should say token:

If not check the error code, and the response body: it could be the wrong password or the user doesn’t have the right permissions.

The token remains authorized only for one hour even if the token is unused. After one hour, an error code of 403 occurs that indicate the loss of authorization. Use the /auth command target to reauthenticate with the user name and password. This can be changed.

Copy the string after token: and without quotes, as in my case:
eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJpYXQiOjE2NjMxNTM2MTgsImV4cCI6MTY2MzE1NzIxOCwianRpIjoiMjczYjRmMmEyMzNkYTZjNjgy-shorten-down

Go down to lsvdisk, and press “try it out”:

Copy in the string to X-Auth-Token

Change then the string in
filtervalue to id=1 or name=yourvdiskname
units: GB

the id is the id of the vdisk.

The output should be code 200 and data about the vdisk id 1

There will also be an example of the command sent in the Curl section

curl -X POST "https://10.33.7.56:7443/rest/v1/lsvdisk" -H  "accept: application/json" -H  "X-Auth-Token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJpYXQiOjE2NjQyNzYxMzQsImV4cCI6MTY2NDI3OTczNCwianRpIjoiOWM3YWRhNGY5ZWQ5ZTNkMzhmMDAwZjcyMjIwNjQxMTMiLCJzdiI6eyJ1c2VyIjoic3VwZXJ1c2VyIn19.J1UPgWNhhNOSUW2bm-QqXVLA2WCnn6CgaKmsMNRaUHmaSrzy7YKJ-3xX3nn5XBr-dmdtt0m8CwvPifq4h-VYUQ" -H  "Content-Type: application/json" -d "{\"filtervalue\":\"id=1\",\"unit\":\"gb\"}"

If you are familiar with SpecV CLI you will recognise the Syntax, we are using the filtervalue to filter the disk with id=1 and unit in GB

-d "{\"filtervalue\":\"id=1\",\"unit\":\"gb\"}"

we can use the same filter for other attrib like give all vdisk that is pool/mdisk_grp_name: FS840

{
 “filtervalue”: “mdisk_grp_name=FS840–1”,
 “unit”: “gb”
}

This list of all volumes in the pool FS840-1

[
  {
    "id": "0",
    "name": "pvc_volume-disk.raw-7f936ea1-44f8",
    "IO_group_id": "0",
    "IO_group_name": "io_grp0",
    "status": "online",
    "mdisk_grp_id": "0",
    "mdisk_grp_name": "FS840-1",
    "capacity": "120.00GB",

    "volume_name": "pvc_volume-disk.raw-7f936ea1-44f8",
    "function": "",
    "protocol": ""
  },
  {
    "id": "1",
    "name": "vmware_svc02_fs840_1_prod_flash02_new_vmfs",
    "IO_group_id": "0",
    "IO_group_name": "io_grp0",
    "status": "online",
    "mdisk_grp_id": "0",
    "mdisk_grp_name": "FS840-1",

    "volume_name": "vmware_svc02_fs840_1_prod_flash02_new_vmfs",
    "function": "",
    "protocol": "scsi"
  },
  {

No filters

To not have any attributes, you should rest remove all info inside brackets and also the brackets.

{

}

/lsvdisk/{id}

To only show info about a specific device/ID there will be an {id}, example is /lsvdisk/{id}

PS: Add -k to use insecure

Create a thin volume /mkvdisk

There is a lot of variable in the mkvdisk, however, we don't need to populate the all.

{
  "name": "string",
  "mdiskgrp": "string",
  "fmtdisk": true,
  "nofmtdisk": true,
  "size": 0,
  "iogrp": "string",
  "vtype": 0,
  "mdisk": 0,
  "node": "string",
  "unit": "string",
  "cache": 0,
  "udid": "string",
  "rsize": "string",
  "warning": "string",
  "autoexpand": true,
  "grainsize": 0,
  "import": true,
  "copies": 0,
  "syncrate": 0,
  "createsync": true,
  "easytier": 0,
  "tier": 0,
  "mirrorwritepriority": 0,
  "accessiogrp": "string",
  "compressed": true,
  "deduplicated": true
}

If you want to know more about what variable you want/need you can create a test volume in the GUI and copy out the command. like this one for Thin volume.

svctask mkvdisk -autoexpand -cache readwrite -grainsize 256 -iogrp io_grp0 -mdiskgrp 0 -name testvolume -rsize 2% -size 22548578304 -unit b -warning 80%

This will result in the following for “Request Body.”

{
  "name": "restapitest-2",
  "mdiskgrp": "FS840-1",
  "size": 20,
  "iogrp": "io_grp0",
  "unit": "gb",
  "rsize": "2%",
  "warning": "80%",
  "autoexpand": true,
  "grainsize": 256
}

In SpecV Gui we can search for the volume and verify it’s created.

Map the Volume against a Host /mkvdiskhostmap/{id}

When mapping the volume and using the /mkvdiskhostmap/{id}
then the {id} is the VolumeID, and in my case, it’s 91 for the restapitest-2 volume. and then you specify the hostname in the body: "host:" "restapi"

Let us check with RestAPI what volumes are mapped. /lshostvdiskmap/{id}

I know that the host restapihost has the ID 29, so I can check directly that host with /lshostvdiskmap/{id} and no body.

The output should show something like this, and it has the volume mapped

Hope this was informative and see you next time. 🕵

Some more information about Storage Virtualize and CURL

Each curl example takes the following form:

curl -L -X POST https://system_ip:7443/rest/v1/target -H header_1 -H header_2 data-raw ‘JSON’

Where the following definitions apply:

• POST is the only HTTPS method that the Storage Virtualize RESTful API supports.
• system_ip is the IP address to which you are sending requests.
• v1 is version 1 of the API. (0 is the first version)
• target is the target object of commands, which includes any object IDs, names, and parameters.
• Headers (header_1 ) are individually specified HTTP headers (for example, Content-Type and X-Auth-Token).
• — data-raw is followed by JSON input (for example, '{"name": "password"}').

The system supports configuring a session between 10 minutes to 2 hours. However, the default single session lasts a maximum of 1 hour. If the maximum allotted time is reached, an error code 403 occurs that indicate the loss of authorization. Also, the token expiry is configurable and can be set between 10–120minutes. .

PS: Consider the following:

Note: Compatibility with an earlier version is implemented by auto redirection of nonversioned requests to v0. It is recommended to use versioned endpoints for guaranteed behavior
https://SpecV_ip_address:7443/rest/target uses API v0
https://SpecV_ip_address:7443/v0/rest/target uses API v0
https://SpecV_ip_address:7443/v1/rest/target uses API v1

• 200: Ok
• 400: BadRequest
• 401: Unauthorized
• 403: Forbidden
• 404: NotFound
• 409: Conflict
• 429: TooManyRequests
• 500: InternalServerError
• 502: BadGateway