API reference

List of all REST API references for IBM Storage Fusion HCI System.

For authentication of IBM Storage Fusion REST APIs, ensure you have a valid Red Hat® OpenShift® Container Platform bearer token in Authorization header:

For example,

Authorization : Bearer sha256~4rpK-5GEwvgGKnXbBtMJ9dcaRDhIqOxt5BihZ1NVt20
IBM Storage Fusion console route is the host for all these APIs. To access the console route, do the following steps:
  1. Log in to Red Hat OpenShift Container Platform.
  2. Go to Network > Routes page.
  3. In the Routes page, search for Console. Ensure that you are in ibm-spectrum-fusion-ns project.
    Note: All the APIs mentioned in swagger are not applicable to IBM Storage Fusion HCI System.

IBM Storage Fusion appliance management API

Compute APIs
List of compute monitoring CRs
GET /api/v1/compute-monitorings
Get a specific ComputeMonitoring CR 
GET /api/v1/compute-monitorings/<node-name>
List of ComputeConfiguration CRs
GET /api/v1/compute-configurations
Enable maintenance mode for compute node 
POST /api/v1/compute/update/maitenancemode/<node-name>
Payload: 
{"maintenanceMode":"true"}
Power operation for compute node
POST /api/v1/compute/update/poweroperation/<node-name>
Payload:
{"maintenanceMode":"true"}
Note: The node must be in maintenance mode before calling this API. To enable the maintenance mode, call the Enable maintenance mode for compute node API.
Add new compute node
POST /api/v1/computeconfig
Payload: 
[{"linkLocal":"<linklocaladdress","ru":"<RUnumber>","ibmSerialNumber":"<ibmserialnumber>","rackSerialNumber":"<rackname>"}]

To check the added node, check the successNodes field in the response. An empty list means that the compute node failed to add to the cluster.

Add node to storage cluster (scale out)
PUT /api/v1/compute/scaleout
Payload: 
{"scaleOutNodes":"compute-0,compute-2,compute-3"}

To confirm success of scale out, call the GET compute node API.

