With the IBM Spectrum Scale™ management API, you can develop scripts or applications to automate labor-intensive cluster management tasks. These APIs provide a useful way to integrate and use the IBM Spectrum Scale 4.2.3 system.

The IBM Spectrum Scale management API is a REST-style interface for managing IBM Spectrum Scale cluster resources. It runs on HTTPS and uses JSON syntax to frame data inside HTTP requests and responses.

The API implementation is based on the GUI stack. The GUI server manages and processes the API requests and commands. The following figure illustrates the API architecture.

Figure 1. IBM Spectrum Scale management API architecture

The following are the main features of the API architecture:

• Reuses the IBM Spectrum Scale GUI deployment's backend infrastructure, which makes introduction of new API commands easier.


• Uses the same role-based access that is available to authenticate and authorize the GUI
  users. No additional configuration is required to authenticate the API users.


• Deploys easily as the GUI installation takes care of the basic deployment.


• Fixes scalability issues and introduces new features such as filter and field parameters and supports paging.


• Highly scalable and can support large clusters with thousands of nodes.


• The APIs are driven by the same WebSphere® server and object cache that is used by the IBM Spectrum Scale GUI.

Functional overview

The IBM Spectrum Scale™ management API is a REST-style API that provides interoperability between a client
and server over a network. These APIs allow authenticated users to perform day-to-day storage management tasks.

The following list provides the salient features of the REST-style APIs:

• Resource-based


• Stateless


• Client-server


• Cacheable


• Layered system

REST is a resource-based service system in which requests are made to the resource’s Universal resources identifier (URI). This invokes a response from the resource in the JSON format. An IBM Spectrum Scale management API resource is a collection of all the objects of the same type in a cluster, such as all the filesets. A resource
element is an instance of a resource, such as a particular fileset named fileset1. The following example request ends with the resource filesets. It indicates that the particular operation affects all the filesets that are part of a file system named gpfs0.

https://198.51.100.1:443/scalemgmt/v2/filesystems/gpfs0/filesets

The following example ends with a resource followed by a resource element: filesets/fileset1. This indicates that the operation affects a particular fileset.

https://198.51.100.1:443/scalemgmt/v2/filesystems/gpfs0/filesets/fileset1

The kind of operations that can be performed on the resources or a resource element are directed by the HTTP methods such as GET, POST, PUT, DELETE. The following list provides the meanings of the basic HTTP methods used in the requests:

• GET: Reads a specific resource or a collection of resources and provides the details as the response.


• PUT: Updates a specific resource or a collection of resources.


• DELETE: Removes or deletes a specific resource.


• POST: Creates a resource.

For more information about the API requests and responses, see API requests and API responses.

Asynchronous job framework

In general, the runtime of an IBM Spectrum Scale CLI command is non-deterministic. Therefore, the API commands
run asynchronously and return a job ID, which can be used to query the status of the job using the /jobs URL. All jobs can be queried using "/jobs" command and a specific job can be queried using /jobs/{jobId}.

For more information see, Jobs: GET and Jobs/{jobId}: GET

The following example shows the job details returned in a POST operation.

The POST filesystems/{filesystemName}/filesets command creates a new fileset in the specified file system.

Request data:

curl -k -u admin:admin001 -X POST --header 'content-type:application/json' --header 'accept:application/json'

-d '{

"filesetName": "fset1",

"path":
"/mnt/gpfs0/fset1",

"owner": "scalemgmt",

"permissions": "700"

}'
'https://198.51.100.1:443/scalemgmt/v2/filesystems/gpfs0/filesets'

Response data:

{

"jobs" : [ {

"jobId" : 1000000000003,

"status" : "COMPLETED",

"submitted" : "2017-03-14
15:54:23,042",

"completed" : "N/A",

"request" : {

"data" : {

"filesetName" :
"fset1",

"owner" :
"scalemgmt",

"path" :
"/mnt/gpfs0/fset1",

"permissions" : 700

},

"type" : "POST",

"url" :
"/scalemgmt/v2/filesystems/gpfs0/filesets"

},

"result" : { }

} ],

"status" : {

"code" : 202,

"message" : "The request was
accepted for processing"

}

}

Installing and configuring IBM Spectrum Scale management API

