Overview

The TS7700 REST model Application Programming Interface (API) consists of commands that are used to read system resources. Hypertext Transfer Protocol Secure (HTTPS) is used to communicate with the RESTful API server.

RESTful API uses the operational method HTTP GET to query read operations.

Note: TS7700 RESTful API currently supports only GET method for all the resources except for authentication where POST method is used.

URL structure

The URL structure for an operation is https://ip_address/api/vX/command

where,
  • ip_address is the IP address of the TS7700 storage system.
  • api is the API application name.
  • vX is the version X of the API.
  • command is the resource that is targeted for the operation.
Note:
  • The URL should be encoded as documented in RFC 3986.
  • If a version supersedes an existing version of an API, then the new version will not be compatible with the previous versions. The older version will still be available for use.
  • The default port number is 443, and port number 80 is disabled.
  • The request and responses are in JavaScript Object Notation (JSON) format.
  • From release 5.4PGA1 (8.54.1.x), the RESTful API response supports the response in Comma-Separated Values (CSV) format.

Data types

RESTful API uses the following data types.

Boolean
Boolean attributes are provided as true or false.
Integer
Integer is a whole number that can be positive or negative.
Number
A fractional number is formatted as a double or a float.
String
Alphanumeric sequence of letters and/or numbers
Array
A list of values.

