IBMHyper‐ScaleManager4.4RESTAPIspecifications

IBM1IBMHyper‐ScaleManagerRESTAPISpecificationsIBMHyper‐ScaleManager4.
4RESTAPIspecificationsIBM2TableofContents1Introduction42Versioning43Protocoloverview43.
1DataTypes54Queryrequests54.
1Systems64.
2Volumes64.
3Hosts64.
4Clusters74.
5SystemFiberChannelPorts.
74.
6SystemISCSIPorts74.
7HostPorts84.
8VolumeMappings84.
9Pools84.
10VolumeSnapshots94.
11SnapGroups94.
12ConsistencyGroups104.
13Mirrors104.
14Three‐way‐mirrors104.
15Queryresponseformat114.
16Querypagingsupport134.
17Eventquery145Updaterequests155.
1Volumes155.
2Hosts215.
3Clusters235.
4HostPorts275.
5VolumeMappings295.
6Pools325.
7VolumeSnapshots355.
8SnapshotGroups395.
9ConsistencyGroups425.
10Mirrors45IBMHyper‐ScaleManager4.
4RESTAPIspecificationsIBM35.
11Three‐Way‐Mirrors505.
12X‐ConsistencyGroup546Updateresponseformat557Errorhandling558Security589Appendix599.
1SummaryofrequestURL's599.
2Resourcedefinitions619.
2.
1System619.
2.
2Volume619.
2.
3Host629.
2.
4Cluster639.
2.
5FCPort639.
2.
6ISCSIPort649.
2.
7HostPort649.
2.
8VolumeMapping659.
2.
9Pool659.
2.
10Event669.
2.
11VolumeSnapshots669.
2.
12SnapshotGroup669.
2.
13ConsistencyGroup.
679.
2.
14Mirrors689.
2.
15Three‐Way‐Mirrors68Table1-HTTPstatuscodes.
56Table2-Serverstatuscodes57Table3-Failedsystemsstatuscodes58IBMHyper‐ScaleManager4.
4RESTAPIspecificationsIBM41INTRODUCTIONThepurposeofthisdocumentistoprovidespecificationsoftheHyper‐ScaleManagementServerRESTAPI,referencedasAPIinthedocument.
Thedocumentcoversthefollowingareas:ProtocolspecificationsoRequestsyntaxoOutputserializationformatErrorhandlingVersioningSecurityTheAPIallowstheendusertoprocesstwomaintypesofrequests:Queryrequests–requeststhatreturnobjectentitiesmanagedbytheManagementServer(forexample,allvolumesofaspecificXIVmachine).
Updaterequests–requeststhatcreate,deleteorupdatetheobjectentitystate(forexample,createanewpoolonaspecificXIVmachine).
TheAPIusesHTTPastransportprotocolandreliesonHTTPforsomefeatures(forexample,security).
Thesectionsbelowdescribethegeneralprotocolprinciplesandoperation,whiletheexactURLsandresourcedefinitionsareprovidedintheAppendix.
2VERSIONINGThecurrentprotocolversionisv2.
ThisisindicatedintheURLbyaddingthe/v2pathtoalloftheURLs(forexample,/xiv/v2/volumes).
3PROTOCOLOVERVIEWTheprotocolreliesonHTTPmethodstosupportCRUDoperations(Create/Read/Update/Delete)HTTPPOST‐mappedtocreate/update/deleteoperationsHTTPGET‐mappedtoquery(Read)operationsHTTPDELETE–mappedtodeleteoperationsTheHTTPURIspecifiestheresourcetowhichtherequestapplies.
Therearetworesourcetypes:Singleresource–volume,port,orhostListofresources–allpoolsofaspecificXIVmachineIBMHyper‐ScaleManager4.
4RESTAPIspecificationsIBM5TheURIisbuiltfromscopespecifiersandresourcenames,prefixedwith":",forexample,/xiv/v2/:xiv2/ports/:10000000C9926DCA.
Inthisexample:/xivspecifiesmainAPIscopev2–specifiesprotocolversion(shouldbev1forversionone):xiv2–specificsystemIP/DNSname/ports–definesportsscope,forexample,wearelookingatportsinxiv110000000C9926DCA–portnameTherequestandresponseformatisJSON.
AlloftheexamplesshowninthedocumentareformattedasJSON.
3.
1DATATYPESAllofthestoragecapacitypropertiesinthequeryresponsesaregivenasintegers,inbytes.
Forexample:CapacityattributesofSystemresources,sizeattributesofVolumeresources,sizeattributesofPoolresources.
Booleanattributesaregivenastrue/false.
Forexample:MirroredattributesofVolumeresources.
Timestampsaredisplayedinmilliseconds,sincetheUnixepoch(1970‐01‐0100:00:00).
Therearetwomainrequeststypes:Queryrequests–requeststhatreturnstates–eitherasingleresourceorresourcelistsUpdaterequests‐requeststhatupdatestates(forexample,createnewvolume,updatepoolsize,etc.
)4QUERYREQUESTSAQueryisrunbyissuingtheHTTPGETcommandonaURIrepresentingeither:Collectionofresourcesalistofresourcesandtheirpropertiesisreturned(forexample,/xiv/v2/:xiv1/volumes)Singleresource–singleresourcepropertiesarereturned(forexample,/xiv/v2/:xiv1/volumes/:vol1)QueryrequestscancontainadditionalURIparameters,suchas:Filteringparameters–returnsonlyresourcesthatmatchfilteringcriteria.
Forexample,/xiv/v2/:xiv1/volumespool=mypool–allvolumesthatexistinthe"mypool"pool.
Allquerieslistedinthisdocument(excludingsystemqueries),whichreturncollectionsofresources,willsupport"bydomain"filtering.
Forexample:/xiv/v2/:xiv1/volumesdomain=d1–returnsallvolumesonagivensystem(xiv1)thatbelongtothespecifieddomain(d1).
Thisfunctionalityisoptionalandwillbeimplementedona"besteffortbase".
ChecktheAppendixforsupportedfilteringparametersinthisrelease.
IBMHyper‐ScaleManager4.
4RESTAPIspecificationsIBM6Belowareallofthepossiblequeryrequests:4.
1SYSTEMSManagementServermanagedsystemqueryrequests:Listallofthesystemsonwhichtheuserisauthorized:GET/xiv/v2/systemsListspecificsystemproperties(xiv1–systemIP/DNS):GET/xiv/v2/systems/:xiv14.
2VOLUMESVolumequeryrequests:Listallofthevolumesfromallofthesystemsonwhichtheuserisauthorized:GET/xiv/v2/volumesListallofthevolumesfromspecificmachine:GET/xiv/v2/:xiv1/volumesListallofthevolumesfromspecificmachineandpool(wherep1isthepoolname):GET/xiv/v2/:xiv1/volumespool=p1Listspecificvolumeproperties(wherevol1isthevolumename)GET/xiv/v2/:xiv1/volumes/:vol14.
3HOSTSHostqueryrequests:Listallofthehostsfromallofthesystemsonwhichtheuserisauthorized:GET/xiv/v2/hostsListallofthehostsfromaspecificmachine:GET/xiv/v2/:xiv1/hostsListallofthehostsfromaspecificmachinethatbelongtothegivencluster(wherecl1istheclustername):IBMHyper‐ScaleManager4.
4RESTAPIspecificationsIBM7GET/xiv/v2/:xiv1/hostscluster=cl1Listspecifichostproperties(whereh1isthehostname)GET/xiv/v2/:xiv1/hosts/:h14.
4CLUSTERSClusterqueryrequests:Listalloftheclustersfromallofthesystemsonwhichtheuserisauthorized:GET/xiv/v2/clustersListallclustersfromaspecificmachine:GET/xiv/v2/:xiv1/clustersListspecificclusterproperties(wherec1istheclustername)GET/xiv/v2/:xiv1/clusters/:c14.
5SYSTEMFIBERCHANNELPORTSSystemsFCportqueryrequests:ListalloftheFCportsfromaspecificmachineGET/xiv/v2/:xiv1/fc_portsListspecificFCportproperties(wherep1istheportname)GET/xiv/v2/:xiv1/fc_ports/:p14.
6SYSTEMISCSIPORTSSystemISCSIportqueryrequests:ListalloftheISCSIportsfromaspecificmachineGET/xiv/v2/:xiv1/iscsi_portsListspecificISCSIportproperties(wherep1istheportname)GET/xiv/v2/:xiv1/iscsi_ports/:p1IBMHyper‐ScaleManager4.
4RESTAPIspecificationsIBM84.
7HOSTPORTSHostportsareportsthatbelongtohosts,nottosystems.
Hostportqueryrequests:Listalloftheportsofaspecifichost(whereh1isthehostname)GET/xiv/v2/:xiv1/host_portshost=h1Listthehosttowhichthespecificportisassigned(wherep1istheportname)GET/xiv/v2/:xiv1/host_portsport=p1ListspecificFCportonahost(whereh1isthehostnameandp1istheportname)GET/xiv/v2/:xiv1/host_ports/:fc:h1:p1ListspecificISCSIportonahost(whereh1isthehostnameandp1istheportname)GET/xiv/v2/:xiv1/host_ports/:iscsi:h1:p14.
8VOLUMEMAPPINGSHost/ClusterandVolumemappingqueryrequests:Listallofthemappingsofthehost(whereh1isthehostname)GET/xiv/v2/:xiv1/vol_mapshost=h1Listallofthemappingsofthecluster(wherec1isthehostname)GET/xiv/v2/:xiv1/vol_mapscluster=c1Listallofthemappingsofthevolume(wherevol1isthevolumename)GET/xiv/v2/:xiv1/vol_mapsvolume=vol1Listspecifichostmappingproperties(whereh1isthehostnameandvol1isthevolumename)GET/xiv/v2/:xiv1/vol_maps/:host:h1:vol1Listspecificclustermappingproperties(wherec1istheclusternameandvol1isthevolumename)GET/xiv/v2/:xiv1/vol_maps/:cluster:c1:vol14.
9POOLSPoolqueryrequests:IBMHyper‐ScaleManager4.
4RESTAPIspecificationsIBM9Listallofthepoolsfromallofthesystemsonwhichtheuserisauthorized:GET/xiv/v2/poolsListallofthepoolsfromaspecificmachine:GET/xiv/v2/:xiv1/poolsListspecificpoolproperties(wherep1isthevolumename):GET/xiv/v2/:xiv1/pools/:p14.
10VOLUMESNAPSHOTSVolumeSnapshotqueryrequests:Listallofthesnapshotsfromallofthesystemsonwhichtheuserisauthorized:GET/xiv/v2/snapshotsListallofthesnapshotsfromaspecificmachine:GET/xiv/v2/:xiv1/snapshotsListallofthesnapshotsofthespecifiedvolume(wherev1isthevolumename):GET/xiv/v2/:xiv1/snapshotsvolume=vol1Listspecificsnapshotproperties(wheresn1isthesnapshotname):GET/xiv/v2/:xiv1/snapshots/:sn14.
11SNAPGROUPSSnapgroupqueryrequests:Listallofthesnapgroupsfromallofthesystemsonwhichtheuserisauthorized:GET/xiv/v2/snap_groupsListallofthesnapgroupsfromaspecificmachine:GET/xiv/v2/:xiv1/snap_groupsListallofthesnapgroupsofthespecifiedconsistencygroup(wherecg1isthenameofconsistencygroup):GET/xiv/v2/:xiv1/snap_groupscg=cg1IBMHyper‐ScaleManager4.
4RESTAPIspecificationsIBM10Listspecificsnapgroupsproperties(wheresg1isthesnapgroupname):GET/xiv/v2/:xiv1/snap_groups/:sg14.
12CONSISTENCYGROUPSConsistencygroupqueryrequests:Listalloftheconsistencygroupsfromallofthesystemsonwhichtheuserisauthorized:GET/xiv/v2/cgsListalloftheconsistencygroupsfromaspecificmachine:GET/xiv/v2/:xiv1/cgsListspecificconsistencygroupproperties(wherecg1istheconsistencygroupname)GET/xiv/v2/:xiv1/cgs/:cg14.
13MIRRORSMirrorqueryrequests:Listallofthemirrorsfromallofthesystemsonwhichtheuserisauthorized:GET/xiv/v2/mirrorsListallofthemirrorsfromaspecificmachine:GET/xiv/v2/:xiv1/mirrorsListthemirrorpropertiesofaspecificvolumemirror(wherevol1isthesourcevolumename)GET/xiv/v2/:xiv1/mirrors/:volume:vol1ListthemirrorpropertiesofaspecificCGmirror(wherecg1isthesourceCGname)GET/xiv/v2/:xiv1/mirrors/:cg:cg14.
14THREE‐WAY‐MIRRORSThree‐way‐mirrorqueryrequests:Listallofthethree‐way‐mirrorsfromallofthesystemsonwhichtheuserisauthorized:GET/xiv/v2/3_way_mirrorsIBMHyper‐ScaleManager4.
4RESTAPIspecificationsIBM11Listallofthe3‐way‐mirrorsfromaspecificmachine:GET/xiv/v2/:xiv1/3_way_mirrorsComment:thisquerylistsonlythosethree‐way‐mirrorsthatincludethemirrorsassociatedwithagivenmachine.