The IBM Spectrum Scale™ management API implementation is based on the IBM Spectrum Scale GUI stack. Installation and configuration of GUI sets up the API infrastructure. That is, you do not need to perform any API-specific deployment procedures.

Ensure that the following tasks are completed to start using the IBM Spectrum Scale management API to monitor and manage the IBM Spectrum Scale system:

1. Install the GUI server. Use any of the following options to install the GUI:
   
   
   1. Manually installing IBM Spectrum Scale management GUI
   
   
   2. Installing IBM Spectrum Scale management GUI by using the spectrumscale installation toolkit
   
   


2. Initialize the GUI either by accessing the GUI through the browser or by using the /usr/lpp/mmfs/gui/cli/initgui command.


3. The default user name and password to access the IBM Spectrum Scale GUI is admin and admin001 respectively. Due to security reasons, it is recommended to change the default password after the first login. The password can be changed through the GUI or by using /usr/lpp/mmfs/gui/cli/chuser
   admin -p newPassword command.


4. Create new users and provide the required permissions. You can either use the Access > GUI Users GUI page or the usr/lpp/mmfs/gui/cli/mkuser command to create new users and assign roles. For more information on how to create GUI users and assigning user roles, see Managing GUI users.

Every API call to IBM Spectrum Scale needs a valid GUI user and password. For example, curl -k -u admin:admin001 -XGET -H 'content-type:application/json' 'https://<IP address>:443/scalemgmt/v2/info'.

The user roles assigned to the user determine actions that can be performed.

Upgrading IBM Spectrum Scale management API from 4.2.2 to 4.2.3.x

The management API Version 1 was introduced in the IBM Spectrum Scale 4.2.2 release and the API Version 2 is introduced in the 4.2.3 release. You cannot upgrade the IBM Spectrum Scale management API from 4.2.2 to 4.2.3 as the architecture and syntax are entirely different in these versions. If you are already using API in 4.2.2, uninstall the scalemgmt rpm and then install the 4.2.3 GUI rpms to start using the latest version.

IBM Spectrum Scale management API command reference

The following table lists the currently supported operations for each type of resource and resource element. The first and second columns list the resource type and the operation. The third column lists the resource and resource element terms that appear in the HTTPS request. The fourth column lists the HTTP method that is called to do the operation.

Table 1. Operations supported for resources and resource elements in management API.

For information about the API commands, see IBM Spectrum Scale management API commands.

You can also access the documentation corresponding to each API command from the GUI itself. The API documentation is available in the GUI at: https://<IP
address or host name of API server>:<port>/ibm/api/explorer/. For example: https://scalegui.ibm.com:443/ibm/api/explorer.

Using the IBM Spectrum Scale management API

The following examples shows how to use the API commands.

1. The GET ces/addresses command gets information about CES (Cluster Export Services) addresses.
   
   

   Request data:

   
   

   curl -k -u admin:admin001 -X GET --header 'accept:application/json' 'https://198.51.100.1:443/scalemgmt/v2/ces/addresses'

   
   
   

   Response data:

   
   

   {

     "cesaddresses" : [ {

       "cesAddress" : "198.51.100.35",

       "nodeName" : "mari-13.localnet.com"

     }, {

       "cesAddress" : "198.51.100.37",

       "nodeName" : "mari-12.localnet.com"

     }, {

       "cesAddress" : "198.51.100.31",

       "nodeName" : "mari-12.localnet.com"

     }, {

       "cesAddress" : "198.51.100.33",

       "nodeName" : "mari-14.localnet.com"

     }, {

       "cesAddress" : "198.51.100.27",

       "nodeName" : "mari-14.localnet.com"

     }

     ],

     "status" : {

       "code" : 200,

       "message" : "The request finished successfully"

     }

   }

   
   


