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.
URL structure
The URL structure for an operation is
https://ip_address/api/vX/command
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.
- 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
- The format of CSV format is (key (column name) and values)