Content Type

  • How to get the response in CSV format

    To get the response in CSV format, the GET request needs to specify "Content-Type: text/csv". The default Content-Type is application/json.

  • CSV response format

    • The response includes the column names and the data (keys and values in JSON format). The 1st line is always filled with the column name and 2nd+ lines provide the corresponding data.

    • The column names are provided in three different formats:

      1. If we have no nested values in JSON response, the name of keys are directly provided in CSV format.

      2. If we have nested values but it does not provide any array (list), the nested column name is provided with '_' delimiter. For example, dataClasses with v2 provides lwormRetentionOptions with the nested values. The column name is: lwormRetentionOptions_retentionType.

      3. If we have nested values and it provides the array (list), the nested column name is provided with '_' delimiter and index. For example, storageClasses provides clusterSettings with arrays. The column name is: clusterSettings_0_cluster.

  • Empty column

    If JSON output provides empty value, CSV output does not provide the corresponding column name.

  • Note: The order on column name is in alphabetical order.
  • How to specify CSV format
    • The format of CSV format is (key (column name) and values)

      Example of CSV format :

      
      $ curl -k -s "https://popcorn.tuc.stglabs.ibm.com/api/v1/cacheDrives" -H "Content-Type: text/csv" -H "Authorization: Bearer $token"
      capacity,cluster,dataRate,driveId,driveSpeed,enclosureId,encryption,fips,firmwareVersion,id,interface,mediaType,partNumber,serialNumber,slotId,status,stringId
      "9.0TB",7,"12Gb",23,7200,1,null,null,"KCP5","c7s0e1t1","tierNearline","hdd","02XV954","S00VN576",1,"online",0
      "9.0TB",7,"12Gb",9,7200,1,null,null,"KCP5","c7s0e1t1","tierNearline","hdd","02XV954","ZRT0MJNL",1,"online",0
      "9.0TB",7,"12Gb",12,7200,1,null,null,"KCP5","c7s0e1t1","tierNearline","hdd","02XV954","ZRT0L544",1,"online",0
      "9.0TB",7,"12Gb",27,7200,1,null,null,"KCP5","c7s0e1t1","tierNearline","hdd","02XV954","S00VN576",1,"online",0
      "9.0TB",7,"12Gb",24,7200,1,null,null,"KCP5","c7s0e1t1","tierNearline","hdd","02XV954","S00VN576",1,"online",0
      "9.0TB",7,"12Gb",28,7200,1,null,null,"KCP5","c7s0e1t1","tierNearline","hdd","02XV954","S00VN576",1,"online",0
      "9.0TB",7,"12Gb",30,7200,1,null,null,"KCP5","c7s0e1t1","tierNearline","hdd","02XV954","S00VN576",1,"online",0
      "9.0TB",7,"12Gb",21,7200,1,null,null,"KCP5","c7s0e1t1","tierNearline","hdd","02XV954","S00VN576",1,"online",0
      "9.0TB",7,"12Gb",22,7200,1,null,null,"KCP5","c7s0e1t1","tierNearline","hdd","02XV954","S00VN576",1,"online",0
      
      $ curl -k -s "https://popcorn.tuc.stglabs.ibm.com/api/v1/storageClasses" -H "Content-Type: text/csv" -H "Authorization: Bearer $token"
      clusterSettings_0_cluster,clusterSettings_0_description,clusterSettings_0_partition,clusterSettings_0_premigrationSettings,clusterSettings_0_premigrationSettings_preference,clusterSettings_0_premigrationSettings_premigrationDelayTime,clusterSettings_0_premigrationSettings_premigrationDelayTimeAfter,clusterSettings_0_removalSettings,clusterSettings_0_removalSettings_preference,clusterSettings_0_removalSettings_retentionTime,clusterSettings_0_removalSettings_retentionTimeAfter,clusterSettings_1_cluster,clusterSettings_1_description,clusterSettings_1_partition,clusterSettings_1_premigrationSettings,clusterSettings_1_premigrationSettings_preference,clusterSettings_1_premigrationSettings_premigrationDelayTime,clusterSettings_1_premigrationSettings_premigrationDelayTimeAfter,clusterSettings_1_removalSettings,clusterSettings_1_removalSettings_preference,clusterSettings_1_removalSettings_retentionTime,clusterSettings_1_removalSettings_retentionTimeAfter,name
      6,"The default Storage Class",0,null,,,,,"preferKeep",0,"volumeCreation",7,"The default Storage Class",0,null,,,,,"preferKeep",0,"volumeCreation","--------"
      6,"",1,,"remove",0,"volumeCreation",null,,,,,,,,,,,,,,,"SC0"
      6,"",1,,"keep",0,"volumeCreation",null,,,,,,,,,,,,,,,"SC1"
      6,"Auto created at 2023.11-16.03:06:54.888344",0,null,,,,,"preferKeep",0,"volumeCreation",7,"",1,,"remove",0,"volumeCreation",null,,,,"SCNT"
      6,"",1,,"useIART",0,"volumeCreation",null,,,,7,"",1,,"useIART",0,"volumeCreation",null,,,,"SCPOOL1"
      
      $ curl -k -s "https://popcorn.tuc.stglabs.ibm.com/api/v2/dataClasses" -H "Content-Type: text/csv" -H "Authorization: Bearer $token"
      _lwormRetentionOptions_applicationManagedDuration,_lwormRetentionOptions_applyApplicationManagedDateForSubsequentHDR1,_lwormRetentionOptions_applyFixedDurationForFirstHDR1NoDate,_lwormRetentionOptions_applyFixedDurationForNoSubsequentHDR1,_lwormRetentionOptions_applyFixedDurationForSubsequentHDR1NoDate,_lwormRetentionOptions_applyFixedDurationOnReturnToScratch,_lwormRetentionOptions_fixedDuration,_lwormRetentionOptions_honorAllSubsequentHDR1s,_lwormRetentionOptions_honorReturnToScratch,_lwormRetentionOptions_noFirstHDR1TreatAsNoDate,_lwormRetentionOptions_retentionType,compression,counterHandling,description,logicalWorm,lwormRetentionOptions,name,virtualVolumeSize
      ,,,,,,,,,,,"FICON","surfaceEOT","The default Data Class","no",null,"--------",0
      ,,,,,,,,,,,"ZSTD","wrapSupported","0","yes",,"DCINS",0
      ,,,,,,,,,,,"ZSTD","surfaceEOT","a","no",null,"DCNT",65000
      ,,,,,,,,,,,"ZSTD","wrapSupported","A","no",null,"M2C2GIG",2000
      ,,,,,,,,,,,"FICON","surfaceEOT","b","no",null,"M2N2GIG",0