2. The GET filesystems/filesystemName command gets information about a particular file system.
   
   

   Request data:

   
   
   

   curl -k -u admin:admin001 -X GET --header 'accept:application/json' 'https://198.51.100.1:443/scalemgmt/v2/filesystems/gpfs0?fields=:all:'

   
   

   Response data:

   
   

   {

     "status": {

       "code": "200",

       "message": "..."

     },

     "paging": {

       "next": "https://localhost:443/scalemgmt/v2/filesystems/gpfs0?lastId=1001"

     },

     "filesystems": [

       {

         "oid": "2",

         "uuid": "0A00641F:58982753",

         "name": "gpfs0",

         "version": "17.00",

         "type": "local",

         "createTime": "Mon Feb 06 08:35:47 2017",

         "block": {

           "pools": "system;data",

           "disks": "disk1;disk2",

           "blockSize": "262144",

           "metaDataBlockSize": "262144",

           "indirectBlockSize": "16384",

           "minFragmentSize": "8192",

           "inodeSize": "4096",

           "logfileSize": "4194304",

           "writeCacheThreshold": "0"

         },

         "mount": {

           "mountPoint": "/mnt/gpfs0",

           "automaticMountOption": "yes",

           "additionalMountOptions": "none",

           "mountPriority": "0",

           "driveLetter": "F",

           "remoteDeviceName": "gpfs0",

           "readOnly": "false"

         },

         "replication": {

           "defaultMetadataReplicas": "1",

           "maxMetadataReplicas": "2",

           "defaultDataReplicas": "1",

           "maxDataReplicas": "2",

           "strictReplication": "whenpossible",

           "logReplicas": "0"

         },

         "quota": {

           "quotasAccountingEnabled": "user;group;fileset",

           "quotasEnforced": "user;group;fileset",

           "defaultQuotasEnabled": "none",

           "perfilesetQuotas": "true",

           "filesetdfEnabled": "false"

         },

         "settings": {

           "blockAllocationType": "cluster",

           "fileLockingSemantics": "nfs4",

           "numNodes": "32",

           "exactMTime": "true",

           "suppressATime": "no",

           "fastEAEnabled": "true",

           "encryption": "false",

           "maxNumberOfInodes": "3211520",

           "is4KAligned": "true",

           "rapidRepairEnabled": "true",

           "stripeMethod": "round-robin",

           "stripedLogs": "true",

           "aclsemantics": "nfs4",

           "dmapienabled": "true"

         }

       }

     ]

   }

   
   


3. The POST filesystems/{filesystemName}/filesets command creates a fileset in the specified file system.
   

   Request data:

   
   

   curl -k -u admin:admin001 -X POST --header 'content-type:application/json' --header 'accept:application/json'

   
   

   -d '{
"filesetName": "fset1",
"path": "/mnt/gpfs0/fset1",
"owner": "scalemgmt",
"permissions": "700"
}'
'https://198.51.100.1:443/scalemgmt/v2/filesystems/gpfs0/filesets'

   
   Response data:
   

   {

     "jobs" : [ {

       "jobId" : 1000000000003,

       "status" : "COMPLETED",

       "submitted" : "2017-03-14 15:54:23,042",

       "completed" : "N/A",

       "request" : {

         "data" : {

           "filesetName" : "fset1",

           "owner" : "scalemgmt",

           "path" : "/mnt/gpfs0/fset1",

           "permissions" : 700

         },

         "type" : "POST",

         "url" : "/scalemgmt/v2/filesystems/gpfs0/filesets"

       },

       "result" : { }

     } ],

     "status" : {

       "code" : 202,

       "message" : "The request was accepted for processing"

     }

   }

   
   


4. The DELETE filesystems/{filesystemName}/snapshots/{snapshotName} command deletes the specified file system snapshot.
   

   Request URL:

   
   

   curl -k -u admin:admin001 -X DELETE --header 'accept:application/json' 'https://198.51.100.1:443/scalemgmt/v2/filesystems/gpfs0/snapshots/snap1' 

   
   

   Response data:

   
   

   {

     "status": {

       "code": "200",

       "message": "..."

     },

     "job": [

       {

         "result": {},

         "request": {

           "type": "DELETE",

           "url": "/scalemgmt/v2/filesystems/gpfs0/snapshots/snap1",

           },

         "jobId": "12345",

         "submitted": "2016-11-14 10.35.56",

         "completed": "2016-11-14 10.35.56",

         "status": "COMPLETED"

       }

   ]
   }

Reference

Acknowledgement

• Alexander Wolf-Reber - Development lead and architect, IBM Spectrum Scale GUI and API


• Andreas Koeninger - Scrum Master, IBM Spectrum Scale GUI and API


• Thorne T. Ventura - IBM Spectrum Scale GUI and API test automation