API reference

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

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.
  • Compute APIs
    List all the compute nodes
    GET /api/v1/compute
    Get specific compute node
    GET /api/v1/compute/<node-name>
    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
    Dashboard APIs
    File system storage capacity
    GET /api/v1/storage/scale/fsCapacity
    Backup capacity
    GET /api/v1/backupcapacity
    Backup job summary
    GET /api/v1/backupjobsummary
    Get OpenShift pods
    GET /api/v1/dashboard/openshift/pods
    Get OpenShift PVs
    GET /api/v1/dashboard/openshift/pvs
    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."
    }
    }
  • 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.