v1http500

IBMHyper-ScaleManagerVersion5.
1.
1RESTAPISpecificationsSC27-6440-03IBMNoteBeforeusingthisinformationandtheproductitsupports,readtheinformationin"Notices"onpage59.
EditionNoticePublicationnumber:SC27-6440-03.
ThiseditionappliestoIBMHyper-ScaleManagerversion5.
1.
1andtoallsubsequentreleasesandmodifications,untilotherwiseindicatedinanewerpublication.
CopyrightIBMCorporation2014,2016.
USGovernmentUsersRestrictedRights–Use,duplicationordisclosurerestrictedbyGSAADPScheduleContractwithIBMCorp.
ContentsTablesvAboutthisguideviiWhoshouldusethisguideviiConventionsusedinthisguideviiRelatedinformationandpublications.
viiGettinginformation,help,andserviceviiIBMPublicationsCenterviiiSendingorpostingyourcommentsviiiChapter1.
Introduction1Protocolversion1HTTPmethods1URLscopespecifiersandresourcenames.
1Chapter2.
Generalrequests3Chapter3.
Queryrequests5Querypagingsupport5Systemqueryrequests6Volumequeryrequests6Hostqueryrequests7Clusterqueryrequests7SystemFiberChannel(FC)portqueryrequests.
.
.
7SystemiSCSIportqueryrequests8Hostportqueryrequests8Mappingqueryrequests8Poolqueryrequests9Volumesnapshotqueryrequests.
9Performanceclassqueryrequests9Eventqueryrequests10Queryresponseformat11Chapter4.
Updaterequests13Volumeupdaterequests14Volumecreationrequests14Volumeresizerequests14Volumelockrequests15Volumeunlockrequests16Volumerenamerequests16Volumecopyrequests17Volumemoverequests.
17Volumedeletionrequests18Hostupdaterequests19Hostcreationrequests19Hostrenamerequests19Hostdeletionrequests20Clusterupdaterequests21Clustercreationrequests21Clusteraddhostrequests.
21Clusterremovehostrequests22Clusterrenamerequests23Clusterdeletionrequests23Hostportupdaterequests24Hostportcreationrequests24Hostportdeletionrequests24Volumemappingupdaterequests25Volumemappingcreationrequests26Volumemappingdeletionrequests26Poolupdaterequests27Poolcreationrequests27Poolresizerequests.
28Poolresizesnapshotsizerequests28Poolrenamerequests29Pooldeletionrequests30Volumesnapshotupdaterequests30Volumesnapshotcreationrequests30Volumesnapshotoverwriterequests31Volumesnapshotlockrequests31Volumesnapshotunlockrequests32Volumesnapshotdeletionrequests32Performanceclassupdaterequests.
33Performanceclasscreationrequests33PerformanceclassupdateIOPSlimitrequests.
.
34Performanceclassupdatebandwidthlimitrequests35Performanceclassrenamerequests35Performanceclassaddvolumerequests.
.
.
.
36Performanceclassremovevolumerequests.
.
.
37Performanceclassaddpoolrequests37Performanceclassremovepoolrequests.
.
.
.
38Performanceclassadddomainrequests.
.
.
.
38Performanceclassremovedomainrequests.
.
.
39Performanceclassaddhostrequests40Performanceclassremovehostrequests.
.
.
.
40Performanceclassdeletionrequests41Updateresponseformat41Chapter5.
RequestURLdefinitions.
.
43SystemrequestURLs43VolumerequestURLs43HostrequestURLs43ClusterrequestURLs44SystemFCportrequestURLs44SystemiSCSIportrequestURLs44HostportrequestURLs44VolumemappingrequestURLs.
44PoolrequestURLs44EventrequestURLs45VolumesnapshotrequestURLs.
45PerformanceclassrequestURLs45Chapter6.
Resourcedefinitions.
.
.
.
47Systemresourcedefinitions47Volumeresourcedefinitions48Hostresourcedefinitions48Clusterresourcedefinitions49SystemFCportresourcedefinitions49SystemiSCSIportresourcedefinitions50CopyrightIBMCorp.
2014,2016iiiHostportresourcedefinitions50Volumemappingresourcedefinitions.
50Poolresourcedefinitions51Eventresourcedefinitions51Volumesnapshotresourcedefinitions.
51Performanceclassresourcedefinitions52Chapter7.
Errorhandling.
53HTTPstatuscodes53Serverstatuscodes54Failedsystemstatuscodes55Chapter8.
Security57Notices59Trademarks61ivIBMHyper-ScaleManagerRESTAPISpecificationsTables1.
HTTPstatuscodesandmessages532.
Serverstatuscodes,correlatedtoHTTPstatuscodes543.
Failedsystemstatuscodes55CopyrightIBMCorp.
2014,2016vviIBMHyper-ScaleManagerRESTAPISpecificationsAboutthisguideThepurposeofthisguideistoprovidethespecificationsoftheIBMHyper-ScaleManagerRESTapplicationprogramminginterface(API).
WhoshouldusethisguideThisguideisforsoftwaredeveloperswhoarecodingcontrolapplicationsforXIV,SpectrumAccelerate,FlashSystemA9000,andFlashSystemA9000Rsystems.
ConventionsusedinthisguideThesenoticesareusedtohighlightkeyinformation.
Note:Thesenoticesprovideimportanttips,guidance,oradvice.
Important:Thesenoticesprovideinformationoradvicethatmighthelpyouavoidinconvenientordifficultsituations.
Attention:Thesenoticesindicatepossibledamagetoprograms,systems,ordata.
Anattentionnoticeappearsbeforetheinstructionorsituationinwhichdamagecanoccur.
RelatedinformationandpublicationsYoucanfindadditionalinformationandpublicationsrelatedtoIBMHyper-ScaleManageronthefollowinginformationsources:vIBMFlashSystemA9000onIBMKnowledgeCenter(ibm.
com/support/knowledgecenter/STJKMM)vIBMFlashSystemA9000RonIBMKnowledgeCenter(ibm.
com/support/knowledgecenter/STJKN5)vIBMSpectrumAccelerateonIBMKnowledgeCenter(ibm.
com/support/knowledgecenter/STZSWD)vIBMXIVStorageSystemonIBMKnowledgeCenter(ibm.
com/support/knowledgecenter/STJTAG).
Gettinginformation,help,andserviceIfyouneedhelp,service,technicalassistance,orwantmoreinformationaboutIBMproducts,youcanfindvarioussourcestoassistyou.
YoucanviewthefollowingwebsitestogetinformationaboutIBMproductsandservicesandtofindthelatesttechnicalinformationandsupport.
vIBMwebsite(ibm.
com)vIBMSupportPortalwebsite(www.
ibm.
com/storage/support)vIBMDirectoryofWorldwideContactswebsite(www.
ibm.
com/planetwide)UsetheDirectoryofWorldwideContactstofindtheappropriatephonenumberforinitiatingvoicecallsupport.
VoicecallsarrivetoLevel1orFrontLineSupport.
CopyrightIBMCorp.
2014,2016viiIBMPublicationsCenterTheIBMPublicationsCenterisaworldwidecentralrepositoryforIBMproductpublicationsandmarketingmaterial.
TheIBMPublicationsCenterwebsite(ibm.
com/shop/publications/order)offerscustomizedsearchfunctionstohelpyoufindthepublicationsthatyouneed.
Youcanviewordownloadpublicationsatnocharge.
SendingorpostingyourcommentsYourfeedbackisimportantinhelpingtoprovidethemostaccurateandhighestqualityinformation.
ProcedureTosubmitanycommentsaboutthisguide:vGotoIBMKnowledgeCenter(ibm.
com/support/knowledgecenter),drilldowntotherelevantpage,andthenclicktheFeedbacklinkthatislocatedatthebottomofthepage.
Thefeedbackformisdisplayedandyoucanuseittoenterandsubmityourcommentsprivately.
vYoucanpostapubliccommentontheIBMKnowledgeCenterpagethatyouareviewing,byclickingAddComment.
Forthisoption,youmustfirstlogintoIBMKnowledgeCenterwithyourIBMID.
vYoucansendyourcommentsbyemailtostarpubs@us.
ibm.
com.
Besuretoincludethefollowinginformation:–Exactpublicationtitleandproductversion–Publicationformnumber(forexample:SC01-0001-01)–Page,table,orillustrationnumbersthatyouarecommentingon–AdetaileddescriptionofanyinformationthatshouldbechangedNote:WhenyousendinformationtoIBM,yougrantIBManonexclusiverighttouseordistributetheinformationinanywayitbelievesappropriatewithoutincurringanyobligationtoyou.
viiiIBMHyper-ScaleManagerRESTAPISpecificationsChapter1.
IntroductionTheHyper-ScaleManagerRESTAPIallowstheendusertoprocesstwomaintypesofrequests:vQueryrequests:Requeststhatreturnstates,foreitherasingleresourceoralistofresources.
TheseareobjectentitiesmanagedbyHyper-ScaleManager(forexample,allvolumesofaspecificsupportedstoragesystem).
vUpdaterequests:Requeststhatupdatestates–thatcreate,delete,orupdatetheobjectentitystate(forexample,onethatcreatesanewpoolonaspecificsupportedstoragesystem).
TheAPIusesHTTPasthetransportprotocolandreliesonHTTPforsomefeatures,suchassecurity.
Therearetworesourcetypesthatrequestsmaycall:vSingleresource:Volume,port,orhost.
vListofresources:Allpoolsofaspecificsupportedstoragesystem.
ProtocolversionThecurrentprotocolversionisv3.
ThisisindicatedintheURLbyaddingthe/v3pathtoalloftheURLs(forexample,/xiv/v3/volumes).
ThecurrentprotocolversionsupportsIBMXIVStorageSystemGen4.
Asopposedtov2,thisversion:vSupportsperformanceclasses.
vDiscontinuessupportofvolumecompressionanddecompression.
HTTPmethodsTheprotocolreliesonHTTPmethodstosupportCRUDoperations(Create/Read/Update/Delete):vHTTPPOST:Mappedtocreate/update/deleteoperations.
vHTTPGET:Mappedtoquery(read)operations.
vHTTPDELETE:Mappedtodeleteoperations.
TheHTTPURLspecifiestheresourcetowhichtherequestapplies.
URLscopespecifiersandresourcenamesRequestURLsarebuiltfromscopespecifiersandresourcenames,prefixedwith:,forexample:/xiv/v3/:xiv2/ports/:10000000C9926DCAIntheaboveexample:v/xivspecifiesthemainAPIscope.
vv3specifiestheprotocolversion.
(Shouldbev1forversionone.
)v:xiv2specifiesthesystemIP/DNSname.
v/portsdefinestheportsscope.
Forexample,wearelookingatportsinxiv1.
CopyrightIBMCorp.
2014,20161v10000000C9926DCAistheportname.
Note:TherequestandresponseformatisJSON.
AlloftheexamplesshowninthedocumentareformattedasJSON.
2IBMHyper-ScaleManagerRESTAPISpecificationsChapter2.
GeneralrequestsThefollowinggeneralqueryrequestsaresupported.
Generateacapacityreportforallofthesystemsinyourinventory:GET/xiv/v3/systems/capacityReportGenerateacapacityreportforaspecificsysteminyourinventory:GET/xiv/v3/systems/:/capacityReportAdownloadbarappearsatthebottomofyourscreenwithalinktothecontainingfolderofthezipfile.
OpenthezipfolderandclickonthePDFtodisplaythereport.
CopyrightIBMCorp.
2014,201634IBMHyper-ScaleManagerRESTAPISpecificationsChapter3.
QueryrequestsAqueryisrunbyissuingtheHTTPGETcommandonaURL,representingeither:vAcollectionofresourceswherealistofresourcesandtheirpropertiesisreturned(forexample,/xiv/v3/:xiv1/volumes).
vAsingleresourcewheresingleresourcepropertiesarereturned(forexample,/xiv/v3/:xiv1/volumes/:vol1).
QueryrequestsmaycontainadditionalURLparameters,forfiltering.
Requeststhatusefilteringparametersreturnonlyresourcesthatmatchthefilteringcriteria.
Forexample,/xiv/v3/:xiv1/volumespool=mypoolwouldreturnonlyvolumesthatexistinthemypoolpool.
Allquerieslistedinthisdocument(excludingsystemqueries),whichreturncollectionsofresources,willsupport"bydomain"filtering.
Forexample:/xiv/v3/:xiv1/volumesdomain=d1wouldreturnallvolumesonagivensystem(xiv1)thatbelongtothespecifieddomain(d1).
Thisfunctionalityisoptionalandwillbeimplementedona"besteffortbasis.
"Thefollowingtopicsarecoveredinthischapter:v"Querypagingsupport"v"Systemqueryrequests"onpage6v"Volumequeryrequests"onpage6v"Hostqueryrequests"onpage7v"Clusterqueryrequests"onpage7v"SystemFiberChannel(FC)portqueryrequests"onpage7v"SystemiSCSIportqueryrequests"onpage8v"Hostportqueryrequests"onpage8v"Mappingqueryrequests"onpage8v"Poolqueryrequests"onpage9v"Volumesnapshotqueryrequests"onpage9v"Performanceclassqueryrequests"onpage9v"Eventqueryrequests"onpage10v"Queryresponseformat"onpage11QuerypagingsupportAqueryrequestcanreturnahugelistofresources.
Forexample,arequestforallvolumesfromallsupportedstoragesystemscancontaintensofthousandsofvolumeresources.
Aclientmayonlybeinterestedinrequestingasubset/pagefromthequery.
Thefollowingtwoparameterssupportthisrequirement:voffset:Definestheindexofthefirstresourcethatshouldbereturnedinthequery.
(Allresourcesarenumbered,startingfrom0.
)Ifanoffsetparameterisomitted,anoffsetof0isassumed.
Iftheoffsetislargerthanthenumberofresources,aresponsewithnoresourcesisreturned.
vlimit:Definesthemaximumcountofresourcesthatshouldbereturnedinthequery.
Theactualcountofresourcesintheresponseislessthanorequaltotherequestedlimit.
Ifthelimitparameterisomitted,theserverreturnsuptoCopyrightIBMCorp.
2014,20165max_limitamountofresources(defaultsto1000).
Ifthelimitparameterishigherthantheamountofresources,therequestwillfailwitha400BadRequesterror.
Bydefault,thelistofreturnedobjectsissortedbyname.
Note:Systemandeventqueriesdonotsupportpaging.
Examples:v/xiv/v3/volumes:ReturnsallofthevolumesfromalloftheXIVsystems(uptomax_limit).
v/xiv/v3/volumeslimit=400:Returnsthefirst400volumesfromalloftheXIVsystems.
v/xiv/v3/volumesoffset=10&limit=40:Returns40volumes,startingfromvolume11.
v/xiv/v3/volumesoffset=101:Returnsallvolumes(uptomax_limit),startingfromvolume102.
SystemqueryrequestsThefollowingsystemqueryrequestsaresupported:Listallofthesystemsonwhichtheuserisauthorized:GET/xiv/v3/systemsListspecificsystemproperties(xiv1–systemIP/DNS):GET/xiv/v3/systems/:xiv1VolumequeryrequestsThefollowingvolumequeryrequestsaresupported:Listallofthevolumesfromallofthesystemsonwhichtheuserisauthorized:GET/xiv/v3/volumesListallofthevolumesfromspecificmachine:GET/xiv/v3/:xiv1/volumesListallofthevolumesfromspecificmachineandpool(wherep1isthepoolname):GET/xiv/v3/:xiv1/volumespool=p1Listspecificvolumeproperties:GET/xiv/v3/:xiv1/volumes/:vol16IBMHyper-ScaleManagerRESTAPISpecificationsHostqueryrequestsThefollowinghostqueryrequestsaresupported:Listallofthehostsfromallofthesystemsonwhichtheuserisauthorized:GET/xiv/v3/hostsListallofthehostsfromaspecificmachine:GET/xiv/v3/:xiv1/hostsListallofthehostsfromaspecificmachinethatbelongtoaspecificcluster(wherecl1istheclustername):GET/xiv/v3/:xiv1/hostscluster=cl1Listspecifichostproperties:(whereh1isthehostname)GET/xiv/v3/:xiv1/hosts/:h1ClusterqueryrequestsThefollowingclusterqueryrequestsaresupported:Listalloftheclustersfromallofthesystemsonwhichtheuserisauthorized:GET/xiv/v3/clustersListalloftheclustersfromaspecificmachine:GET/xiv/v3/:xiv1/clustersListspecificclusterproperties:(wherec1istheclustername)GET/xiv/v3/:xiv1/clusters/:c1SystemFiberChannel(FC)portqueryrequestsThefollowingsystemFiberChannel(FC)portqueryrequestsaresupported:ListalloftheFCportsfromaspecificmachine:GET/xiv/v3/:xiv1/fc_portsListspecificFCportproperties:(wherep1istheportname)GET/xiv/v3/:xiv1/fc_ports/:p1Chapter3.
Queryrequests7SystemiSCSIportqueryrequestsThefollowingsystemiSCSIportqueryrequestsaresupported:ListallofthesystemiSCSIportsfromaspecificmachine:GET/xiv/v3/:xiv1/iscsi_portsListspecificiSCSIportproperties:(wherep1istheportname)GET/xiv/v3/:xiv1/iscsi_ports/:p1HostportqueryrequestsHostportsareportsthatbelongtohosts,nottosystems.
Thefollowingsystemhostportqueryrequestsaresupported:Listalloftheportsofaspecifichost(whereh1isthehostname):GET/xiv/v3/:xiv1/host_portshost=h1Listthehosttowhichthespecificportisassigned(wherep1istheportname):GET/xiv/v3/:xiv1/host_portsport=p1ListthespecificFCportonahost(whereh1isthehostname,andp1istheportname):GET/xiv/v3/:xiv1/host_ports/:fc:h1:p1ListthespecificiSCSIportonahost(whereh1isthehostname,andp1istheportname):GET/xiv/v3/:xiv1/host_ports/:iscsi:h1:p1MappingqueryrequestsThefollowinghost,cluster,andvolumemappingqueryrequestsaresupported:Listallofthemappingsofthehost(whereh1isthehostname):GET/xiv/v3/:xiv1/vol_mapshost=h1Listallofthemappingsofthecluster(wherec1istheclustername):GET/xiv/v3/:xiv1/vol_mapscluster=c1Listallofthemappingsofthevolume(wherevol1isthevolumename):GET/xiv/v3/:xiv1/vol_mapsvolume=vol18IBMHyper-ScaleManagerRESTAPISpecificationsListspecifichostmappingproperties(whereh1isthehostname,andvol1isthevolumename):GET/xiv/v3/:xiv1/vol_maps/:host:h1:vol1Listspecificclustermappingproperties(wherec1isthehostname,andvol1isthevolumename):GET/xiv/v3/:xiv1/vol_maps/:cluster:c1:vol1PoolqueryrequestsThefollowingpoolqueryrequestsaresupported:Listallofthepoolsfromallofthesystemsonwhichtheuserisauthorized:GET/xiv/v3/poolsListallofthepoolsfromaspecificmachine:GET/xiv/v3/:xiv1/poolsListspecificpoolproperties(wherep1isthepoolname):GET/xiv/v3/:xiv1/pools/:p1VolumesnapshotqueryrequestsThefollowingvolumesnapshotqueryrequestsaresupported:Listallofthesnapshotsfromallofthesystemsonwhichtheuserisauthorized:GET/xiv/v3/snapshotsListallofthesnapshotsfromaspecificmachine:GET/xiv/v3/:xiv1/snapshotsListallofthesnapshotsofthespecifiedvolume(wherevol1isthevolumename):GET/xiv/v3/:xiv1/snapshotsvolume=vol1Listspecificsnapshotproperties(wheresn1isthesnapshotname):GET/xiv/v3/:xiv1/snapshots/:sn1PerformanceclassqueryrequestsThefollowingperformanceclassqueryrequestsaresupported:Chapter3.
Queryrequests9Listalloftheperformanceclassesfromallofthesystemsonwhichtheuserisauthorized:GET/xiv/v3/perf_classesListalloftheperformanceclassesfromaspecificmachine:GET/xiv/v3/:xiv1/perf_classesListthepropertiesofaspecificperformanceclass(wheresilveristheperformanceclassname):GET/xiv/v3/perf_classes/:silverListallvolumesthatareapartofaspecificperformanceclass:GET/xiv/v3/:xiv1/volumesperf_class=silverListallhoststhatarepartofaspecificperformanceclassGET/xiv/v3/:xiv1/hostsperf_class=silverListallpoolsthatarepartofaspecificperformanceclassGET/xiv/v3/:xiv1/poolsperf_class=silverEventqueryrequestsAneventqueryrequestfetcheseventsfromaspecificsupportedstoragesystem.
EventqueriesaredifferentfromtherestofthequeriessinceeventsarecurrentlynotmanagedbytheHyper-ScaleManager.
SinceeventsarenotmanagedbytheHyper-ScaleManager,pagingisnotsupportedforthisquery.
Thefollowingqueryparameterscanbeusedtofiltertheevents:vmin_severity:Definestheminimumeventseverity.
PossiblevaluesincludeInformational,Minor,Major,Warning,orCritical.
Ifomitted,theminimumseveritydefaultstoInformational.
vafter:Onlyreturnseventsthatoccurafterthespecifiedtimestamp.
vbefore:Onlyreturnseventsthatoccurbeforethespecifiedtimestamp.
Thesyntaxforthebeforeandafterfieldsisasfollows:Y-M-D[.
[h[:m[:s]]]],wheretherangesareasfollows:vY:year(fourdigits)vM:month(01-12)vD:day(01-31)vh:hour(00-23,with00asthedefault)vm:minute(00-59with00asthedefault)vs:second(00-59with00asthedefault)10IBMHyper-ScaleManagerRESTAPISpecificationsIffilteringparametersareomitted,thelast300eventsarereturned.
Exampleeventquery:GET/xiv/v3/:xiv1/eventsmin_severity=Warning&after=2013-03-07Exampleeventqueryresponse:HTTP/1.
1200OK.
.
.
{"status":{"server":{"status":"0","message":"OK"}"failed_systems":[]}"response":{"counts":{"data_count":"300","total_count":"300"}"data":{.
.
.
.
}}Note:Sinceeventsarenotmanagedbytheserverandpagingisnotsupported,thedatacountreturnedinresponseisalwaysequaltothetotalcount.
QueryresponseformatThequeryresponseisdefinedasanobjecthavingthefollowingfields:vstatus:Theresponsestatus.
–server:Applicationlevelstatusandstatusmessage.
–failed_systems:Arrayofmachineerrorsthatwereencounteredduringtherequest.
Thisfieldisusedduringmulti-machinequeriesorupdatestoindicatethatsomemachineshadissues(suchasdisconnected,not–authorized,invalidstate,etc.
)duringthequeryandthatthereturneddatamaynotcontainallresources,ortherequiredoperationhadonlypartialsuccess.
vresponse:Thequeryresponseresult.
–counts:Theresponsecountandtotalcountofobjects.
-data_count:Thenumberofobjectsinthisresponsedata.
-total_count:Thenumberoftotalobjects.
–data:Theresponsedata.
Canbeeither:-Alistofobjectsforqueriesonobjectcollections(forexample:/xiv/volumes).
-Asingleobjectforqueriesonaspecificobject(forexample:/xiv/:xiv1/volumes/:vol1).
-Null,iftherewassomeerrorinqueryprocessing.
Notesregardingformatofqueryresponsedetails:vAllofthestoragecapacitypropertiesinthequeryresponsesaregivenasintegers,inbytes.
Forexample:capacityattributesofsystemresources,sizeattributesofvolumeresources,sizeattributesofpoolresources,etc.
vBooleanattributesaregivenastrue/false,suchasforthemirroredattributeofvolumeresources,etc.
vTimestampsaredisplayedinmilliseconds,sincetheUnixepoch(example:1970-01-0100:00:00).
Chapter3.
Queryrequests11Exampleofasuccessfulresponse:Request-GET/xiv/v3/:xiv1/volumes/:vol1.
.
.
Response-HTTP/1.
1200OK.
.
.
{"status":{"server":{"status":"0","message":"OK"}"failed_systems":[]}"response":{"counts":{"data_count":"1","total_count":"1"}"data":{"volume":{"name":"vol1".
.
.
}}}}Exampleofapartiallysuccessfulresponse:Request-GET/xiv/v3/volumes.
.
.
Response-HTTP/1.
1200OK.
.
.
{"status":{"server":{"status":"0","message":"OK"}"failed_systems":[{"name":"mn44","status":"1","message":"Thesystemisdisconnected"}]}"response":{"counts":{"data_count":"10","total_count":"1000"}"data":{"volume":[{"name":"vol1".
.
.
}.
.
.
{"name":"vol10".
.
.
}]}}}Exampleofaresponsetoaninvalidrequest:Request-GET/xiv/v3/myvolumes.
.
.
Response-HTTP/1.
1400BadRequest.
.
.
{"status":{"server":{"status":"6","message":"Invalidrequest–myvolumespathisundefined"}"failed_systems":[]}"response":{"counts":{"data_count":"0","total_count":"0"}"data":{}}}12IBMHyper-ScaleManagerRESTAPISpecificationsChapter4.
UpdaterequestsUpdaterequestsincludecreation,deletion,ormodificationofmanagedresources.
SincetheHyper-ScaleManageronlyreflectsthestateofobjectsmanagedbythesupportedstoragesystems,allsuchrequestsshouldbepassedbytheHyper-ScaleManagertothesupportedstoragesystemstohandle,usingCLIcommandsinternally.
Hereanewgenericprotocolformatisintroduced,decoupledfromtheCLIsyntax.
Sinceupdaterequestsrequiresomedatatobeprovidedbyclients(forexample,anewvolumesizeinthevolumeresizeoperation),howthisdataistransferredmustbedefined.
OnealternativeistoprovidethisdataasHTTPURLparameters;however,thismeansthattheprotocolisstrictlycoupledwiththetransportprotocol(HTTPinthiscase)andcannotbereusedeasilywithothertransportprotocolsthatdonotsupporttheURLparametersfeature.
TheonlyotheroptionistodelivertherequireddatainsideanHTTPbodyinJSONformat.
Definetheupdaterequestobjectwiththefollowinggenericfields:vaction:Therequiredaction.
Possiblevaluesincludecreateanddelete.
Additionalactionsarepossible,basedontheresourcetype.
vparams:Containstheparametersrequiredfortheaction.
UpdatesaredoneusingtheHTTPPOSTrequestonaURLrepresentingacollectionofresources(forexample,POSTon/xiv/v3/:xiv1/volumes),whilethebodycontainstheexactactiontoperform(create/delete/update).
Eachsuchrequestcancarryalistofupdaterequeststosupportbulkoperations.
Additionally,thefollowingshortcutsareallowed:vHTTPDELETErequestonafullURL(forexample,/xiv/v3/:xiv1/volumes/:vol1)withnobody,inordertodeleteit.
vHTTPPOSTrequestonafullURLinordertoupdate/deleteit.
Thebodycontainsasinglerequestobjectwithalloftherequiredparameters,exceptname(sinceitappearsinURL).
Note:Thisreleasedoesnotsupportmultiplerequestsinthebody.
Onlyasingleupdaterequestinthebodyissupported.
Thefollowingtopicsarecoveredinthischapter:v"Volumeupdaterequests"onpage14v"Hostupdaterequests"onpage19v"Clusterupdaterequests"onpage21v"Hostportupdaterequests"onpage24v"Volumemappingupdaterequests"onpage25v"Poolupdaterequests"onpage27v"Volumesnapshotupdaterequests"onpage30v"Performanceclassupdaterequests"onpage33v"Updateresponseformat"onpage41CopyrightIBMCorp.
2014,201613VolumeupdaterequestsThefollowingtypesofvolumeupdaterequestsaresupported.
vVolumecreationrequestsvVolumeresizerequestsvVolumelockrequestsvVolumeunlockrequestsvVolumerenamerequestsvVolumecopyrequestsvVolumemovetoapoolvVolumedeleterequestsVolumecreationrequestsVolumecreationrequestsincludethefollowingcomponents:vAnactionparameterwithavalueofcreate.
vAparamsparameter,containingthefollowingparameters:–name:Thevolumename.
–pool:Thepoolnamewherevolumeshouldbecreated.
–size:Thevolumesize.
–size_units:Thesizeunits.
PossiblevaluesincludeGBandBLOCKS.
Example:POST/xiv/v3/:xiv1/volumes{"request":[{"action":"create","params":{"name":"vol1","pool":"pool1","size":"17","size_units":"GB"}}]}VolumeresizerequestsVolumeresizerequests(toincreaseordecreasethevolumesize)includethefollowingcomponents:vAnactionparameterwithavalueofresize.
vAparamsparameter,containingthefollowingparameters:–name:Thevolumename.
–size:Thenewvolumesize.
–size_units:Thesizeunits.
PossiblevaluesincludeGBandBLOCK.
Example:14IBMHyper-ScaleManagerRESTAPISpecificationsPOST/xiv/v3/:xiv1/volumes{"request":[{"action":"resize","params":{"name":"vol1","size":"170","size_units":"GB"}}]}Alternatively,avolumecanberesizedwiththefollowingrequest:POST/xiv/v3/:xiv1/volumes/:vol1{"request":[{"action":"resize","params":{"size":"170","size_units":"GB"}}]}VolumelockrequestsVolumelockrequestsincludethefollowingcomponents:vAnactionparameterwithavalueoflock.
vAparamsparameter,containingthefollowingparameter:–name:Thevolumename.
Example:POST/xiv/v3/:xiv1/volumes{"request":[{"action":"lock","params":{"name":"vol1"}}]}Alternatively,avolumecanbelockedwiththefollowingrequest:POST/xiv/v3/:xiv1/volumes/:vol1{"request":{"action":"lock"}}Chapter4.
Updaterequests15VolumeunlockrequestsVolumeunlockrequestsincludethefollowingcomponents:vAnactionparameterwithavalueofunlock.
vAparamsparameter,containingthefollowingparameter:–name:Thevolumename.
Example:POST/xiv/v3/:xiv1/volumes{"request":[{"action":"unlock","params":{"name":"vol1"}}]}Alternatively,avolumecanbeunlockedwiththefollowingrequest:POST/xiv/v3/:xiv1/volumes/:vol1{"request":{"action":"unlock"}}VolumerenamerequestsVolumerenamerequestsincludethefollowingcomponents:vAnactionparameterwithavalueofrename.
vAparamsparameter,containingthefollowingparameters:–name:Thevolumename.
–new_name:Thenewnameofthevolume.
Example:POST/xiv/v3/:xiv1/volumes{"request":[{"action":"rename","params":{"name":"vol1","new_name":"vol2"}}]}Alternatively,avolumecanberenamedwiththefollowingrequest:16IBMHyper-ScaleManagerRESTAPISpecificationsPOST/xiv/v3/:xiv1/volumes/:vol1{"request":{"action":"rename","params":{"new_name":"vol2"}}}VolumecopyrequestsVolumecopyrequestsincludethefollowingcomponents:vAnactionparameterwithavalueofcopy.
vAparamsparameter,containingthefollowingparameters:–name:Thevolumename.
–target:Thenameofthetargetvolume.
Example:POST/xiv/v3/:xiv1/volumes{"request":[{"action":"copy","params":{"name":"vol1","target":"vol2"}}]}Alternatively,avolumecanbecopiedwiththefollowingrequest:POST/xiv/v3/:xiv1/volumes/:vol1{"request":{"action":"copy","params":{"target":"vol2"}}}VolumemoverequestsArequesttomoveavolumetoanewpoolincludesthefollowingcomponents:vAnactionparameterwithavalueofmove.
vAparamsparameter,containingthefollowingparameters:–name:Thevolumename.
–pool:Thenameofthetargetpool.
Example:Chapter4.
Updaterequests17POST/xiv/v3/:xiv1/volumes{"request":[{"action":"move","params":{"name":"vol1","pool":"pool1"}}]}Alternatively,avolumecanbemovedtoanewpoolwiththefollowingrequest:POST/xiv/v3/:xiv1/volumes/:vol1{"request":{"action":"move","params":{"pool":"pool1"}}}VolumedeletionrequestsVolumedeletionrequestsincludethefollowingcomponents:vAnactionparameterwithavalueofdelete.
vAparamsparameter,containingthefollowingparameters:–name:Thevolumename.
Example:POST/xiv/v3/:xiv1/volumes{"request":[{"action":"delete","params":{"name":"vol1"}}]}Alternatively,avolumecanbedeletedusingeitherofthefollowingrequests,wherevol1isthevolumename:POST/xiv/v3/:xiv1/volumes/:vol1{"request":[{"action":"delete"}]}DELETE/xiv/v3/:xiv1/volumes/:vol118IBMHyper-ScaleManagerRESTAPISpecificationsHostupdaterequestsThefollowingtypesofhostupdaterequestsaresupported.
v"Hostcreationrequests"v"Hostrenamerequests"v"Hostdeletionrequests"onpage20HostcreationrequestsHostcreationrequestsincludethefollowingcomponents:vAnactionparameterwithavalueofcreate.
vAparamsparameter,containingthefollowingparameters:–name:Thehostname.
–cluster(optionalparameter):Theclustername.
Ifnotprovided,thestand-alonehostisdefined.
–type(optionalparameter):Thehosttype.
Possiblevaluesincludestandard,hpux,andzvm.
Ifomitted,thedefaultvalueisstandard.
–domains(optionalparameter):Thedomain.
Ifomitted,thehostwillnotbeassociatedwithanydomain.
Use"*"toassociatethehostwithalldomains.
Note:vThetypeandclusterparametersareexclusive;thatis,onlyoneofthemcanbeprovidedintherequest.
Thetypeparametercanonlybespecifiedforstand-alonehosts.
Iftheclusterparameterisprovided,thehosttypeisderivedfromthecluster.
vIftheparameterclusterisdefined,andthetargetsystemsupportsdomains,thentheparameterdomainsshouldbedefined.
Example:POST/xiv/v3/:xiv1/hosts{"request":[{"action":"create","params":{"name":"host1","type":"hpux","domains":"domain1"}}]}HostrenamerequestsHostrenamerequestsincludethefollowingcomponents:vAnactionparameterwithavalueofrename.
vAparamsparameter,containingthefollowingparameters:–name:Thehostname.
–new_name:Thenewnameofthehost.
Example:Chapter4.
Updaterequests19POST/xiv/v3/:xiv1/hosts{"request":[{"action":"rename","params":{"name":"host1","new_name":"host2"}}]}Alternatively,ahostcanberenamedwiththefollowingrequest:POST/xiv/v3/:xiv1/hosts/:host1{"request":{"action":"rename","params":{"new_name":"host2"}}}HostdeletionrequestsHostdeletionrequestsincludethefollowingcomponents:vAnactionparameterwithavalueofdelete.
vAparamsparameter,containingthefollowingparameter:–name:Thehostname.
Example:POST/xiv/v3/:xiv1/hosts{"request":[{"action":"delete","params":{"name":"host1"}}]}Alternatively,ahostcanbedeletedwitheitherofthefollowingrequests:POST/xiv/v3/:xiv1/hosts/:h1{"request":[{"action":"delete"}]}DELETE/xiv/v3/:xiv1/hosts/:h120IBMHyper-ScaleManagerRESTAPISpecificationsClusterupdaterequestsThefollowingtypesofclusterupdaterequestsaresupported.
v"Clustercreationrequests"v"Clusteraddhostrequests"v"Clusterremovehostrequests"onpage22v"Clusterrenamerequests"onpage23v"Clusterdeletionrequests"onpage23ClustercreationrequestsClustercreationrequestsincludethefollowingcomponents:vAnactionparameterwithavalueofcreate.
vAparamsparameter,containingthefollowingparameters:–name:Theclustername.
–type(optionalparameter):Theclustertype.
Possiblevaluesincludestandard,hpux,andzvm.
Ifomitted,thedefaultvalueisstandard.
–domains(optionalparameter):Thedomain.
Ifomitted,theclusterwillnotbeassociatedwithanydomain.
Use"*"toassociatetheclusterwithalldomains.
Example:POST/xiv/v3/:xiv1/clusters{"request":[{"action":"create","params":{"name":"c1","type":"zvm","domains":"domain1"}}]}ClusteraddhostrequestsClusteraddhostrequestsincludethefollowingcomponents:vAnactionparameterwithavalueofadd_host.
vAparamsparameter,containingthefollowingparameters:–name:Theclustername.
–host:Thenameofthehost.
–map:Indicatesthetypeofmapping.
Possiblevaluesincludehostandcluster.
Example:Chapter4.
Updaterequests21POST/xiv/v3/:xiv1/clusters{"request":[{"action":"add_host","params":{"name":"cluster1","host":"host1","map":"cluster"}}]}Alternatively,ahostcanbeaddedtoaclusterwiththefollowingrequest:POST/xiv/v3/:xiv1/clusters/:cluster1{"request":{"action":"add_host","params":{"host":"host1","map":"cluster"}}}ClusterremovehostrequestsClusterremovehostrequestsincludethefollowingcomponents:vAnactionparameterwithavalueofremove_host.
vAparamsparameter,containingthefollowingparameters:–name:Theclustername.
–host:Thenameofthehost.
Example:POST/xiv/v3/:xiv1/clusters{"request":[{"action":"remove_host","params":{"name":"cluster1","host":"host1"}}]}Alternatively,ahostcanberemovedfromaclusterwiththefollowingrequest:POST/xiv/v3/:xiv1/clusters/:cluster1{"request":{"action":"remove_host","params":{"host":"host1"}}}22IBMHyper-ScaleManagerRESTAPISpecificationsClusterrenamerequestsClusterrenamerequestsincludethefollowingcomponents:vAnactionparameterwithavalueofrename.
vAparamsparameter,containingthefollowingparameters:–name:Theclustername.
–new_name:Thenewnameofthecluster.
Example:POST/xiv/v3/:xiv1/clusters{"request":[{"action":"rename","params":{"name":"cluster1","new_name":"cluster2"}}]}Alternatively,aclustercanberenamedwiththefollowingrequest:POST/xiv/v3/:xiv1/clusters/:cluster1{"request":{"action":"rename","params":{"new_name":"cluster2"}}}ClusterdeletionrequestsClusterdeletionrequestsincludethefollowingcomponents:vAnactionparameterwithavalueofdelete.
vAparamsparameter,containingthefollowingparameters:–name:Theclustername.
Example:POST/xiv/v3/:xiv1/clusters{"request":[{"action":"delete","params":{"name":"c1"}}]}Alternatively,aclustercanbedeletedwitheitherofthefollowingrequests:Chapter4.
Updaterequests23POST/xiv/v3/:xiv1/clusters/:cluster1{"request":[{"action":"delete"}]}DELETE/xiv/v3/:xiv1/clusters/:c1HostportupdaterequestsHostportsrepresentportsthataredefinedonthehost/clientside.
Asinglehostportnameiscreatedbyconcatenatingtheporttype(fcoriscsi),hostname(host),andportname(port),asfollows:vForFCports:fc:h1:p1,whereh1isthehostname,andp1istheportname.
vForiSCSIports:iscsi:h1:p1,whereh1isthehostname,andp1istheportnameThefollowingtypesofhostportupdaterequestsaresupported.
vHostportcreationrequestsvHostportdeletionrequestsHostportcreationrequestsHostportcreationrequestsincludethefollowingcomponents:vAnactionparameterwithavalueofcreate.
vAparamsparameter,containingthefollowingparameters:–port:Theportname.
–host:Thehostname.
–type:Theporttype.
Possiblevaluesincludeiscsiandfc.
Example:POST/xiv/v3/:xiv1/host_ports{"request":[{"action":"create","params":{"port":"10000000C9926DCA","host":"h1","type":"fc"}}]}HostportdeletionrequestsHostportdeletionrequestsincludethefollowingcomponents:vAnactionparameterwithavalueofdelete.
vAparamsparameter,containingthefollowingparameters:–port:Theportname.
–host:Thehostname.
24IBMHyper-ScaleManagerRESTAPISpecifications–type:Theporttype.
Possiblevaluesincludeiscsiandfc.
Example:POST/xiv/v3/:xiv1/host_ports{"request":[{"action":"delete","params":{"port":"10000000C9926DCA","host":"h1","type":"fc"}}]}Alternatively,deletingFCportmappingscanbedoneusingeitherofthefollowingrequests(whereh1isthehostnameandp1istheportname):POST/xiv/v3/:xiv1/host_ports/:fc:h1:p1{"request":[{"action":"delete"}]}DELETE/xiv/v2/:xiv1/host_ports/:fc:h1:p1Likewise,deletingiSCSIportmappingscanbedoneusingeitherofthefollowingrequests(whereh1isthehostnameandp1istheportname):POST/xiv/v3/:xiv1/host_ports/:iscsi:h1:p1{"request":[{"action":"delete"}]}DELETE/xiv/v3/:xiv1/host_ports/:iscsi:h1:p1VolumemappingupdaterequestsVolumemappingisanartificial/virtualobject;itrepresentsrelations/mappingsbetweenhosts(orclusters)andvolumes.
Asinglemappingnameiscreatedbyconcatenatingthetype(clusterorhost)withthecluster/hostnameandvolumename.
Forexample,host:h1:v1representshostvolumemapping,whilecluster:c1:v1representsclustervolumemapping.
Thefollowingtypesofvolumemappingupdaterequestsaresupported.
v"Volumemappingcreationrequests"onpage26v"Volumemappingdeletionrequests"onpage26Chapter4.
Updaterequests25VolumemappingcreationrequestsVolumemappingcreationrequestsincludethefollowingcomponents:vAnactionparameterwithavalueofcreate.
vAparamsparameter,containingthefollowingparameters:–volume:Thevolumename.
–host_cluster_name:Thehostnameforhostmappingsorclusternameforclustermappings.
–map_type:Themappingtype.
Possiblevaluesincludehost(forhostmappings)andcluster(forclustermappings).
–lun:TheLUNID.
Exampleofhostmappingcreation:POST/xiv/v3/:xiv1/vol_maps{"request":[{"action":"create","params":{"volume":"vol1","host_cluster_name":"h1","map_type":"host","lun":"3"}}]}Exampleofclustermappingcreation:POST/xiv/v3/:xiv1/vol_maps{"request":[{"action":"create","params":{"volume":"vol1","host_cluster_name":"c1","map_type":"cluster","lun":"3"}}]}VolumemappingdeletionrequestsVolumemappingdeletionrequestsincludethefollowingcomponents:vAnactionparameterwithavalueofdelete.
vAparamsparameter,containingthefollowingparameters:–volume:Thevolumename.
–host_cluster_name:Thehostnameforhostmappingsorclusternameforclustermappings.
–map_type:Themappingtype.
Possiblevaluesincludehost(forhostmappings)andcluster(forclustermappings).
Exampleofhostmappingdeletion:26IBMHyper-ScaleManagerRESTAPISpecificationsPOST/xiv/v3/:xiv1/vol_maps{"request":[{"action":"delete","params":{"volume":"vol1","host_cluster_name":"h1","map_type":"host"}}]}Exampleofclustermappingdeletion:POST/xiv/v3/:xiv1/vol_maps{"request":[{"action":"delete","params":{"volume":"vol1","host_cluster_name":"c1","map_type":"cluster"}}]}PoolupdaterequestsThefollowingtypesofpoolupdaterequestsaresupported.
v"Poolcreationrequests"v"Poolresizerequests"onpage28v"Poolresizesnapshotsizerequests"onpage28v"Poolrenamerequests"onpage29v"Pooldeletionrequests"onpage30PoolcreationrequestsPoolcreationrequestsincludethefollowingcomponents:vAnactionparameterwithavalueofcreate.
vAparamsparameter,containingthefollowingparameters:–name:Thepoolname.
–size:Virtualcapacityofthestoragepool,inGB.
–snap_size:Thesize,inGB,reservedforsnapshots.
–domain(optional):Thenameofthedomaintoassociate.
Ifthisparameterisomitted,thenthepoolwillnotbeassociatedwithanydomain.
Example:Chapter4.
Updaterequests27POST/xiv/v3/:xiv1/pools{"request":[{"action":"create","params":{"name":"p1","size":"1700","snap_size":"170","domain":"domain1"}}]}PoolresizerequestsPoolresizerequestsincludethefollowingcomponents:vAnactionparameterwithavalueofresize_pool_size.
vAparamsparameter,containingthefollowingparameters:–name:Thepoolname.
–size:Virtualcapacityofthestoragepool,inGB.
Example:POST/xiv/v3/:xiv1/pools{"request":[{"action":"resize_pool_size","params":{"name":"p1","size":"1700"}}]}Alternatively,apoolcanberesizedusingthefollowingrequest:POST/xiv/v3/:xiv1/pools/:p1{"request":{"action":"resize_pool_size","params":{"size":"1700"}}}PoolresizesnapshotsizerequestsPoolresizesnapshotsizerequestsincludethefollowingcomponents:vAnactionparameterwithavalueofresize_snapshot_size.
vAparamsparameter,containingthefollowingparameters:–name:Thepoolname.
–snap_size:Thenewsize,inGB,reservedforsnapshots.
Example:28IBMHyper-ScaleManagerRESTAPISpecificationsPOST/xiv/v3/:xiv1/pools{"request":[{"action":"resize_snapshot_size","params":{"name":"p1","snap_size":"170"}}]}Alternatively,thesnapshotsizecanberesizedusingthefollowingrequest:POST/xiv/v3/:xiv1/pools/:p1{"request":{"action":"resize_snapshot_size","params":{"snap_size":"170"}}}PoolrenamerequestsPoolrenamerequestsincludethefollowingcomponents:vAnactionparameterwithavalueofrename.
vAparamsparameter,containingthefollowingparameters:–name:Thepoolname.
–new_name:Thenewnameofthepool.
Example:POST/xiv/v3/:xiv1/pools{"request":[{"action":"rename","params":{"name":"pool1","new_name":"pool2"}}]}Alternatively,apoolcanberenamedusingthefollowingrequest:POST/xiv/v3/:xiv1/pools/:pool1{"request":{"action":"rename","params":{"new_name":"pool2"}}}Chapter4.
Updaterequests29PooldeletionrequestsPooldeletionrequestsincludethefollowingcomponents:vAnactionparameterwithavalueofdelete.
vAparamsparameter,containingthefollowingparameter:–name:Thepoolname.
Example:POST/xiv/v3/:xiv1/pools{"request":[{"action":"delete","params":{"name":"pool1"}}]}Alternatively,apoolcanbedeletedusingeitherofthethefollowingrequests,wherep1isthepoolname:POST/xiv/v3/:xiv1/pools/:p1{"request":[{"action":"delete"}]}DELETE/xiv/v3/:xiv1/pools/:p1VolumesnapshotupdaterequestsThefollowingtypesofvolumesnapshotupdaterequestsaresupported.
v"Volumesnapshotcreationrequests"v"Volumesnapshotoverwriterequests"onpage31v"Volumesnapshotlockrequests"onpage31v"Volumesnapshotunlockrequests"onpage32v"Volumesnapshotdeletionrequests"onpage32VolumesnapshotcreationrequestsVolumesnapshotcreationrequestsincludethefollowingcomponents:vAnactionparameterwithavalueofcreate.
vAparamsparameter,containingthefollowingparameters:–source:Thenameofthevolume.
–target(optional):Thesnapshotname.
–delete_priority(optional):Thepriority.
Possiblevaluesareintegers0–4,andthedefaultvalueis1.
Example:30IBMHyper-ScaleManagerRESTAPISpecificationsPOST/xiv/v3/:xiv1/snapshots{"request":[{"action":"create","params":{"source":"vol1","target":"snapshot1","delete_priority":"2"}}]}VolumesnapshotoverwriterequestsVolumesnapshotoverwriterequestsincludethefollowingcomponents:vAnactionparameterwithavalueofoverwrite.
vAparamsparameter,containingthefollowingparameters:–source:Thenameofthevolume.
–target:Thesnapshotname.
Example:POST/xiv/v3/:xiv1/snapshots{"request":[{"action":"overwrite","params":{"source":"vol1","target":"snapshot1"}}]}Alternatively,thevolumesnapshotmaybeoverwrittenusingthefollowingupdaterequest,wherethesnapshotnameisusedasapartoftheURL:POST/xiv/v3/:xiv1/snapshots/snapshot1{"request":[{"action":"overwrite","params":{"source":"vol1"}}]}VolumesnapshotlockrequestsVolumesnapshotlockrequestsincludethefollowingcomponents:vAnactionparameterwithavalueoflock.
vAparamsparameter,containingthefollowingparameter:–name:Thesnapshotname.
Example:Chapter4.
Updaterequests31POST/xiv/v3/:xiv1/snapshots{"request":[{"action":"lock","params":{"name":"snapshot1"}}]}Alternatively,asnapshotmaybelockedusingthefollowingupdaterequest,wheresnapshot1isthevolumesnapshotname:POST/xiv/v3/:xiv1/snapshots/snapshot1{"request":{"action":"lock"}}}VolumesnapshotunlockrequestsVolumesnapshotunlockrequestsincludethefollowingcomponents:vAnactionparameterwithavalueofunlock.
vAparamsparameter,containingthefollowingparameter:–name:Thesnapshotname.
Example:POST/xiv/v3/:xiv1/snapshots{"request":[{"action":"unlock","params":{"name":"snapshot1"}}]}Alternatively,asnapshotmaybeunlockedusingthefollowingupdaterequest,wheresnapshot1isthevolumesnapshotname:POST/xiv/v3/:xiv1/snapshots/snapshot1{"request":{"action":"unlock"}}}VolumesnapshotdeletionrequestsVolumesnapshotdeletionrequestsincludethefollowingcomponents:vAnactionparameterwithavalueofdelete.
vAparamsparameter,containingthefollowingparameter:–name:Thesnapshotname.
32IBMHyper-ScaleManagerRESTAPISpecificationsExample:POST/xiv/v3/:xiv1/snapshots{"request":[{"action":"delete","params":{"name":"snapshot1"}}]}Alternatively,asnapshotcanalsobedeletedusingeitherofthefollowingupdaterequests,wheresnapshot1isthevolumesnapshotname:POST/xiv/v3/:xiv1/snapshots/snapshot1{"request":[{"action":"delete"}]}DELETE/xiv/v3/:xiv1/snapshots/:snapshot1PerformanceclassupdaterequestsThefollowingtypesofperformanceclassupdaterequestsaresupported.
v"Performanceclasscreationrequests"v"PerformanceclassupdateIOPSlimitrequests"onpage34v"Performanceclassupdatebandwidthlimitrequests"onpage35v"Performanceclassrenamerequests"onpage35v"Performanceclassaddvolumerequests"onpage36v"Performanceclassremovevolumerequests"onpage37v"Performanceclassaddpoolrequests"onpage37v"Performanceclassremovepoolrequests"onpage38v"Performanceclassaddhostrequests"onpage40v"Performanceclassremovehostrequests"onpage40v"Performanceclassdeletionrequests"onpage41PerformanceclasscreationrequestsPerformanceclasscreationrequestsincludethefollowingcomponents:vAnactionparameterwithavalueofcreate.
vAparamsparameter,containingthefollowingparameters:–name:Theperformanceclassname.
–interface_ops_limit:TheIOPSlimitforthisperformanceclass–interface_bw_limit:Thebandwidthlimitforthisperformanceclass.
–type:Theperformanceclasstype.
PossiblevaluesareSHAREDandINDEPENDENT.
SelectingSHARED,enablesthetransparentanddynamicsharingofdatabetweenmultipleentities.
IfINDEPENDENTisselected,multipleentitiesdoChapter4.
Updaterequests33notsharedata.
Forexample,ifinterface_ops_limitissetto100,and2volumesareattachedtotheperformanceclass,selectingSHAREDwillsplittheIOPSof100betweenthe2volumes.
SelectingINDEPENDENTwillallocatetheIOPSof100toeachvolume.
POST/xiv/v3/:xiv1/perf_classes{"request":[{"action":"create","params":{"name":"gold","interface_iops_limit":"1500","interface_bw_limit":"5000","type":"SHARED"}}]}Alternatively,theperformanceclasscanbecreatedbyusingthefollowingrequest(wheregoldisthenameoftheperformanceclass).
Forexample:POST/xiv/v3/:xiv1/perf_classes/:gold{"request":[{"action":"create","params":{"interface_iops_limit":"1500","interface_bw_limit":"5000","type":"SHARED"}}]}PerformanceclassupdateIOPSlimitrequestsPerformanceclassupdateIOPSlimitrequestsincludethefollowingcomponents:vAnactionparameterwithavalueofupdate_iops_limit.
vAparamsparameter,containingthefollowingparameters:–name:Theperformanceclassname.
–interface_iops_limit:Thenewiopslimitforthisperformanceclass.
Example:POST/xiv/v3/:xiv1/perf_classes{"request":[{"action":"update_iops_limit","params":{"name":"gold","interface_iops_limit":"1700"}}]}Alternatively,aniopslimitcanbeupdatedusingthefollowingrequest:34IBMHyper-ScaleManagerRESTAPISpecificationsPOST/xiv/v3/:xiv1/perf_classes/:gold{"request":{"action":"update_iops_limit","params":{"interface_iops_limit":"1700"}}}PerformanceclassupdatebandwidthlimitrequestsPerformanceclassupdatebandwidthlimitrequestsincludethefollowingcomponents:vAnactionparameterwithavalueofupdate_bw_limit.
vAparamsparameter,containingthefollowingparameters:–name:Theperformanceclassname.
–interface_bw_limit:Thenewbandwidthlimitforthisperformanceclass.
POST/xiv/v3/:xiv1/perf_classes{"request":[{"action":"update_bw_limit","params":{"name":"gold","interface_bw_limit":"5000"}}]}Alternatively,abandwidthlimitcanbeupdatedbyusingthefollowingrequest:POST/xiv/v3/:xiv1/perf_classes/:gold{"request":{"action":"update_bw_limit","params":{"interface_bw_limit":"1700"}}}PerformanceclassrenamerequestsPerformanceclassrenamerequestsincludethefollowingcomponents:vAnactionparameterwithavalueofrename.
vAparamsparameter,containingthefollowingparameters:–name:Theperformanceclassname.
–new_name:Thenewnameoftheperformanceclass.
Chapter4.
Updaterequests35POST/xiv/v3/:xiv1/perf_classes{"request":[{"action":"rename","params":{"name":"gold","new_name":"silver"}}]}Alternatively,aperformanceclasscanberenamedbyusingthefollowingrequest:POST/xiv/v3/:xiv1/perf_classes/:gold{"request":{"action":"rename","params":{"new_name":"silver"}}}PerformanceclassaddvolumerequestsPerformanceclassaddvolumerequestsincludethefollowingcomponents:vAnactionparameterwithavalueofadd_volume.
vAparamsparameter,containingthefollowingparameters:–name:Thenameoftheperformanceclasstowhichthevolumeisadded.
–volume:Thenameofthevolumetoadd.
POST/xiv/v3/:xiv1/perf_classes{"request":[{"action":"add_volume","params":{"name":"gold","volume":"vol1"}}]}Alternatively,addingavolumetoaperformanceclasscanbedonebyusingthefollowingrequest:POST/xiv/v3/:xiv1/perf_classes/:gold{"request":{"action":"add_volume","params":{"volume":"vol1"}}}36IBMHyper-ScaleManagerRESTAPISpecificationsPerformanceclassremovevolumerequestsPerformanceclass"removevolume"requestsincludethefollowingcomponents:vAnactionparameterwithavalueofremove_volume.
vAparamsparameter,containingthefollowingparameters:–volume:Thenameofthevolumetoremove.
POST/xiv/v3/:xiv1/perf_classes{"request":[{"action":"remove_volume","params":{"volume":"vol1"}}]}Alternatively,removingavolumetoaperformanceclasscanbedonebyusingthefollowingrequest:POST/xiv/v3/:xiv1/perf_classes/:gold{"request":{"action":"remove_volume","params":{"volume":"vol1"}}}PerformanceclassaddpoolrequestsPerformanceclassaddpoolrequestsincludethefollowingcomponents:vAnactionparameterwithavalueofadd_pool.
vAparamsparameter,containingthefollowingparameters:–name:Thenameoftheperformanceclasstowhichthepoolisadded.
–pool:Thenameofthepooltoadd.
POST/xiv/v3/:xiv1/perf_classes{"request":[{"action":"add_pool","params":{"name":"gold","pool":"pool1"}}]}Alternatively,addingapooltoaperformanceclasscanbedonebyusingthefollowingrequest:Chapter4.
Updaterequests37POST/xiv/v3/:xiv1/perf_classes/:gold{"request":{"action":"add_pool","params":{"pool":"pool1"}}}PerformanceclassremovepoolrequestsPerformanceclassremovepoolrequestsincludethefollowingcomponents:vAnactionparameterwithavalueofremove_pool.
vAparamsparameter,containingthefollowingparameters:–pool:Thenameofthepooltoremove.
Example:POST/xiv/v3/:xiv1/perf_classes{"request":[{"action":"remove_pool","params":{"pool":"pool1"}}]}Alternatively,removingapoolfromaperformanceclasscanbedoneusingthefollowingrequest:POST/xiv/v3/:xiv1/perf_classes/:gold{"request":{"action":"remove_pool","params":{"pool":"pool1"}}}PerformanceclassadddomainrequestsPerformanceclassadddomainrequestsincludethefollowingcomponents:vAnactionparameterwithavalueofadd_domain.
vAparamsparameter,containingthefollowingparameters:–name:Thenameoftheperformanceclasstowhichthedomainisadded.
–domain:Thenameofthedomaintoadd.
38IBMHyper-ScaleManagerRESTAPISpecificationsPOST/xiv/v3/:xiv1/perf_classes{"request":[{"action":"add_domain","params":{"name":"gold","domain":"domain1"}}]}Alternatively,addingadomaintoaperformanceclasscanbedonebyusingthefollowingrequest:POST/xiv/v3/:xiv1/perf_classes/:gold{"request":{"action":"add_domain","params":{"domain":"domain1"}}}PerformanceclassremovedomainrequestsPerformanceclassremovedomainrequestsincludethefollowingcomponents:vAnactionparameterwithavalueofremove_domain.
vAparamsparameter,containingthefollowingparameters:–domain:Thenameofthedomaintoremove.
Example:POST/xiv/v3/:xiv1/perf_classes{"request":[{"action":"remove_domain","params":{"domain":"domain1"}}]}Alternatively,removingadomainfromaperformanceclasscanbedoneusingthefollowingrequest:POST/xiv/v3/:xiv1/perf_classes/:gold{"request":{"action":"remove_domain","params":{"domain":"domain1"}}}Chapter4.
Updaterequests39PerformanceclassaddhostrequestsPerformanceclassaddhostrequestsincludethefollowingcomponents:vAnactionparameterwithavalueofadd_host.
vAparamsparameter,containingthefollowingparameters:–name:Thenameoftheperformanceclasstowhichthehostisadded.
–host:Thenameofthehosttoadd.
Example:POST/xiv/v3/:xiv1/perf_classes{"request":[{"action":"add_host","params":{"name":"gold","host":"host1"}}]}Alternatively,addingahosttoaperformanceclasscanbedoneusingthefollowingrequest:POST/xiv/v3/:xiv1/perf_classes/:gold{"request":{"action":"add_host","params":{"host":"host1"}}}PerformanceclassremovehostrequestsPerformanceclassremovehostrequestsincludethefollowingcomponents:vAnactionparameterwithavalueofremove_host.
vAparamsparameter,containingthefollowingparameters:–host:Thenameofthehosttoremove.
Example:POST/xiv/v3/:xiv1/perf_classes{"request":[{"action":"remove_host","params":{"host":"host1"}}]}Alternatively,removingahostfromaperformanceclasscanbedoneusingthefollowingrequest:40IBMHyper-ScaleManagerRESTAPISpecificationsPOST/xiv/v3/:xiv1/perf_classes/:gold{"request":{"action":"remove_host","params":{"host":"host1"}}}PerformanceclassdeletionrequestsPerformanceclasscreationrequestsincludethefollowingcomponents:vAnactionparameterwithavalueofdelete.
vAparamsparameter,containingthefollowingparameters:–name:Theperformanceclassname.
Example:POST/xiv/v3/:xiv1/perf_classes{"request":[{"action":"delete","params":{"name":"gold"}}]}Alternatively,theperformanceclassmaybedeletedusingthefollowingrequest(wheregoldisthenameoftheperformanceclass).
Forexample:POST/xiv/v3/:xiv1/perf_classes/:gold{"request":[{"action":"delete"}]}DELETE/xiv/v3/:xiv1/perf_classes/:goldUpdateresponseformatTheupdateresponseisdefinedasanobjectthathasastatusfieldonly,asdefinedinthequeryresponseformat.
SeeQueryresponseformat.
Exampleofasuccessfulresponsetoanupdaterequest:Chapter4.
Updaterequests41Request-GET/xiv/v3/:xiv1/volumes/:vol1.
.
.
Response-HTTP/1.
1200OK.
.
.
{"status":{"server":{"status":"0","message":"OK"}"failed_systems":[]}}Exampleofafailedrequest:Request-DELETE/xiv/v3/:xiv1/volumes/:vol1.
.
.
Response-HTTP/1.
1500InternalServerError.
.
.
{"status":{"server":{"status":"5","message":"Updaterequestfailedwithreason:Volume'vol1'doesnotexist"}"failed_systems":[]}}42IBMHyper-ScaleManagerRESTAPISpecificationsChapter5.
RequestURLdefinitionsThefollowinggroupsofrequestURLsaredefined:v"SystemrequestURLs"v"VolumerequestURLs"v"ClusterrequestURLs"onpage44v"SystemFCportrequestURLs"onpage44v"SystemiSCSIportrequestURLs"onpage44v"HostportrequestURLs"onpage44v"VolumemappingrequestURLs"onpage44v"PoolrequestURLs"onpage44v"EventrequestURLs"onpage45v"VolumesnapshotrequestURLs"onpage45SystemrequestURLsThefollowingsystemrequestURLsaredefined:vGET/xiv/v3/systems:ListsallsystempropertiesmanagedbytheHyper-ScaleManager.
vGET/xiv/v3/systems/:xiv1:Listsallspecificsystemproperties.
vGET/xiv/v3/systems/capacityReport:Generatescapacityreportforallsystemsinyourinventory.
vGET/xiv/v3/systems/:/capacityReport:Generatescapacityreportforaspecificsysteminyourinventory.
VolumerequestURLsThefollowingvolumerequestURLsaredefined:vGET/xiv/v3/volumes:Listsallvolumesonallauthorizedsystems.
vGET/POST/xiv/v3/:xiv1/volumes:Listsallvolumesonaspecificsystem;creates/updates/deletesvolumes.
vGET/xiv/v3/:xiv1/volumespool=x:Listsallvolumesinaspecificpool.
vGET/POST/DELETE/xiv/v3/:xiv1/volumes/:vol1:Listsspecificvolumeproperties;updates/deletesavolume.
HostrequestURLsThefollowinghostrequestURLsaredefined:vGET/xiv/v3/hosts:Listsallhosts'propertiesonallauthorizedsystems.
vGET/POST/xiv/v3/:xiv1/hosts:Listsallhostsonaspecificsystem;creates/updates/deleteshosts.
vGET/POST/DELETE/xiv/v3/:xiv1/hosts/:h1:Listsspecifichostproperties;deletesahost.
CopyrightIBMCorp.
2014,201643ClusterrequestURLsThefollowingclusterrequestURLsaredefined:vGET/xiv/v3/clusters:Listsallclustersonallauthorizedsystems.
vGET/POST/xiv/v3/:xiv1/clusters:Listsallhostsonaspecificsystem;creates/updates/deletesclusters.
vGET/POST/DELETE/xiv/v3/:xiv1/clusters/:cl1:Listsspecificclusterproperties;updates/deletesacluster.
SystemFCportrequestURLsThefollowingsystemFCportrequestURLsaredefined:vGET/xiv/v3/:xiv1/fc_ports:ListsallFCportsonaspecificmachine.
vGET/xiv/v3/:xiv1/fc_ports/:p1:ListspropertiesforaspecificFCport.
SystemiSCSIportrequestURLsThefollowingsystemiSCSIportrequestURLsaredefined:vGET/xiv/v3/:xiv1/iscsi_ports:ListsalliSCSIportsonaspecificmachine.
vGET/xiv/v3/:xiv1/iscsi_ports/:p1:ListspropertiesforaspecificiSCSIport.
HostportrequestURLsThefollowinghostportrequestURLsaredefined:vPOST/xiv/v3/:xiv1/host_ports:Add/removeportsto/fromaspecifichost.
vGET/xiv/v3/:xiv1/host_portshost=x:Listsallportsofaspecifichost.
vGET/xiv/v3/:xiv1/host_portsport=x:Liststhehostofaspecificport.
vGET/DELETE/xiv/v3/:xiv1/host_ports/:h1:p1:Listspropertiesofaspecificport;removesportfromahost.
VolumemappingrequestURLsThefollowingvolumemappingrequestURLsaredefined:vPOST/xiv/v3/:xiv1/vol_maps:Creates/deletesmappings.
vGET/xiv/v3/:xiv1/vol_mapshost=x:Listsallmappingsofaspecifichost.
vGET/xiv/v3/:xiv1/vol_mapscluster=x:Listsallmappingsofaspecificcluster.
vGET/xiv/v3/:xiv1/vol_mapsvolume=x:Listsallmappingsofaspecificvolume.
vGET/DELETE/xiv/v3/:xiv1/vol_maps/:cluster:c1:vol1:Listspropertiesofaspecificmapping;deletesthemapping.
vGET/DELETE/xiv/v3/:xiv1/vol_maps/:host:h1:vol1:Listspropertiesofaspecificmapping;deletesthemapping.
PoolrequestURLsThefollowingpoolrequestURLsaredefined:vGET/xiv/v3/pools:Listsallpoolsonallauthorizedsystems.
vGET/POST/xiv/v3/:xiv1/pools:Listsallpoolsonaspecificsystem;creates/updates/deletespools.
vGET/POST/DELETE/xiv/v3/:xiv1/hosts/:h1:Listspropertiesofaspecificpool;deletesapool.
44IBMHyper-ScaleManagerRESTAPISpecificationsEventrequestURLsThefollowingeventrequestURLisdefined:vGET/xiv/v3/:xiv1/events/:Listseventsfromaspecificsystem.
VolumesnapshotrequestURLsThefollowingvolumesnapshotrequestURLsaredefined:vGET/xiv/v3/snapshots:Listsallsnapshotsonallauthorizedsystems.
vGET/xiv/v3/:xiv1/snapshotsvolume=vol1:Listsallsnapshotsofaspecificvolume.
vGET/POST/xiv/v3/:xiv1/snapshots:Listsallsnapshotsonaspecificsystem;creates/updates/deletessnapshots.
vGET/POST/DELETE/xiv/v3/:xiv1/snapshots/:sn1:Listspropertiesofaspecificsnapshot;deletesasnapshot.
PerformanceclassrequestURLsThefollowingperformanceclassrequestURLsaredefined:vGET/xiv/v3/perf_classes:Listsallperformanceclassesonallauthorizedsystems.
vGET/POST/xiv/v3/:xiv1/perf_classes:Listsallperformanceclassesonaspecificsystem;creates/updates/deletesperformanceclasses.
vGET/POST/DELETE/xiv/v3/:xiv1/perf_classes/:gold:Listspropertiesofaspecificperformanceclass;updatesaperformanceclassordeletesaperformanceclass.
vGET/xiv/v3/:xiv1/volumesperf_class=gold:Listsallofthevolumesthatareapartofaspecificperformanceclass.
vGET/xiv/v3/:xiv1/hostsperf_class=gold:Listsallofthehoststhatareapartofaspecificperformanceclass.
vGET/xiv/v3/:xiv1/poolsperf_class=gold:Listsallofthepoolsthatareapartofaspecificperformanceclass.
Chapter5.
RequestURLdefinitions4546IBMHyper-ScaleManagerRESTAPISpecificationsChapter6.
ResourcedefinitionsTheresourceformatsthatarereturnedbytheRESTAPIaredefinedinthefollowingsections:v"Systemresourcedefinitions"v"Volumeresourcedefinitions"onpage48v"Hostresourcedefinitions"onpage48v"Clusterresourcedefinitions"onpage49v"SystemFCportresourcedefinitions"onpage49v"SystemiSCSIportresourcedefinitions"onpage50v"Hostportresourcedefinitions"onpage50v"Volumemappingresourcedefinitions"onpage50v"Poolresourcedefinitions"onpage51v"Eventresourcedefinitions"onpage51v"Volumesnapshotresourcedefinitions"onpage51SystemresourcedefinitionsThesystemresourceformatsthatarereturnedbytheRESTAPIareasfollows:{"system":{"hard_capacity":"""ip_addresses":[1]-0:{"ip":"gen4d-64b"}"safe_mode":"false""system_state":"on""soft_capacity":"""compression_state":"""free_soft_capacity":"""ref":"/xiv/v3/systems/:gen4d-64b""target_state":"on""name":"gen4d-64b""physical_free":"1937000000000""redundancy_status":"FullyProtected""id":"XIVgen4d-64b:6013794:9835:415""physical_size":"1963000000000"}}Note:ThesystemresourceformatisthesameforbothGen3andGen4systems.
However,inGen3systems,thevaluesforphysical_sizeandphysical_freeareempty.
WhileinGen4systems,thevaluesforhard_capacity,soft_capacity,andfree_soft_capacityareempty.
CopyrightIBMCorp.
2014,201647VolumeresourcedefinitionsThevolumeresourceformatsthatarereturnedbytheRESTAPIareasfollows:{"volume":{"size_on_disk":"103000000000","pool_ref":"/xiv/v3/:6011947b/pools/:Pool_DM","size":"103249084416","wwn":"001738002EAB3AAB","capacity_used_by_snapshots":"0","id":"6d5d14d03ab5","ref":"/xiv/v3/:6011947b/volumes/:Vol_RTC_004","system":"6011947b","pool":"Pool_DM","name":"Vol_RTC_004","mirrored":"false","cg":"","locked":"false","used_capacity":"12000000000","perf_class_ref":"/xiv/v3/:gen4d-54c/perf_classes/:TaylorS","perf_class":"TaylorS","estimated_min_delete_size":"0"}Note:Theperf_class_refparameterisapplicableonlytoobjectslimitedbyQOS.
HostresourcedefinitionsThehostresourceformatsthatarereturnedbytheRESTAPIareasfollows:{"host":{"ports":[{"type":"fc""name":"1234567890123001""ref":"/xiv/v3/:mn44/host_ports/:rest-host-sa-def:1234567890123001",},{"type":"iscsi""name":"rest-host-sa-def_1""ref":"/xiv/v3/:mn44/host_ports/:rest-host-sa-def:rest-host-sa-def_1",}],"perf_class":"none","ref":"/xiv/v3/:mn44/hosts/:rest-host-sa-def","type":"standard","cluster":"","id":"101255","name":"rest-host-sa-def","system":"mn44","perf_class_ref":"/xiv/v3/:gen4d-54c/perf_classes/:TaylorS","perf_class":"TaylorS","domains":[{"domain":"domain1"},{"domain":"domain2"}]}Note:Theperf_class_refparameterisapplicableonlytoobjectslimitedbyQOS.
48IBMHyper-ScaleManagerRESTAPISpecificationsClusterresourcedefinitionsTheclusterresourceformatsthatarereturnedbytheRESTAPIareasfollows:{"cluster":{"ref":"/xiv/v3/:mn44/clusters/:rest-cluster-def","type":"standard","id":"101239","name":"rest-cluster-def","hosts":[{"name":"rest-host-cd-def-1","ref":"/xiv/v3/:mn44/hosts/:rest-host-cd-def-1"},{"name":"rest-host-cd-def-2","ref":"/xiv/v3/:mn44/hosts/:rest-host-cd-def-2"}],"system":"mn44","domains":[{"domain":"domain1"},{"domain":"domain2"}]}}SystemFCportresourcedefinitionsThesystemFCportresourceformatsthatarereturnedbytheRESTAPIareasfollows:{"fc_port":{"ref":"/xiv/v3/:mn44/fc_ports/:1234567890123001","id":"101280","wwpn":"1234567890123001","module":"6","port_number":"1","status":"OK","role":"Target","state":"Online","user_enabled":"true","configured_rate":"Auto","current_rate":"4","error_count":"0","system":"mn44"}}Chapter6.
Resourcedefinitions49SystemiSCSIportresourcedefinitionsThesystemiSCSIportresourceformatsthatarereturnedbytheRESTAPIareasfollows:{"iscsi_port":{"ref":"/xiv/v3/:mn44/iscsi_ports/:myport","id":"101280","name":"myport","address":"1.
1.
1.
13","netmask":"255.
255.
255.
0","gateway":"1.
1.
1.
1","mtu":"4500","module":"7","port_number":"1","system":"mn44"}}HostportresourcedefinitionsThehostportresourceformatsthatarereturnedbytheRESTAPIareasfollows:{"host_port":{"ref":"/xiv/v3/:mn44/host_ports/:rest-host-sa-def:1234567890123001","host":"rest-host-sa-def","type":"fc","id":"101280","name":"1234567890123001","system":"mn44"}}VolumemappingresourcedefinitionsThevolumemappingresourceformatsthatarereturnedbytheRESTAPIareasfollows:{"vol_map":{"ref":"/xiv/v3/:mn44/vol_maps/:host:host_rest-host-sa-def:rest-vol-rpnoio_001","lun":"2","host":"rest-host-sa-def","cluster":"","volume":"rest-vol-rpnoio_001","id":"101215","system":"mn44"}}50IBMHyper-ScaleManagerRESTAPISpecificationsPoolresourcedefinitionsThepoolresourceformatsthatarereturnedbytheRESTAPIareasfollows:{"pool":{"used_by_snapshots":"0","snapshot_size":"309000000000","size":"23050000000000","id":"6dc714800006","ref":"/xiv/v3/:6011947b/pools/:Clippers","system":"6011947b","used_by_volumes":"860000000000","name":"Clippers","domain":"no-domain","locked":"false","perf_class_ref":"/xiv/v3/:gen4d-54c/perf_classes/:TaylorS","perf_class":"TaylorS"}}Note:Theperf_class_refparameterisapplicableonlytoobjectslimitedbyQOS.
EventresourcedefinitionsTheeventresourceformatsthatarereturnedbytheRESTAPIareasfollows:{"event":{"ref":"/xiv/:mn44/events/:111111","id":"111111","code":"USER_LOGIN_HAS_SUCCEEDED","severity":"Informational","timestamp":"1234567890","description":"User'admin'fromIP'X.
X.
X.
X'successfullyloggedintothesystem.
","system":"mn44"}}VolumesnapshotresourcedefinitionsThevolumesnapshotresourceformatsthatarereturnedbytheRESTAPIareasfollows:{"snapshot":{"source_ref":"/xiv/v3/:6010625a/volumes/:vol1","estimated_min_delete_size":"0","delete_priority":"1","sg":"","pool_ref":"/xiv/v3/:6010625a/pools/:pool-a","creator":"admin","size":"17000000000","id":"5811450000d","wwn":"001738002981000D","ref":"/xiv/v3/:6010625a/snapshots/:vol1.
snapshot_00001","system":"6010625a","source":"vol1","pool":"pool-a","name":"vol1.
snapshot_00001","cg":"","locked":"true","perf_class_ref":"/xiv/v3/:gen4d-54c/perf_classes/:TaylorS","perf_class":"TaylorS"}}Chapter6.
Resourcedefinitions51Note:Theperf_class_refparameterisapplicableonlytoobjectslimitedbyQOS.
PerformanceclassresourcedefinitionsTheperformanceclassresourceformatsthatarereturnedbytheRESTAPIareasfollows:{"performanceClass":{"ref":"/xiv/v3/:Gen4D64a/perf_classes/:ClassQoS","system":"gen4d-54c","name":"AnotherQoS","interface_iops_limit":0,"interface_bw_limit":500,"id":"10d61720000b","type":SHARED}}52IBMHyper-ScaleManagerRESTAPISpecificationsChapter7.
ErrorhandlingEachrequesttotheRESTAPIreceivesaresponsewithtwotypesofstatuscodes:vHTTP(transport)statuscode:Aquickindicationofwhetherornottherequestsucceeded.
Someautomationscriptsmaynotparsethefullresponseincaseoferror,soitishelpfultohaveaquickindicationattheHTTPlevel.
vserverstatuscode:Providesamoredetailedapplicationlevelstatustoallowtroubleshootingincaseoferrors.
Thefollowingtopicsarecoveredinthischapter:v"HTTPstatuscodes"v"Serverstatuscodes"onpage54v"Failedsystemstatuscodes"onpage55HTTPstatuscodesThefollowingtablesliststheHTTPstatuscodesandmessagesreturnedbytheRESTAPI:Table1.
HTTPstatuscodesandmessagesHTTPstatuscodeHTTPmessageDescription200OKTherequestsucceeded.
Theresponsecontainseitheralistofresources(inresponsetoaquery)orisempty.
400BadRequestTherequestcontainsinvalidscopekeywordsorinvalidURLparameters.
ExamplesofinvalidURLparametersare:non-numericvalues,redundantparameters,etc.
401UnauthorizedTheusercredentialsprovidedarenotvalid.
404NotFoundTherequestaddressesnon-existingresource(s).
Theserverstatuscodecontainsmoredetailsaboutwhatresourcewasnotfound.
500InternalServerErrorTherequestisvalid,butsomeapplicationlevelerroroccurred.
Seeserverstatusformoreinformation.
CopyrightIBMCorp.
2014,201653ServerstatuscodesThefollowingtablesliststheserverstatuscodesandmessagesreturnedbytheRESTAPI:Table2.
Serverstatuscodes,correlatedtoHTTPstatuscodesHTTPstatuscodeServerstatuscodeServermessageDescription2000OKTherequestsucceeded.
Theresponsecontainseitheralistofresources(inresponsetoaquery)orisempty.
5001RobotauthenticationfailedTheservercannotconnecttoasupportedstoragesystemwithrobotusercredentials.
Mostlikely,therobotuserpasswordisnotsetontheserver.
4012UnauthorizedInvalidusercredentialsweresuppliedforaqueryorupdateoperation.
5003NosystemsconnectedAllsupportedstoragesystemsthatareaddressedintherequestaredisconnected.
4044ResourcenamedXoftypeYnotfoundThequeryrequestaddressedanon-existentresource.
Theservermessagecontainsthemissingresourcenameandtype.
Thisisusefulfortroubleshootingcomplexrequests,suchasmappingofthesystem'shost.
5005RequestfailedTherequestexecutionfailed.
Thefailed_systemspartcontainsthereason.
4006InvalidRequest.
Therequestisinvalid.
Themessagecontainstheexactreason.
5008NomanagedsystemsconfiguredNosupportedstoragesystemsaremanagedbytheserver.
5009ServergeneralerrorSomegeneralerroroccurredduringprocessing.
54IBMHyper-ScaleManagerRESTAPISpecificationsFailedsystemstatuscodesWhenperformingmulti-systemqueries,somesupportedstoragesystemsmaybeinanerrorstate(suchasdisconnected,notauthenticated,etc.
).
Thisindicatestotheuserthatthequeryresponsedoesnotcontainresourcesfromthesesystems.
Toaddressthissituation,thereisthefailed_systemsfieldintheresponse.
Thefieldisalistthatcontainssystemsthatareinerror,accordingtothefollowingtable:Table3.
FailedsystemstatuscodesFailedsystemstatuscodeMessageDescription1RobotuserauthenticationfailedRobotusercredentialsarenotdefinedonthesystem,ortherobotpasswordisnotsetontheserver.
2UnauthorizedInvalidusercredentialsweresupplied.
3SystemisdisconnectedTheservercannotconnecttothespecificsupportedstoragesystem.
4ThesystemisnotmanagedbytheserverThespecificsupportedstoragesystemisnotmanagedbytheserver.
5Requestfailed.
Therequestfailed.
ReasoncontainsCLIcommandresponse+errorcode.
6SystemissuspendedThespecificstoragesystemissuspended.
Ifthereisamulti-systemrequestwhenallofthesystemsareinaccessible,thefollowingrulesapply:vIfallsystemsareinanUnauthorizedstate,theresponseisHTTP401,serverstatus2.
vIfallsystemsareinaRobotuserauthenticationfailedstate,theresponseisHTTP500,serverstatus1.
vForallothercases,theresponseisHTTP500,serverstatus3.
Chapter7.
Errorhandling5556IBMHyper-ScaleManagerRESTAPISpecificationsChapter8.
SecurityTheRESTAPIprotocoldoesnothaveanybuilt-insecurityfeatures,soitstronglyreliesonthetransportprotocol(HTTP)toprovidesecurity.
Specifically,thefollowingHTTPfeaturesareused:vHTTP/S:ProvidesanencryptedHTTPchannelbetweenclientandserver.
vHTTPbasicauthentication:Usedforcarryingclientprovidedcredentialstotheserver/supportedstoragesystems.
CopyrightIBMCorp.
2014,20165758IBMHyper-ScaleManagerRESTAPISpecificationsNoticesThisinformationwasdevelopedforproductsandservicesofferedintheU.
S.
A.
ThismaterialmaybeavailablefromIBMinotherlanguages.
However,youmayberequiredtoownacopyoftheproductorproductversioninthatlanguageinordertoaccessit.
IBMmaynotoffertheproducts,services,orfeaturesdiscussedinthisdocumentinothercountries.
ConsultyourlocalIBMrepresentativeforinformationontheproductsandservicescurrentlyavailableinyourarea.
AnyreferencetoanIBMproduct,program,orserviceisnotintendedtostateorimplythatonlythatIBMproduct,program,orservicemaybeused.
Anyfunctionallyequivalentproduct,program,orservicethatdoesnotinfringeanyIBMintellectualpropertyrightmaybeusedinstead.
However,itistheuser'sresponsibilitytoevaluateandverifytheoperationofanynon-IBMproduct,program,orservice.
IBMmayhavepatentsorpendingpatentapplicationscoveringsubjectmatterdescribedinthisdocument.
Thefurnishingofthisdocumentdoesnotgrantyouanylicensetothesepatents.
Youcansendlicenseinquiries,inwriting,to:IBMDirectorofLicensingIBMCorporationNorthCastleDriveArmonk,NY10504-1785U.
S.
A.
Forlicenseinquiriesregardingdouble-bytecharacterset(DBCS)information,contacttheIBMIntellectualPropertyDepartmentinyourcountryorsendinquiries,inwriting,to:IntellectualPropertyLicensingLegalandIntellectualPropertyLawIBMJapanLtd.
1623-14,Shimotsuruma,Yamato-shiKanagawa242-8502JapanThefollowingparagraphdoesnotapplytotheUnitedKingdomoranyothercountrywheresuchprovisionsareinconsistentwithlocallaw:INTERNATIONALBUSINESSMACHINESCORPORATIONPROVIDESTHISPUBLICATION"ASIS"WITHOUTWARRANTYOFANYKIND,EITHEREXPRESSORIMPLIED,INCLUDING,BUTNOTLIMITEDTO,THEIMPLIEDWARRANTIESOFNON-INFRINGEMENT,MERCHANTABILITYORFITNESSFORAPARTICULARPURPOSE.
Somestatesdonotallowdisclaimerofexpressorimpliedwarrantiesincertaintransactions,therefore,thisstatementmaynotapplytoyou.
Thisinformationcouldincludetechnicalinaccuraciesortypographicalerrors.
Changesareperiodicallymadetotheinformationherein;thesechangeswillbeincorporatedinneweditionsofthepublication.
IBMmaymakeimprovementsand/orchangesintheproduct(s)and/ortheprogram(s)describedinthispublicationatanytimewithoutnotice.
CopyrightIBMCorp.
2014,201659Anyreferencesinthisinformationtonon-IBMWebsitesareprovidedforconvenienceonlyanddonotinanymannerserveasanendorsementofthoseWebsites.
ThematerialsatthoseWebsitesarenotpartofthematerialsforthisIBMproductanduseofthoseWebsitesisatyourownrisk.
IBMmayuseordistributeanyoftheinformationyousupplyinanywayitbelievesappropriatewithoutincurringanyobligationtoyou.
Licenseesofthisprogramwhowishtohaveinformationaboutitforthepurposeofenabling:(i)theexchangeofinformationbetweenindependentlycreatedprogramsandotherprograms(includingthisone)and(ii)themutualuseoftheinformationwhichhasbeenexchanged,shouldcontact:IBMCorporationAlmadenResearch650HarryRoadBldg80,D3-304,Department277SanJose,CA95120-6099U.
S.
A.
Suchinformationmaybeavailable,subjecttoappropriatetermsandconditions,includinginsomecases,paymentofafee.
ThelicensedprogramdescribedinthisdocumentandalllicensedmaterialavailableforitareprovidedbyIBMundertermsoftheIBMCustomerAgreement,IBMInternationalProgramLicenseAgreementoranyequivalentagreementbetweenus.
Anyperformancedatacontainedhereinwasdeterminedinacontrolledenvironment.
Therefore,theresultsobtainedinotheroperatingenvironmentsmayvarysignificantly.
Somemeasurementsmayhavebeenmadeondevelopment-levelsystemsandthereisnoguaranteethatthesemeasurementswillbethesameongenerallyavailablesystems.
Furthermore,somemeasurementsmayhavebeenestimatedthroughextrapolation.
Actualresultsmayvary.
Usersofthisdocumentshouldverifytheapplicabledatafortheirspecificenvironment.
Informationconcerningnon-IBMproductswasobtainedfromthesuppliersofthoseproducts,theirpublishedannouncementsorotherpubliclyavailablesources.
IBMhasnottestedthoseproductsandcannotconfirmtheaccuracyofperformance,compatibilityoranyotherclaimsrelatedtonon-IBMproducts.
Questionsonthecapabilitiesofnon-IBMproductsshouldbeaddressedtothesuppliersofthoseproducts.
AllstatementsregardingIBM'sfuturedirectionorintentaresubjecttochangeorwithdrawalwithoutnotice,andrepresentgoalsandobjectivesonly.
Thisinformationisforplanningpurposesonly.
Theinformationhereinissubjecttochangebeforetheproductsdescribedbecomeavailable.
Thisinformationcontainsexamplesofdataandreportsusedindailybusinessoperations.
Toillustratethemascompletelyaspossible,theexamplesincludethenamesofindividuals,companies,brands,andproducts.
Allofthesenamesarefictitiousandanysimilaritytothenamesandaddressesusedbyanactualbusinessenterpriseisentirelycoincidental.
60IBMHyper-ScaleManagerRESTAPISpecificationsIfyouareviewingthisinformationsoftcopy,thephotographsandcolorillustrationsmaynotappear.
TrademarksIBM,theIBMlogo,andibm.
comaretrademarksorregisteredtrademarksofInternationalBusinessMachinesCorp.
,registeredinmanyjurisdictionsworldwide.
OtherproductandservicenamesmightbetrademarksofIBMorothercompanies.
AcurrentlistofIBMtrademarksisavailableontheWebatCopyrightandtrademarkinformationwebsite(www.
ibm.
com/legal/copytrade.
shtml).
OtherproductandservicenamesmightbetrademarksofIBMorothercompanies.
Notices6162IBMHyper-ScaleManagerRESTAPISpecificationsIBMPrintedinUSASC27-6440-03