Listthepropertiesofaspecificthree‐way‐mirror(wheremirror1isthenameofthethree‐way‐mirror)GET/xiv/v2/3_way_mirrors/:mirror1Listthepropertiesofaspecificthree‐way‐mirror(wheremirror1isthenameofthethree‐way‐mirror)onthegivensystemGET/xiv/v2/:xiv1/3_way_mirrors/:mirror1Comment:thisqueryreturnsthethree‐way‐mirrorpropertiesonlywhentherespectivethree‐way‐mirrorisassociatedwiththegivenmachine.
Generalcomments(forresponsedetailsseeChapter9.
1.
15):1.
Therequests,appearingabove,donotsupportpaging(limitandoffsetparameters).
2.
Theresponsecontainsonlythethree‐way‐mirrorstowhichtheuserhasaccesstoatleastoneofthe"containment"mirrors(despitethemirror'srole).
3.
Onlymirrorsassociatedwiththe"source"volumesarereturned.
Iftheusercanonlyaccessmirrorsassociatedwith"destination"volumes,thenanemptylistofmirrorsisreturned.
4.
15QUERYRESPONSEFORMATThequeryresponseisdefinedasanobjecthavingthefollowingfields:status–responsestatusoserver–applicationlevelstatusandstatusmessageofailed_systems–arrayofXIVmachineerrorsthatwereencounteredduringtherequest.
Thisfieldisusedduringmulti‐machinequeriesorupdatestoindicatethatsomeXIVmachineshadissues(disconnected,not–authorized,invalidstate,etc.
)duringthequeryandthereturneddatamaynotcontainallresources,ortherequiredoperationhadonlypartialsuccess.
response–thequeryresponseresultocounts–theresponsecountandtotalcountofobjectsdata_count–thenumberofobjectsinthisresponsedatatotal_count–thenumberoftotalobjectsodata–theresponsedataCanbeeither:Alistofobjectsforqueriesonobjectcollections(forexample:/xiv/volumes)Asingleobjectforqueriesonaspecificobject(forexample:/xiv/:xiv1/volumes/:vol1)Null,iftherewassomeerrorinqueryprocessingExampleofasuccessfulresponse:Request‐GET/xiv/v2/:xiv1/volumes/:vol1…Response‐HTTP/1.
1200OKIBMHyper‐ScaleManager4.
4RESTAPIspecificationsIBM12…{status":{"server":{"status":"0","message":"OK"}"failed_systems":[]"response":{counts":{"data_count":"1","total_count":"1"}data""volume":{name":"vol1"}Exampleofapartiallysuccessfulresponse:Request‐GET/xiv/v2/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"IBMHyper‐ScaleManager4.
4RESTAPIspecificationsIBM13}Exampleofaninvalidrequest:Request‐GET/xiv/v2/myvolumes…Response‐HTTP/1.
1400BadRequest…{"status""server":{"status":"6","message":"Invalidrequest–myvolumespathisundefined"}"failed_systems":[]response":{counts":{"data_count":"0","total_count":"0"}data"}4.
16QUERYPAGINGSUPPORTAqueryrequestcanreturnahugelistofresources.
Forexample,arequestforallvolumesfromallXIVmachinescancontaintensofthousandsofvolumeresources.
Aclientmayonlybeinterestedinrequestingasubset/pagefromthequery.
Tosupportthisrequirement,weintroducetwoparameters:offset–definestheindexofthefirstresourcethatshouldbereturnedinthequery(considerthatallresourcesarenumbered,startingfrom0).
Ifanoffsetparameterisomitted,offsetof0isassumed.
Iftheoffsetislargerthanthenumberofresources–aresponsewithnoresourcesisreturned.
limit–definesthemaximumcountofresourcesthatshouldbereturnedinthequery.
Theactualcountofresourcesinresponseislessthan,orequalto,therequestedlimit.
Ifthelimitparameterisomitted,theserverreturnsuptomax_limitamountofresources(defaultsto1000).
Ifthelimitparameterishigherthantheamountofresources,therequestwillfailwitha400BadRequesterror.
Bydefault,thelistofreturnedobjectsissortedbyname.
Note:Thefollowingqueriesdonotsupportpaging‐SystemsandEvents.
Examples:/xiv/v2/volumes–returnsallofthevolumesfromalloftheXIVsystems(uptomax_limit)/xiv/v2/volumeslimit=400–returnsthefirst400volumesfromalloftheXIVsystems/xiv/v2/volumesoffset=10&limit=40–returns40volumes,startingfromvolume11/xiv/v2/volumesoffset=101–returnsallvolumes(uptomax_limit),startingfromvolume101IBMHyper‐ScaleManager4.
4RESTAPIspecificationsIBM144.
17EVENTQUERYTheEventqueryfetcheseventsfromaspecificXIVsystem.
Eventqueriesaredifferentfromtherestofthequeriessinceeventsare,currently,notmanagedbytheManagementServer.
SinceeventsarenotmanagedbytheManagementServer,pagingisnotsupportedforthisquery.
Thefollowingqueryparameterscanbeusedtofiltertheevents:min_severity–definestheminimumeventseverityPossiblevalues:Informational,Minor,Major,Warning,orCritical.
Ifomitted,minimumseverityisInformational.
after–returnsonlyeventsafterspecifiedtimestampbefore–returnsonlyeventsbeforespecifiedtimestampThesyntaxforthebeforeandafterfieldsisasfollows:Y‐M‐D[.
[h[:m[:s]]]],wheretherangesareasfollows:Y‐year(fourdigits)M‐month(01‐12)D‐day(01‐31)h‐hour(00‐23,with0asdefault)m‐minute(0‐‐59,with0asdefault)s‐second(00‐59,with0asdefault)Iffilteringparametersareomitted,thelast300eventsarereturned.
Example:GET/xiv/v2/:xiv1/eventsmin_severity=Warning&after=2013‐03‐07ResponseHTTP/1.
1200OK…{status":{"server":{"status":"0","message":"OK"}"failed_systems":[]"response":{counts":{"data_count":"300","total_count":"300"}data"}Note:Sinceeventsarenotmanagedbytheserverandpagingisnotsupported,thedatacountreturnedinresponseisalwaysequaltothetotalcount.
IBMHyper‐ScaleManager4.
4RESTAPIspecificationsIBM155UPDATEREQUESTSUpdaterequestsincludecreation,deletionormodifyingmanagedresources.
SincetheManagementServeronlyreflectsthestateofobjectsmanagedbyXIVmachines,allsuchrequestsshouldbepassedbytheManagementServertotheXIVmachinestohandle,usingXCLIcommandsinternally.
Hereanewgenericprotocolformatisintroduced,decoupledfromtheXCLIsyntax.
Sinceupdaterequestsrequiresomedatatobeprovidedbyclients(forexample,anewvolumesizeinthevolumeresizeoperation),howthisdataistransferredmustbedefined.
OnealternativeistoprovidethisdataasHTTPURLparameters;however,thismeansthattheprotocolisstrictlycoupledwiththetransportprotocol(HTTPinthiscase)andcannotbereusedeasilywithothertransportprotocolsthatdonotsupporttheURLparametersfeature.

TheonlyotheroptionistodelivertherequireddatainsideanHTTPbodyinJSONformat.
Definetheupdaterequestobjectwiththefollowinggenericfields:Action–therequiredactionPossiblevalues:create,delete.
Additionalactionsarepossible,basedontheresourcetype.
Params–containstheparametersrequiredfortheactionUpdatesaredoneusingtheHTTPPOSTrequestonaURLrepresentingacollectionofresources(forexample,POSTon/xiv/v2/:xiv1/volumes),whilethebodycontainstheexactactiontoperform(create/delete/update).
Eachsuchrequestcancarryalistofupdaterequeststosupportbulkoperations.
Additionally,thefollowingshortcutsareallowed:HTTPDELETErequestonafullURL(forexample,/xiv/v2/:xiv1/volumes/:vol1)withnobody,inordertodeleteit.
HTTPPOSTrequestonafullURLinordertoupdate/deleteit.
Thebodycontainsasinglerequestobjectwithalloftherequiredparameters,exceptname(sinceitappearsinURL).
Note:Thisreleasedoesnotsupportmultiplerequestsinthebody.
Onlyasingleupdaterequestinthebodyissupported.
5.
1VOLUMESBelowarepossibleupdateoperationsonvolumes.
Volumecreationisdoneusingthefollowingupdaterequest:action=createParamsoname–thevolumenameopool–thepoolnamewherevolumeshouldbecreatedosize–thevolumesizeosize_units–thesizeunitsPossiblevalues:GB,BLOCKSExample:POST/xiv/v2/:xiv1/volumes{"request":[IBMHyper‐ScaleManager4.
4RESTAPIspecificationsIBM16"action":"create","params":{name":"vol1",pool":"pool1",size":"17",size_units":"GB"}]}Volumeresize(eitherextendorshrink)isdoneusingthefollowingupdaterequest:action=resizeParamsoname–thevolumenameosize–newvolumesizeosize_units–thesizeunitsPossiblevalues:GB,BLOCKSExample:POST/xiv/v2/:xiv1/volumes{"request":["action":"resize","params":{name":"vol1",size":"170"size_units":"GB"}]}Alternatively,avolumecanberesizedwiththefollowingrequest:POST/xiv/v2/:xiv1/volumes/:vol1{"request":{"action":"resize","params":{size":"170"size_units":"GB"IBMHyper‐ScaleManager4.
4RESTAPIspecificationsIBM17}Volumelockisdoneusingthefollowingupdaterequest:action=lockParamsoname–thevolumenameExample:POST/xiv/v2/:xiv1/volumes{"request":["action":"lock","params":{name":"vol1"}]}Alternatively,avolumecanbelockedwiththefollowingrequest:POST/xiv/v2/:xiv1/volumes/:vol1{"request":{"action":"lock"}Volumeunlockisdoneusingthefollowingupdaterequest:action=unlockParamsoname–thevolumenameExample:POST/xiv/v2/:xiv1/volumes{"request":["action":"unlock","params":{name":"vol1"IBMHyper‐ScaleManager4.
4RESTAPIspecificationsIBM18}]}Alternatively,avolumecanbeunlockedwiththefollowingrequest:POST/xiv/v2/:xiv1/volumes/:vol1{"request":{"action":"unlock"}Volumerenameisdoneusingthefollowingupdaterequest:action=renameParamsoname–thevolumenameonew_name–thenewnameofthevolumeExample:POST/xiv/v2/:xiv1/volumes{"request":["action":"rename","params":{name":"vol1"new_name":"vol2"}]}Alternatively,avolumecanberenamedwiththefollowingrequest:POST/xiv/v2/:xiv1/volumes/:vol1{"request":{"action":"rename""params":{new_name":"vol2"IBMHyper‐ScaleManager4.
4RESTAPIspecificationsIBM19}Volumecopyisdoneusingthefollowingupdaterequest:action=copyParamsoname–thevolumenameotarget–thenameofthetargetvolumeExample:POST/xiv/v2/:xiv1/volumes{"request":["action":"copy","params":{name":"vol1"target":"vol2"}]}Alternatively,avolumecanbecopiedwiththefollowingrequest:POST/xiv/v2/:xiv1/volumes/:vol1{"request":{"action":"copy""params":{target":"vol2"}Movingofavolumetoapoolisdoneusingthefollowingupdaterequest:action=moveParamsoname–thevolumenameopool–thenameofthetargetpoolIBMHyper‐ScaleManager4.
4RESTAPIspecificationsIBM20Example:POST/xiv/v2/:xiv1/volumes{"request":["action":"move","params":{name":"vol1"pool":"pool1"}]}Alternatively,avolumecanbemovedwiththefollowingrequest:POST/xiv/v2/:xiv1/volumes/:vol1{"request":{"action":"move""params":{pool":"pool1"}Volumedeletionisdoneusingthefollowingupdaterequest:action=deleteParamsoname–thevolumenameExample:POST/xiv/v2/:xiv1/volumes{"request":["action":"delete","params":{name":"vol1"}]IBMHyper‐ScaleManager4.
4RESTAPIspecificationsIBM21}Alternatively,avolumecanbedeletedwiththeanyofthefollowingrequests(vol1–volumename):POST/xiv/v2/:xiv1/volumes/:vol1{"request":["action":"delete",}]}DELETE/xiv/v2/:xiv1/volumes/:vol15.
2HOSTSBelowarepossibleupdateoperationsonhosts.
Hostcreationisdoneusingthefollowingupdaterequest:action=createParamsoname–thehostnameocluster(optionalparameter)–theclusternameIfnotprovided,thestandalonehostisdefined.
otype(optionalparameter)–thehosttypePossiblevalues:standard,hpux,zvm.
Ifomitted,thedefaultvalueisstandard.
odomains‐thelistofdomains,optional,ifitisomittedthehostwillnotbeassociatedwithanydomain,ifitisdefinedas"*"thehostwillbeassociatedwithalldomainsNotes:1)Typeandclusterparametersareexclusive;thatis,onlyoneofthemcanbeprovidedintherequest.
Typeparametercanonlybespecifiedforstandalonehosts.
Iftheclusterparameterisprovided,thehosttypeisderivedfromthecluster.
2)Iftheparameterclusterisdefined,andthetargetsystemsupportsdomains,thenparameterdomainsshouldbedefined.
Example:POST/xiv/v2/:xiv1/hosts{"request":["action":"create",IBMHyper‐ScaleManager4.
4RESTAPIspecificationsIBM22params":{name":"host1",type":"hpux",domains":"domain1,domain2"}]}Hostrenameisdoneusingthefollowingupdaterequest:action=renameParamsoname–thehostnameonew_name–thenewnameofthehostExample:POST/xiv/v2/:xiv1/hosts{"request":["action":"rename","params":{name":"host1"new_name":"host2"}]}Alternatively,ahostcanberenamedwiththefollowingrequest:POST/xiv/v2/:xiv1/hosts/:host1{"request":{"action":"rename""params":{new_name":"host2"}Hostdeletionisdoneusingthefollowingupdaterequest:action=deleteIBMHyper‐ScaleManager4.
4RESTAPIspecificationsIBM23Paramsoname–thehostnameExample:POST/xiv/v2/:xiv1/hosts{"request":["action":"delete","params":{name":"host1"}]}Alternatively,ahostcanbedeletedwithanyofthefollowingrequests(h1–hostname):POST/xiv/v2/:xiv1/hosts/:h1{"request":["action":"delete",}]}DELETE/xiv/v2/:xiv1/hosts/:h15.
3CLUSTERSBelowarepossibleupdateoperationsonclusters.
Clustercreationisdoneusingthefollowingupdaterequest:action=createParamsoname–theclusternameotype–optionalparameter,theclustertype.
Possiblevalues:standard,hpux,zvm.
Ifomitted,defaultvalueisstandardodomains–thelistofdomains,optional,ifitisomittedtheclusterwillnotbeassociatedwithanydomain,ifitisdefinedas"*",theclusterwillbeassociatedwithalldomainsIBMHyper‐ScaleManager4.
4RESTAPIspecificationsIBM24Example:POST/xiv/v2/:xiv1/clusters{"request":["action":"create","params":{name":"c1"type":"zvm"domains":"domain1,domain2"}]}Additionofahosttoaclusterisdoneusingthefollowingupdaterequest:action=add_hostParamsoname–theclusternameohost–thenameofthehostomap–themappingindicator,thelegalvaluesforhostorcluster(seecommentbelowfordetailedexplanation)Comment:Themapparameterindicatesthetypeofmapping.
Usagerules:Ifthemapparameteriscluster,themappingofthehostandhosttypeischangedtobethecluster'smappingandtype.
Ifthemapparameterishost,themappingoftheclusteranditshosttypeischangedtobethehost'smappingandtype.
Example:POST/xiv/v2/:xiv1/clusters{"request":["action":"add_host","params":{name":"cluster1"host":"host1",map":"cluster"}]}IBMHyper‐ScaleManager4.
4RESTAPIspecificationsIBM25Alternatively,ahostcanbeaddedtoaclusterwiththefollowingrequest:POST/xiv/v2/:xiv1/clusters/:cluster1{"request":{"action":"add_host""params":{host":"host1"map":"cluster"}Removalofahostfromaclusterisdoneusingthefollowingupdaterequest:action=remove_hostParamsoname–theclusternameohost–thenameofthehostExample:POST/xiv/v2/:xiv1/clusters{"request":["action":"remove_host","params":{name":"cluster1"host":"host1"}]}Alternatively,ahostcanberemovedwiththefollowingrequest:POST/xiv/v2/:xiv1/clusters/:cluster1{"request":{"action":"remove_host""params":{host":"host1"IBMHyper‐ScaleManager4.
4RESTAPIspecificationsIBM26}Clusterrenameisdoneusingthefollowingupdaterequest:action=renameParamsoname–theclusternameonew_name–thenewnameoftheclusterExample:POST/xiv/v2/:xiv1/clusters{"request":["action":"rename","params":{name":"cluster1"new_name":"cluster2"}]}Alternatively,aclustercanberenamedwiththefollowingrequest:POST/xiv/v2/:xiv1/volumes/:cluster1{"request":{"action":"rename""params":{new_name":"cluster2"}Clusterdeletionisdoneusingthefollowingupdaterequest:action=deleteParamsoname–theclusternameExample:IBMHyper‐ScaleManager4.
4RESTAPIspecificationsIBM27POST/xiv/v2/:xiv1/clusters{"request":["action":"delete","params":{name":"c1"}]}Alternatively,aclustercanbedeletedwithanyofthefollowingrequests(c1–clustername):POST/xiv/v2/:xiv1/clusters/:c1{"request":["action":"delete",}]}DELETE/xiv/v2/:xiv1/clusters/:c15.
4HOSTPORTSHostportsrepresentportsthataredefinedonthehost/clientside.
Singlehostportnameiscreatedbyconcatenatingtheporttype(fcoriscsi),hostnameandportname,asfollows:Forfcports–fc:h1:p1,whereh1isthehostnameandp1istheportnameForiscsiport–iscsi:h1:p1,whereh1isthehostnameandp1istheportnameBelowarepossibleupdateoperationsonportmappings.
Addingaporttoahostisdoneusingthefollowingupdaterequest:action=createParamsoport–theportnameohost–thehostnameotype–theporttypePossiblevalues:iscsi,fcExample:IBMHyper‐ScaleManager4.
4RESTAPIspecificationsIBM28POST/xiv/v2/:xiv1/host_ports{"request":["action":"create","params":{port":"10000000C9926DCA",host":"h1",type":"fc"}]}Removingaportfromahostisdoneusingthefollowingupdaterequest:action=deleteParamsoport–theportnameohost–thehostnameotype–theporttypePossiblevalues:iscsi,fcExample:POST/xiv/v2/:xiv1/host_ports{"request":["action":"delete","params":{port":"10000000C9926DCA",host":"h1"type":"fc"}]}Alternatively,deletingfcportmappingscanbedoneusinganyofthefollowingrequests(whereh1isthehostnameandp1istheportname):POST/xiv/v2/:xiv1/host_ports/:fc:h1:p1{"request":[IBMHyper‐ScaleManager4.
4RESTAPIspecificationsIBM29"action":"delete",}]}DELETE/xiv/v2/:xiv1/host_ports/:fc:h1:p1Deletinganiscsiportmappingcanbedoneusinganyofthefollowingrequests(whereh1isthehostnameandp1istheportname):POST/xiv/v2/:xiv1/host_ports/:iscsi:h1:p1{"request":["action":"delete",}]}DELETE/xiv/v2/:xiv1/host_ports/:iscsi:h1:p15.
5VOLUMEMAPPINGSVolumemappingisanartificial/virtualobject–itrepresentsrelations/mappingsbetweenhosts(orclusters)andvolumes.
Asinglemappingnameiscreatedbyconcatenatingthetype(clusterorhost)withthecluster/hostnameandvolumename.
Forexample,host:h1:v1representshostvolumemapping,whilecluster:c1:v1representsclustervolumemapping.
Belowarepossibleupdateoperationsonvolumemappings.
Tocreateanewmappingbetweenahost/clusterandvolume,usethefollowingupdaterequest:action=createParamsovolume–thevolumenameohost_cluster_name–thehostnameforhostmappings,orclusternameforclustermappingsomap_type–"host"forhostmappingsor"cluster"forclustermappingsolun–lunidExampleofhostmappingcreation:POST/xiv/v2/:xiv1/vol_maps{"request":[action":"create",params":{volume":"vol1",host_cluster_name":"h1",IBMHyper‐ScaleManager4.
4RESTAPIspecificationsIBM30map_type":"host"lun":"3"}]}Exampleofaclustermappingcreation:POST/xiv/v2/:xiv1/vol_maps{"request":["action":"create",params":{volume":"vol1",host_cluster_name":"c1",map_type":"cluster"lun":"3"}]}Todeletevolumemapping,usethefollowingupdaterequest:action=deleteParamsovolume–thevolumenameohost_cluster_name–thehostnameforhostmappings,orclusternameforclustermappingsomap_type–"host"forhostmappingsor"cluster"forclustermappingsExampleofhostvolumemappingdeletion:POST/xiv/v2/:xiv1/vol_maps{"request":["action":"delete","params":{volume":"vol1",host_cluster_name":"h1",map_type":"host"}]}IBMHyper‐ScaleManager4.
4RESTAPIspecificationsIBM31Exampleofaclustervolumemappingdeletion:POST/xiv/v2/:xiv1/vol_maps{"request":["action":"delete","params":{volume":"vol1",host_cluster_name":"c1",map_type":"cluster"}]}Alternatively,todeleteahostvolumemapping,useanyofthefollowingrequests(whereh1isthehostnameandp1istheportname):POST/xiv/v2/:xiv1/vol_maps/:host:h1:v1{"request":["action":"delete",}]}DELETE/xiv/v2/:xiv1/vol_maps/:host:h1:v1Todeleteaclustervolumemapping,useanyofthefollowingrequests(wherec1istheclusternameandv1isthevolumename):POST/xiv/v2/:xiv1/vol_maps/:cluster:c1:v1{"request":["action":"delete",}]}DELETE/xiv/v2/:xiv1/vol_maps/:cluster:c1:v1IBMHyper‐ScaleManager4.
4RESTAPIspecificationsIBM325.
6POOLSBelowarepossibleupdateoperationsonpools.
Tocreateanewpool,usethefollowingupdaterequest:action=createParamsoname–thepoolnameohard_size–thepoolhardsize(inGB)osoft_size–thepoolsoftsize(inGB)osnap_size–thesizereservedforsnapshots(inGB)odomain–(optional)thenameofthedomaintoassociate.
Ifitisomitted,thenthepoolwillnotbeassociatedwithanydomain.
Example:POST/xiv/v2/:xiv1/pools{"request":["action":"create","params":{name":"p1",hard_size":"1700"soft_size":"1700"snap_size":"170"domain":"domain1"}]}Resizingthepoolsizeisdoneusingthefollowingupdaterequest:action=resize_pool_sizeParamsoname–thepoolnameohard_size–thepoolnewhardsize(inGB)osoft_size–thepoolnewsoftsize(inGB)Example:POST/xiv/v2/:xiv1/pools{"request":[IBMHyper‐ScaleManager4.
4RESTAPIspecificationsIBM33"action":"resize_pool_size","params":{name":"p1",hard_size":"1700"soft_size":"1700"}]}Alternatively,apoolcanberesizedusingthefollowingrequest:POST/xiv/v2/:xiv1/pools/:p1{"request":{"action":"resize_pool_size","params":{hard_size":"1700"soft_size":"1700"}}Toresizethepoolsnapshotsize,usethefollowingupdaterequest:action=resize_snapshot_sizeParamsoname–thepoolnameosnap_size–thenewsizereservedforsnapshots(inGB)Example:POST/xiv/v2/:xiv1/pools{"request":["action":"resize_snapshot_size","params":{name":"p1",snap_size":"170"}]}IBMHyper‐ScaleManager4.
4RESTAPIspecificationsIBM34Alternatively,toresizethesnapshotsize,usethefollowingrequest:POST/xiv/v2/:xiv1/pools/:p1{"request":{"action":"resize_snapshot_size","params":{snap_size":"170"}}Torenameapool,usethefollowingupdaterequest:action=renameParamsoname–thepoolnameonew_name–thenewnameofthepoolExample:POST/xiv/v2/:xiv1/pools{"request":["action":"rename","params":{name":"pool1"new_name":"pool2"}]}Alternatively,apoolcanberenamedusingthefollowingrequest:POST/xiv/v2/:xiv1/pools/:pool1{"request":{"action":"rename""params":{new_name":"pool2"}IBMHyper‐ScaleManager4.
4RESTAPIspecificationsIBM35Todeleteapool,usethefollowingupdaterequest:action=deleteParamsoname–thepoolnameExample:POST/xiv/v2/:xiv1/pools{"request":["action":"delete","params":{name":"p1"}]}Alternatively,apoolcanbedeletedwithanyofthefollowingrequests:(wherep1isthepoolname):POST/xiv/v2/:xiv1/pools/:p1{"request":["action":"delete",}]}DELETE/xiv/v2/:xiv1/pools/:p15.
7VOLUMESNAPSHOTSBelowarepossibleupdateoperationsonsnapshots.
Tocreateanewsnapshotofavolume,usethefollowingupdaterequest:action=createParametersIBMHyper‐ScaleManager4.
4RESTAPIspecificationsIBM36osource–thenameofthevolumeotarget–thesnapshotname,optionalodelete_priority–thepriority,optional,integer(0‐4)Example:POST/xiv/v2/:xiv1/snapshots{"request":["action":"create","params":{source":"vol1"target":"snapshot1"delete_priority":"2"}]}Thevolumesnapshotmaybeoverwrittenusingthefollowingupdaterequest:action=overwriteParametersosource–thenameofthevolumeotarget–thesnapshotnameExample:POST/xiv/v2/:xiv1/snapshots{"request":["action":"overwrite","params":{source":"vol1"target":"snapshot1"}]}Alternatively,thevolumesnapshotmaybeoverwrittenusingthefollowingupdaterequest(thesnapshotnameisusedasapartoftheURL):action=overwriteParametersIBMHyper‐ScaleManager4.
4RESTAPIspecificationsIBM37osource–thenameofthevolumeExample(snapshot1isthesnapshotname):POST/xiv/v2/:xiv1/snapshots/:snapshot1{"request":["action":"overwrite","params":{source":"vol1"}]}TolockaVolumesnapshot,usethefollowingupdaterequest:action=lockParamsoname–thesnapshotnameExample:POST/xiv/v2/:xiv1/snapshots{"request":["action":"lock","params":{name":"snapshot1"}]}Alternatively,asnapshotcanbelockedusingthefollowingrequest(snapshot1isthevolumesnapshotname):POST/xiv/v2/:xiv1/snapshots/:snapshot1{"request":{"action":"lock"}IBMHyper‐ScaleManager4.
4RESTAPIspecificationsIBM38TounlockaVolumesnapshot,usethefollowingupdaterequest:action=unlockParamsoname–thesnapshotnameExample:POST/xiv/v2/:xiv1/snapshots{"request":["action":"unlock","params":{name":"snapshot1"}]}Alternatively,avolumesnapshotcanbeunlockedusingthefollowingrequest(snapshot1isthevolumesnapshotname):POST/xiv/v2/:xiv1/snapshots/:snapshot1{"request":{"action":"unlock"}TodeleteaVolumesnapshot,usethefollowingupdaterequest:action=deleteParamsoname–thesnapshotnameExample:POST/xiv/v2/:xiv1/snapshots{"request":["action":"delete","params":{name":"snapshot1"}IBMHyper‐ScaleManager4.
4RESTAPIspecificationsIBM39]}Alternatively,asnapshotcanbealsodeletedusingoneofthefollowingrequests(wheresnapshot1isthesnapshotname):DELETE/xiv/v2/:xiv1/snapshots/:snapshot1POST/xiv/v2/:xiv1/snapshots/:snapshot1{"request":["action":"delete",}]}5.
8SNAPSHOTGROUPSTocreateanewsnapgroupofaconsistencygroup,usethefollowingupdaterequest:action=createParametersosource–thenameoftheconsistencygroupotarget–thenameofthenewsnapshotgroup,optionalodelete_priority–thepriority,optional,integer(0‐4)Example:POST/xiv/v2/:xiv1/snap_groups{"request":["action":"create","params":{source":"cg1"target":"sg1"delete_priority":"2"}]}Thesnapgroupmaybeoverwrittenusingthefollowingupdaterequest:IBMHyper‐ScaleManager4.
4RESTAPIspecificationsIBM40action=overwriteParametersosource–thenameoftheconsistencygroupotarget–thesnapshotnameExample:POST/xiv/v2/:xiv1/snap_groups{"request":["action":"overwrite","params":{source":"cg1"target":"sg1"}]}Alternatively,thesnapshotgroupmaybeoverwrittenusingthefollowingupdaterequest(thesnapgroupnameisusedasapartoftheURL):action=overwriteParametersosource–thenameoftheconsistencygroupExample(sg1isthesnapshotgroupname):POST/xiv/v2/:xiv1/snap_groups/:sg1{"request":["action":"overwrite","params":{source":"cg1"}]}TolockaSnapshotgroup,usethefollowingupdaterequest:action=lockParamsoname–thesnapshotgroupnameIBMHyper‐ScaleManager4.
4RESTAPIspecificationsIBM41Example:POST/xiv/v2/:xiv1/snap_groups{"request":["action":"lock","params":{name":"sg1"}]}Alternatively,asnapshotgroupcanbelockedusingthefollowingrequest(sg1isthesnapshotgroupname):POST/xiv/v2/:xiv1/snap_groups/:sg1{"request":{"action":"lock"}TounlocktheSnapshotgroup,usethefollowingupdaterequest:action=unlockParamsoname–thesnapshotgroupnameExample:POST/xiv/v2/:xiv1/snap_groups{"request":["action":"unlock","params":{name":"sg1"}]}Alternatively,asnapshotgroupcanbeunlockedusingthefollowingrequest(sg1isthesnapshotgroupname):POST/xiv/v2/:xiv1/snap_groups/:sg1{IBMHyper‐ScaleManager4.
4RESTAPIspecificationsIBM42"request":{"action":"unlock"}TodeleteaSnapshotgroup,usethefollowingupdaterequest:action=deleteParamsoname–thesnapshotgroupnameExample:POST/xiv/v2/:xiv1/snap_groups{"request":["action":"delete","params":{name":"sg1"}]}Alternatively,asnapshotcanbedeletedusingoneofthefollowingrequests(wheresg1isthesnapshotgroupname):DELETE/xiv/v2/:xiv1/snap_groups/:sg1POST/xiv/v2/:xiv1/snap_groups/:sg1{"request":["action":"delete",}]}5.
9CONSISTENCYGROUPSBelowarepossibleupdateoperationsonconsistencygroups.
IBMHyper‐ScaleManager4.
4RESTAPIspecificationsIBM43Tocreateanewconsistencygroup,usethefollowingupdaterequest:action=createParamsoname–thenameoftheconsistencygrouptocreateopool–thenameofthepoolExample:POST/xiv/v2/:xiv1/cgs{"request":["action":"create","params":{name":"cg1"pool":"pool1"}]}Toaddavolumetoaconsistencygroup,usethefollowingupdaterequest:action=add_volumeParametersoname–thenameoftheconsistencygrouptowhichthevolumeisaddedovolume–thenameofthevolumetoaddExample:POST/xiv/v2/:xiv1/cgs{"request":["action":"add_volume","params":{name":"cg1"volume":"vol1"}]}Alternatively,addingavolumetoaconsistencygroupmaybedoneusingthefollowingrequest:POST/xiv/v2/:xiv1/cgs/:cg1{"request":[IBMHyper‐ScaleManager4.
4RESTAPIspecificationsIBM44"action":"add_volume","params":{volume":"vol1"}]}Toremoveavolumefromaconsistencygroup,usethefollowingupdaterequest:action=remove_volumeParametersovolume–thenameofthevolumetoremoveExample:POST/xiv/v2/:xiv1/cgs{"request":["action":"remove_volume","params":{volume":"vol1"}]}Todeleteaconsistencygroup,usethefollowingupdaterequest:action=deleteParamsoname–thenameoftheconsistencygrouptodeleteExample:POST/xiv/v2/:xiv1/cgs{"request":["action":"delete","params":{name":"cg1"}]IBMHyper‐ScaleManager4.
4RESTAPIspecificationsIBM45}Alternatively,aconsistencygroupmaybedeletedusingthefollowingrequests(wherecg1isthenameoftheconsistencygroup):POST/xiv/v2/:xiv1/cgs/:cg1{"request":["action":"delete",}]}DELETE/xiv/v2/:xiv1/cgs/:cg15.
10MIRRORSBelowarepossibleupdateoperationsonmirrors.
Tocreateanewsynchronousmirrorofavolumeorconsistencygroup,usethefollowingupdaterequest:action=create_sync_mirrorParametersoname‐nameoffocalvolumeorcgtobemirrored(themaster)omirror_type–thetypeofthemirrortocreate;legalvaluesarecgorvolumeotarget–nameofthetarget(remote)systemoremote_name–nameoftheremotepeer(volumeorcg)ontheremotestoragesystemopart_of_xmirror–optional,true/false,ifomittedthevalueisfalse,indicateswhetherornotthecreatedmirrorwillbeapartofx‐mirrorComment:Thepart_of_xmirrorparameterisusedfor3‐way‐mirrorcreation.
Example:POST/xiv/v2/:xiv1/mirrors{"request":["action":"create_sync_mirror","params":{name":"mirror1",mirror_type":"volume"target":"system1",remote_name":"remote_vol",IBMHyper‐ScaleManager4.
4RESTAPIspecificationsIBM46part_of_xmirror":"true"}]}Tocreateanewasynchronousmirrorofavolumeorconsistencygroup,usethefollowingupdaterequest:action=create_async_mirrorParametersoname–nameoffocalvolumeorcgtobemirrored(themaster)otarget–nameofthetarget(remote)systemomirror_type–thetypeofthemirrortocreate,legalvaluesare:cg,volumeoremote_name–nameoftheremotepeer(volumeorcg)ontheremotestoragesystemoschedule_type–theschedulingtype,legalvaluesare:internal,externalorpo–mirrorrecoverypointobjective,formathh:mm:ss(wherehh–hours,mm‐minutes,ss–seconds),thelegalvaluesarefrom30secto24hoursoactivation_type–theactivationtype,legalvaluesare:offline,onlineopart_of_xmirror–optional,true/false,ifomittedthevalueisfalse,indicateswhetherornotthecreatedmirrorwillbeapartofx‐mirrorComment:Thepart_of_xmirrorparameterisusedfor3‐way‐mirrorcreation.
Example:POST/xiv/v2/:xiv1/mirrors{"request":["action":"create_async_mirror","params":{name":"mirror1",mirror_type":"volume"target":"system1",remote_name":"remote_vol",schedule_type":"internal",rpo":"23:00:01",activation_type":"online"}]}Toactivateavolumeorconsistencygroupmirror,usethefollowingupdaterequest:action=activate_mirrorParametersoname–thenameofthemastervolumeorcgtoactivatemirroringomirror_type–thetypeofthemirrortoactivate;legalvaluesare:cg,volumeIBMHyper‐ScaleManager4.
4RESTAPIspecificationsIBM47otarget–nameoftheremotesystem,optional,usedifsourcehasmorethanonedestinationExample:POST/xiv/v2/:xiv1/mirrors{"request":["action":"activate_mirror","params":{name":"vol1",mirror_type":"volume"}]}Alternatively,theactivationmaybedoneusingthefollowingrequests(wherevol1isthenameofthesourcevolumeandcg1isthenameofthesourceconsistencygroup):POST/xiv/v2/:xiv1/mirrors/:volume:vol1{"request":["action":"activate_mirror",}]}POST/xiv/v2/:xiv1/mirrors/:cg:cg1{"request":["action":"activate_mirror",}]}Todeactivateavolumeorconsistencygroupmirror,usethefollowingupdaterequest:action=deactivate_mirrorParametersoname–thenameofthemastervolumeonwhichtodeactivatemirroringomirror_type–thetypeofthemirrortodeactivate;legalvaluesare:cg,volumeIBMHyper‐ScaleManager4.
4RESTAPIspecificationsIBM48otarget–nameoftheremotesystem,optional,usedifsourcehasmorethanonedestinationExample:POST/xiv/v2/:xiv1/mirrors{"request":["action":"deactivate_mirror","params":{name":"vol1"mirror_type":"volume",target":"system1"}]}Alternatively,deactivationmaybedoneusingthefollowingrequests(wherevol1isthenameofthesourcevolumeandcg1isthenameofthesourceconsistencygroup):POST/xiv/v2/:xiv1/mirrors/:volume:vol1{"request":["action":"deactivate_mirror","params":{target":"system1"]}POST/xiv/v2/:xiv1/mirrors/:cg:cg1{"request":["action":"deactivate_mirror","params":{target":"system1"]IBMHyper‐ScaleManager4.
4RESTAPIspecificationsIBM49}Todeleteavolumeorconsistencygroupmirror,usethefollowingupdaterequest:action=deleteParams:oname–nameoffocalmastervolumeomirror_type–thetypeofthemirrortodelete;legalvaluesarecgorvolumeoforce_on_slave–optional,true/false,ifomittedthevaluesarefalseotarget–nameoftheremotesystem,optional,usedifsourcehasmorethanonedestinationExample:POST/xiv/v2/:xiv1/mirrors{"request":["action":"delete","params":{name":"vol1",mirror_type":"volume"force_on_slave":"true"}]}Alternatively,thedeletionmaybedoneusingthefollowingrequests(wherevol1isthenameofthesourcevolumeandcg1isthenameofthesourceconsistencygroup):POST/xiv/v2/:xiv1/mirrors/:volume:vol1{"request":["action":"delete","params":{force_on_slave":"true"}]}POST/xiv/v2/:xiv1/mirrors/:cg:cg1{"request":[IBMHyper‐ScaleManager4.
4RESTAPIspecificationsIBM50"action":"delete","params":{target":"system1"}]}Inaddition,thevolumemirrormaybedeletedusingthefollowingrequests(wherevol1isthenameofthesourcevolume):DELETE/xiv/v2/:/mirrors/:volume:vol1Theconsistencygroupmirroringmaybedeletedusingthefollowingrequests(wherecg1isthenameofthesourceconsistencygroup):DELETE/xiv/v2/:/mirrors/:cg:cg1Bothoftheabovedeleterequestsassumethattheforce_on_slaveparameterisfalse.
Comment:Thetworequestslistedabovewillonlyworkwithsourcesthathaveonlyoneassociatedmirror.
5.
11THREE‐WAY‐MIRRORSBelowarepossibleupdateoperationsonthree‐way‐mirrors.
Tocreateanewthree‐way‐mirrorofavolume,usethefollowingupdaterequest:action=createParamsomirror_name–thenameofthethree‐way‐mirrortocreateosource–thenameofthevolumethatwillbeamirroringsourceosecondary_source_target–thenameofthesecondsourcetargetodestination_target–thenameofdestinationtargetocreate_standby‐optional,true/false,defaultisfalse,indicateswhetherornottocreateastand‐bymirrorPreconditions:Twomirrors‐onesynchronousandoneasynchronous–mustexist,andbeassociatedwiththesamesourcevolume.
Tocreateamirrorassociatedwithavolumethatisalreadyassociatedwithanothermirror,thepart_of_xmirrorparametershouldbesettotrue.
Example:POST/xiv/v2/:xiv1/3_way_mirrors{"request":[IBMHyper‐ScaleManager4.
4RESTAPIspecificationsIBM51"action":"create","params":{mirror_name":"my_mirror",source":"my_volume",secondary_source_target":"xiv2",destination_target":"xiv3",create_standby":"true"}]}Toactivateathree‐way‐mirror,usethefollowingupdaterequest:action=activateParametersomirror_name–thenameofthree‐way‐mirrorExample:POST/xiv/v2/:xiv1/3_way_mirrors{"request":["action":"activate","params":{mirror_name":"mirror1"}]}Alternatively,theactivationmaybedoneusingthefollowingrequest(wheremirroristhenameofthethree‐way‐mirror).
POST/xiv/v2/:xiv1/3_way_mirrors/:mirror{"request":["action":"activate"}]}Todeactivateathree‐way‐mirror,usethefollowingupdaterequest:IBMHyper‐ScaleManager4.
4RESTAPIspecificationsIBM52action=deactivateParametersomirror_name–thenameofthree‐way‐mirrorExample:POST/xiv/v2/:xiv1/3_way_mirrors{"request":["action":"deactivate","params":{mirror_name":"mirror1"}]}Alternatively,thedeactivationmaybedoneusingthefollowingrequest(wheremirroristhenameofthethree‐way‐mirror)POST/xiv/v2/:xiv1/3_way_mirrors/:mirror{"request":["action":"deactivate"}]}Todeleteathree‐way‐mirror,usethefollowingupdaterequest:action=deleteParametersomirror_name–thenameofthree‐way‐mirrorComment:Actuallydeletecommanddisbandsthethree‐way‐mirrorExample:POST/xiv/v2/:xiv1/3_way_mirrors{"request":["action":"delete","params":{mirror_name":"mirror1"IBMHyper‐ScaleManager4.
4RESTAPIspecificationsIBM53}]}Alternatively,deletingathree‐way‐mirrormaybeperformedusingthefollowingrequest:(wheremirroristhenameofthethree‐way‐mirror):POST/xiv/v2/:xiv1/3_way_mirrors/:mirror{"request":["action":"delete"}]}Thethree‐way‐mirrormayalsobedeletedusingthefollowingrequest:(wheremirroristhenameofthethree‐way‐mirror):DELETE/xiv/v2/:xiv1/3_way_mirrors/:mirrorToforcedelete(deletionofathree‐way‐mirrormemberonasinglesystem),usethefollowingrequest:action=force_deleteParametersomirror_name–thenameofthethree‐way‐mirrorExample:POST/xiv/v2/:xiv1/3_way_mirrors{"request":["action":"force_delete","params":{mirror_name":"mirror1"}]}Alternatively,theforcedeletionofathree‐way‐mirrormaybeperformedusingthefollowingrequest:(wheremirroristhenameofthethree‐way‐mirror):POST/xiv/v2/:xiv1/3_way_mirrors/:mirror{"request":[IBMHyper‐ScaleManager4.
4RESTAPIspecificationsIBM54"action":"force_delete"}]}5.
12X‐CONSISTENCYGROUPBelowarepossibleupdateoperationsonanX‐consistencygroup.
TocreateasnapshotofanX‐consistencygroup,usethefollowingupdaterequest:action=create_snapshotParams:oxcg_name–thenameoftheX‐consistencygrouposnapshot_name–thenameofthesnapshotgrouptobecreatedodelete_priority–(optional)thedeletionpriorityinteger(0‐4)Example:POST/xiv/v2/xcgs{"request":["action":"create_snapshot","params":{xcg_name":"xcg1",snapshot_name":"snapshot1",delete_priority":"2"}]}Alternatively,thesnapshotmaybecreatedusingthefollowingrequest(wherexcg1isthenameoftheX‐consistencygroup):Example:POST/xiv/v2/xcgs/:xcg1{"request":["action":"create_snapshot","params":{snapshot_name":"snapshot1",delete_priority":"2"IBMHyper‐ScaleManager4.
4RESTAPIspecificationsIBM55}]}6UPDATERESPONSEFORMATTheupdateresponseisdefinedasanobjectthathasastatusfieldonly,asdefinedintheQueryresponseformat.

Exampleofasuccessfulresponsetoanupdaterequest:Request–DELETE/xiv/v2/:xiv1/volumes/:vol1…Response‐HTTP/1.
1200OK…{status":{"server":{"status":"0","message":"OK"}"failed_systems":[]}Exampleofafailedrequest:Request–DELETE/xiv/v2/:xiv1/volumes/:vol1…Response‐HTTP/1.
1500InternalServerError…{"status":{"server":{"status":"5","message":"Updaterequestfailedwithreason:Volume'vol1'doesnotexist"}"failed_systems":[]}7ERRORHANDLINGEachrequesttotheRESTAPIreceivesaresponsewithtwostatuscodes(anddescription):IBMHyper‐ScaleManager4.
4RESTAPIspecificationsIBM56HTTP/Transportstatuscode–aquickindicationwhetherornottherequestsucceeded.
Someautomationscriptsmaynotbeinterestedinparsingthefullresponseincaseoferror,soitisconvenienttohaveaquickindicationatHTTPlevel.
Serverstatuscode–providesmoredetailedapplicationlevelstatuscodetoallowtroubleshootingincaseoferrors.
BelowarealloftheenumeratedHTTPandServerstatuscodesretunedbytheRESTAPI:HTTPStatuscodeHTTPMessageDescription200OKTherequestsucceeded.
Theresponsecontainseitheralistofresources(inresponsetoaquery),orisempty.
400BadRequestTherequestcontainsinvalidscopekeywords,orinvalidURLparameters.
ExamplesofinvalidURLparametersare:non‐numericvalues,redundantparameters,etc.
401UnauthorizedTheusercredentialsprovidedarenotvalid.
404NotFoundTherequestaddressesnon‐existingresource(s).
Serverstatuscodecontainsmoredetailsaboutwhatresourcewasnotfound.
500InternalServerErrorTherequestisvalid,butsomeapplicationlevelerroroccurred.
Seeserverstatusformoreinformation.
Table1‐HTTPstatuscodesHTTPStatusServerstatuscodeServerMessageDescription2000OKTherequestsucceeded.
Theresponsecontainseitheralistofresources(inresponsetoaquery),orisempty.
5001RobotauthenticationfailedTheservercannotconnecttoXIVmachine(s)withrobotusercredentials.
Mostlikely,therobotuserpasswordisnotsetontheserver.
4012UnauthorizedInvalidusercredentialsweresuppliedforaqueryorupdateoperation.
5003NosystemsconnectedAllXIVmachinesthatareaddressedinIBMHyper‐ScaleManager4.
4RESTAPIspecificationsIBM57therequestaredisconnected.
4044ResourcenamedXoftypeYnotfoundThequeryrequestaddressednon‐existingresource.
Theservermessagecontainsthemissingresourcenameandtype.
Thisisusefultotroubleshootcomplexrequests(forexample,mappingofthesystem'shost).
5005Requestfailed.
Therequestexecutionfailed.
Thefailed_systemspartcontainsthereason.
4006InvalidRequest.
Therequestisinvalid.
Themessagecontainstheexactreason.
5008NomanagedsystemsconfiguredNoXIVsystemsaremanagedbytheserver.
5009ServergeneralerrorSomegeneralerroroccurredduringprocessing.
Table2‐ServerstatuscodesAdditionally,whenperformingmulti‐systemqueries,someXIVmachinesmaybeinanerrorstate(forexample,disconnected,notauthenticated,etc.
).
Thisindicatestotheuserthatthequeryresponsedoesnotcontainresourcesfromthesemachines.
Forthispurposethereisthefailed_systemsfieldintheresponse.
Thefieldisalistthatcontainssystemsthatareinerror,accordingtothefollowingtable:FailedsystemcodeMessageDescription1RobotuserauthenticationfailedRobotusercredentialsarenotdefinedonthesystem,ortherobotpasswordisnotsetontheserver2UnauthorizedInvalidusercredentialsweresupplied3SystemisdisconnectedTheservercannotconnecttothespecificXIVsystem4ThesystemisnotmanagedbytheserverThespecificXIVsystemisnotmanagedbytheserver5Requestfailed.
Therequestfailed.
ReasoncontainsXCLIcommandresponse+errorcode.
6SystemissuspendedThespecificXIVsystemissuspendedIBMHyper‐ScaleManager4.
4RESTAPIspecificationsIBM58Table3‐FailedsystemsstatuscodesNote:Ifthereisamulti‐systemrequestwhenallofthesystemsareinaccessible,thefollowingrulesapply:Ifallsystemsareinan"Unauthorized"state‐theresponseisHTTP401,serverstatus2.
Ifallsystemsareina"Robotuserauthenticationfailed"state‐theresponseisHTTP500,serverstatus1.