Check compute node storage
GET /api/v1/addstorage/info
Add storage disks (scale up)
PUT /api/v1/compute/scaleup
This API is applicable only if additional storage disks are available. 
GET /api/v1/addstorage/info before this.
For successful scale, check storage information. To check the information, call the Check compute node storage API before and after this PUT API call.
Networking APIs
Note: If you using Alternative network configuration, then the links related APIs are not applicable.
List all network switches 
GET /api/v1/network/switches
List all network VLANs
GET /api/v1/network/vlans
List all network links
GET /api/v1/network/links
List all network switch commands
GET /api/v1/network/listcommands
Run network switch command
GET /api/v1/networkcommands/<switch-name>/<command>
Create new VLAN 
POST /api/v1/network/vlans/rack-vlans/add/
Payload: 
{"vlanId":<vlan-id>,"vlanName":<vlan-name> ,"vlanType":<vlan-type>,"multipleLinks": <yes/no>}
Update VLAN 
POST /api/v1/network/vlans/rack-vlans/update/<vlan-id>
Payload: 
{"vlanId":<vlan-id>,"vlanName":<vlan-name> ,"vlanType":<vlan-type>,"multipleLinks": <yes/no>}
Create new link 
POST /api/v1/network/links/rack-links/add/
Payload: 
{"name":<link-name> ,"ports":<port>,"vlanType": <type>,"transceiver":<transceiver-value> ,aggregation":true,"nativeVlan":<native-vlan-name>,"vlanNames":<vlan-names> }
Edit the link 
POST /api/v1/network/links/rack-links/update/<uuid>
Payload: 
{"name":<link-name> ,"ports":<port>,"vlanType": <type>,"transceiver":<transceiver-value> ,aggregation":true,"nativeVlan":<native-vlan-name>,"vlanNames":<vlan-names> }
Upgrade
IBM Storage Fusion upgrade status
GET /api/v1/upgrade
Active file management (AFM) APIs
Retrieve the authorization token
For the CURL command, see Active file management (AFM) fileset creation
Retrieve the filesystem name (filesystem_name) that is mounted on the OpenShift Container Platform cluster: 
curl -k -H "Authorization:Token <token retreived from the previous command>" -X GET --header 'content-type:application/json' https://<spectrum_scale_gui_route>/scalemgmt/v2/filesystems
{
  "filesystems" : [ {
    "name" : "ibmspectrum-fs"
  } ],
  "status" : {
    "code" : 200,
    "message" : "The request finished successfully."
  }
Example: 

curl -k -H "Authorization:Token 07b0a89c-5a62-4b8d-b709-b5b51b2a394c" -X GET --header 'content-type:application/json' https://ibm-spectrum-scale-gui-ibm-spectrum-scale.apps.isf.ibm.com/scalemgmt/v2/filesystems
{
"filesystems" : [ {
"name" : "ibmspectrum-fs"
} ],
"status" : {
"code" : 200,
"message" : "The request finished successfully."
}
Create AFM fileset
curl -k -H "Authorization:Token <“Token Value> -X POST --header 'content-type:application/json' --header 'accept:application/json' -d '{

    "filesetName": “<"Name of fileset">”,
    "path": “<"filesystem mount point">/<"fileset name">",
    "afmTarget": “<"NFS export path">”,
    "afmMode": "independent-writer"
    }' <"Scale route URL">/scalemgmt/v2/filesystems//filesets
    {
    "jobs" : [ {
    "jobId" : 2000000011591,
    "status" : "RUNNING",
    "submitted" : "2023-01-12 12:33:46,219",
    "completed" : "N/A",
    "runtime" : 3,
    "request" : {
    "data" : {
    "afmMode" : "independent-writer",
    "afmTarget" : “<"NFS export path">”,
    "filesetName" : “<"fileset Name">”,
    "path" : "<"filesystem mount point">/<"fileset name">"
    },
    "type" : "POST",
    "url" : "/scalemgmt/v2/filesystems//filesets"
    },
    "result" : { },
    "pids" : [ ]
    } ],
    "status" : {
    "code" : 202,
    "message" : "The request was accepted for processing."
    }
    }
Example: 

curl -k -H "Authorization:Token 07b0a89c-5a62-4b8d-b709-b5b51b2a394c" -X POST --header 'content-type:application/json' --header 'accept:application/json' -d '{

    "filesetName": "afmScale",
    "path": "/mnt/ibmspectrum-fs/afmScale",
    "afmTarget": "nfs://9.30.44.36/mnt/fs1/fset1",
    "afmMode": "independent-writer"
    }' https://scalemgmt/v2/filesystems/ibmspectrum-fs/filesets
    {
    "jobs" : [ {
    "jobId" : 2000000011591,
    "status" : "RUNNING",
    "submitted" : "2023-01-12 12:33:46,219",
    "completed" : "N/A",
    "runtime" : 3,
    "request" : {
    "data" : {
    "afmMode" : "independent-writer",
    "afmTarget" : "nfs://9.30.44.36/mnt/fs1/fset1",
    "filesetName" : "afmScale",
    "path" : "/mnt/ibmspectrum-fs/afmScale"
    },
    "type" : "POST",
    "url" : "/scalemgmt/v2/filesystems/ibmspectrum-fs/filesets"
    },
    "result" : { },
    "pids" : [ ]
    } ],
    "status" : {
    "code" : 202,
    "message" : "The request was accepted for processing."
    }
    }
Get cache status

curl -k -H "Authorization:Token “<"Token value">” -X GET --header 'content-type:application/json' <"Scale Route URL">/scalemgmt/v2/filesystems/<"filesystem Name">/afm/state

For eg:
Example: 

curl -k -H "Authorization:Token 07b0a89c-5a62-4b8d-b709-b5b51b2a394c" -X GET --header 'content-type:application/json' https://ibm-spectrum-scale-gui-ibm-spectrum-scale.apps.isf-racki.rtp.raleigh.ibm.com/scalemgmt/v2/filesystems/ibmspectrum-fs/afm/state
{
"filesetAfmStateList" : [ {
"cacheState" : "Active",
"filesetName" : "afmfsetnfs",
"filesystemName" : "ibmspectrum-fs"
}, {
"cacheState" : "Active",
"filesetName" : "afmpallavi",
"filesystemName" : "ibmspectrum-fs"
}, {
"cacheState" : "Active",
"filesetName" : "afms",
"filesystemName" : "ibmspectrum-fs"
}, {
"cacheState" : "Active",
"filesetName" : "cosfset1",
"filesystemName" : "ibmspectrum-fs"
}, {
"cacheState" : "Active",
"filesetName" : "afmScale",
"filesystemName" : "ibmspectrum-fs"
}, {
"cacheState" : "Active",
"filesetName" : "afmScalePal",
"filesystemName" : "ibmspectrum-fs"
}, {
"cacheState" : "Active",
"filesetName" : "afmScaleS",
"filesystemName" : "ibmspectrum-fs"
} ],
"status" : {
"code" : 200,
"message" : "The request finished successfully."
}
}
Get job status
curl -k -H "Authorization:Token <“<"Token Value">” -X GET --header 'content-type:application/json' <"Scale Route URL">/scalemgmt/v2/jobs/
Example: 

curl -k -H "Authorization:Token 07b0a89c-5a62-4b8d-b709-b5b51b2a394c" -X GET --header 'content-type:application/json' https://ibm-spectrum-scale-gui-ibm-spectrum-scale.apps.isf-racki.rtp.raleigh.ibm.com/scalemgmt/v2/jobs/2000000011591
{
"jobs" : [ {
"jobId" : 2000000011591,
"status" : "COMPLETED",
"submitted" : "2023-01-12 12:33:46,219",
"completed" : "2023-01-12 12:33:55,845",
"runtime" : 9626,
"request" : {
"data" : {
"afmMode" : "independent-writer",
"afmTarget" : "nfs://9.30.44.36/mnt/fs1/fset1",
"filesetName" : "afmScale",
"path" : "/mnt/ibmspectrum-fs/afmScale"
},
"type" : "POST",
"url" : "/scalemgmt/v2/filesystems/ibmspectrum-fs/filesets"
},
"result" : {
"progress" : [ ],
"commands" : [ "mmcrfileset 'ibmspectrum-fs' 'afmScale' --inode-space new --inode-limit '1M:50K' --allow-permission-change 'chmodAndSetAcl' -p 'afmTarget=nfs://9.30.44.36/mnt/fs1/fset1' -p 'afmMode=independent-writer' ", "mmlinkfileset 'ibmspectrum-fs' 'afmScale' -J '/mnt/ibmspectrum-fs/afmScale' " ],
"stdout" : [ "EFSSG0070I File set afmScaleS created successfully.", "EFSSG0078I File set afmScale successfully linked.\n" ],
"stderr" : [ ],
"exitCode" : 0
},
"pids" : [ ]
} ],
"status" : {
"code" : 200,
"message" : "The request finished successfully."
}
}

Serviceability APIs

IBM Call Home APIs
Get IBM Call Home data 
GET /api/v1/callhome
GET response: 
{
    "context": "",
    "clusterName": "isf-rackb",
    "domainName": "rtp.raleigh.ibm.com",
    "organization": "ABS_Corp_Dummy",
    "customerid": "2434-4343",
    "email": "test_user@in.ibm.com",
    "customername": "Test User",
    "servicetype": "fullService",
    "agreesprivacy": true,
    "customeraddress": "",
    "contact": "(000)-123456-78",
    "machineaddress": "13th Street. 47 W 13th St, New York, NY 10011, USA.",
    "machinezip": "123456",
    "machinecity": "Newyork",
    "machinestate": "Newyork",
    "machinecountry": "US",
    "skipCallHome": false,
    "isBYOS": false
}
Update IBM Call Home data 
PUT /api/v1/callhome/update

The payload is the same as the response to GET Call Home Data. All the fields are mandatory, even when we plan to update a few of them. Sending an incomplete payload may result in an error.

If Call Home is not configured, then the GET does not return data.
{
	"agreesPrivacy": true,
	"servicetype": "fullService",
	"organization": "ABS_Corp_Dummy",
	"customerid": "2434-4343",
	"customername": "Test User",
	"contact": "(000)-123456-78",
	"email": "test_user@in.ibm.com",
	"machineaddress": "13th Street. 47 W 13th St, New York, NY 10011, USA. 20 Cooper Square",
	"machinecountry": "US",
	"machinecity": "Newyork",
	"machinestate": "Newyork",
	"machinezip": "123456"
}
Turn off Call Home 
PUT /api/v1/callhome/turnoff
Payload: 
data: {
 	     removeconfig: "true"
	    }
Event APIs
Get Events 
GET /api/v1/eventmanager/events?${queryString}
Get event categories 
GET /api/v1/eventmanager/eventcats
Get event stats 
GET /api/v1/eventmanager/eventstats?${query}

For example, query 'Fixed=false' gets unfixed events

Mark an event as fixed
PUT /api/v1/eventmanager/events/${eventId}
Payload: 
{ annotations: { isf_fixed: 'true' } }
Note: This API is applicable only for unfixed and open Call Home tickets.
Log APIs
Get all log collector sets
GET /api/v1/logcollector
Create log collector set
POST /api/v1/logcollector
Payload: 
{"requests":{"storage":{"type":"list-entry","source-list":"isf-collection-sets","list-entry":"storage-sds"}}}
Payload for OpenShift Data Foundation (ODF):
{
 "requests": {
   "odf": {
     "type": "list-entry",
     "source-list": "isf-collection-sets",
     "list-entry": "odf-sds"
   }
 }
}
Response:
{"jobid":"odf-20221103062933"}

The jobid returned by POST call is used for getting the status.

For example: 
GET /api/v1/logcollector/odf-20221103062933
Log set download
GET /api/v1/logcollector/<job-id>/results

This GET command downloads log sets.

Delete log set 
Delete /api/v1/logcollector/${jobid}
Note: Sometimes, though the APIs return 200, the operation for PUT and POST may be unsuccessful. In such cases, use other corresponding GET APIs to confirm the operation.

Refer to the Backup and restore (legacy) commands for the backup and restore APIs.

Services API

For Backup & Restore service APIs, see Backup and restore commands.

For Data Cataloging service APIs, see Data Cataloging REST APIs.