HP 3PAR StoreServ 7450 2-node HP 3PAR Web Service API 1.2 Developer's
HP 3PAR StoreServ 7450 2-node Manual
View all HP 3PAR StoreServ 7450 2-node manuals
Add to My Manuals
Save this manual to your list of manuals |
HP 3PAR StoreServ 7450 2-node manual content summary:
- HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 1
HP 3PAR Web Services API 1.2 Developer's Guide Abstract This guide provides instructions and reference information for the HP 3PAR Web Services API. HP Part Number: QR482-96192 Published: June 2013 Edition: First - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 2
to change without notice. The only warranties for HP products and services are set forth in the express warranty statements accompanying such products and services. Nothing herein should be construed as constituting an additional warranty. HP shall not be liable for technical or editorial errors - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 3
...10 Perl SDK...10 2 Accessing the WSAPI 11 Overview...11 Protocol and Message Format 12 Client HTTP Headers...12 Server HTTP Headers...13 Supported HTTP Methods 14 General URI Format...14 System Access...14 Creating Credentials...14 About Multiple Session Keys 14 About Session Key Security 15 - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 4
38 Volume DetailedState Enumeration Types 39 Volume policies Configuration Object 40 Volume Space Objects...40 Creating a Storage Volume...41 Creating Base Volumes...41 Creating Snapshot Volumes 42 Volume Creation Success...43 Volume Creation Errors...43 Modifying a Virtual Volume...44 Volume - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 5
a CPG or LDLayout Object 84 CPG Space Query Members 84 LDLayout Object Space Query Members 84 Space Query Success...84 Space Query Errors...85 10 Support and Other Resources 86 Contacting HP...86 HP 3PAR documentation...86 Typographic conventions...89 HP 3PAR branding information 89 Contents 5 - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 6
11 Documentation feedback 90 Index...91 6 Contents - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 7
Tables 1 Client HTTP Headers Supported by the HP 3PAR WSAPI for Requests 12 2 Server HTTP Headers in the 31 Message Body JSON Objects for Base-volume Creation 41 32 Message Body parameters JSON Object Members for Snapshot-volume Creation 43 33 Base-volume and Snapshot-volume Creation Error - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 8
52 Host portPos Configuration JSON Objects 61 53 Host agent JSON Objects 61 54 Host Query Errors...62 55 Port portMode Enumeration 63 56 Port portLinkState Enumeration 63 57 Port portConnType Enumeration 64 58 Port portProtocol Enumeration 65 59 Port portFailOverState Enumeration 65 60 - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 9
the WSAPI commands and a summary of the items included in the HP 3PAR Web Services API Server SDK. Starting and Configuring the Server The API server is part of the HP 3PAR OS 3.1.2 and later, and will run on the HP 3PAR StoreServ Storage. The server must be started with the startwsapi command-line - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 10
. • Example programs to illustrate the creation and query of base entities. These examples rely on the accessor and base packages. Perl SDK The Perl SDK includes: • A module with methods for accessing the HP 3PAR storage system. • Modules with mappings of the error codes and enumerated properties - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 11
JSON. The message body will be ignored for GET and DELETE operations. The WSAPI enables programmatic management of HP 3PAR storage servers. The clients access Web services at specified HTTPS locations that control the following tasks: • Gaining system access through session keys • Getting version - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 12
, must be one of the values listed in the Values column. For example: Accept: application/json; charset=UTF-8 Table 1 Client HTTP Headers Supported by the HP 3PAR WSAPI for Requests Header Accept Description The response format the client can accept. Values Required One of the following: No - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 13
Table 1 Client HTTP Headers Supported by the HP 3PAR WSAPI for Requests (continued) Header Description Values Required Value Description HP3PAR-WSAPI The HP 3PAR Web Services API Server. no-cache Disables caching by mechanisms between the Web Services API server software and client - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 14
This section summarizes the HTTP methods currently supported by the HP 3PAR WSAPI. These include: GET The HTTP to the HTTP methods for a single session. Creating Credentials In order to use the Web Services, you must create a session key by providing a username and password. The username and - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 15
About Session Key Security Because session keys allow access to the storage server, client applications should not display session keys or otherwise make them visible to end users. Revealing a session key is similar to revealing a password in that an unauthorized person who obtains a session key can - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 16
Supported JSON a JSON object with information specific to the HP 3PAR WSAPI. The JSON object contains the members and cannot be relied upon. To avoid that problem, the WSAPI provides a reliable code for an be returned. For applications that change behavior based on errors, only the code member should - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 17
time limit. 8 505 HTTP Version The client request uses an Not Supported unsupported HTTP version. 9 501 NOT The resource does not IMPLEMENTED support the operation. 10 (Not used by the HP 3PAR OS.) URI_RES_NOT_FOUND PERM_DENIED NON_EXISTENT_HOST TOO_LARGE OTHER 11 404 Not Found The - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 18
API Error API Error Code HTTP Code Description SVC_UNAVAIL 31 503 Service The server has reached its Unavailable maximum number of connections. Accept header is not supported. 406 Not Acceptable The language specified in client's HTTP Accept-Language header is not supported. 404 Not Found - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 19
request body contains a sequence of characters that is invalid for the supported UTF encodings. INV_INPUT_NO_REQ 64 400 Bad Request A POST request is missing action member with an invalid value. SYS_SVC_NOT_READY 68 503 Service Services that the system Unavailable depends on in order to - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 20
Bad Request Not enough space is available for the operation. This varies based on the following circumstances: • In volume creation, when the CPG In CPG creation, when the storage system's hardware configuration does not support the requested LD layout. • In CPG creation, when the chunklets - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 21
Table 6 Operation-specific API code Member Status and Error Codes (continued) API Error API Error Code HTTP Code Description RETAINED 27 409 Conflict Volume retention time has not expired. HAS_CHILD 32 409 Conflict The virtual volume (VV) has a child VV. NO_SNAP_CPG 33 409 Conflict No - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 22
Table 6 Operation-specific API code Member Status and Error Codes (continued) API Error INV_INPUT_RETAIN_GT_EXPIRE INV_INPUT_VV_POLICY BAD_CPG_PATTERN MISSING_VLUN_EXPORT_INFO INV_INPUT_PORT_SPECIFICATION INV_INPUT_TIME EXISTENT_ID INV_INPUT_TOO_MANY_WWN_OR_iSCSI API Error Code 49 50 53 54 55 58 - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 23
on system volume. (Since WSAPI 1.2) INV_OPERATION_VV_VOLUME_NOT_DEFINED_ALL_NODES 86 409 Conflict Invalid operation. Volume is not defined on all nodes. (Since WSAPI 1.2) INV_OPERATION_VV_ONLINE_COPY_IN_PROGRESS 87 409 Conflict Invalid operation. Online copy is in progress. (Since WSAPI - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 24
supplementary information that helps explain the reason for the error code. NOTE: The text in the desc member is subject to change between releases. HP recommends avoiding parsing the desc member and using it only for display purposes. For example, the desc member for an error may change from No - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 25
The ref Member In the event of an error that may occur for several reasons, the ref member may specify the reason for the error. For example, if the client were to send an incorrect value for a JSON member, then the server may be able to identify which member had the incorrect value. NOTE: There are - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 26
that required members are missing. When writing a client in a language that provides services for serializing a class into a JSON object, it is convenient to only values to use to ignore a member. Null Members The WSAPI supports properties with a value of null. Clients written in languages that - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 27
. Restrictions on values or format are given names that appear in the Type column in Table 7 (page 27). These API types are referenced in this guide in descriptions of JSON input and output. Table 7 API Types Type 8601 Description JSON string with time in ISO 8601 format: YYYY-MM-DDThh:mm - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 28
Table 7 API Types (continued) Type Description An empty string enclosed in quotation marks ("") represents a name with no characters. An unset name is represented in JSON as null. print511 uint32 WWN JSON string of 511 or fewer characters. JSON number restricted to a 32-bit unsigned number. - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 29
Specifies the RAID type for the logical disk. Specifies the set size in the number of chunklets. Specifies that the layout must support the failure of one port pair, one cage, or one magazine. Specifies the chunklet location preference characteristics. Specifies patterns for candidate disks - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 30
based on Table 10 (page 30). Table 10 CPG HA Enumeration Symbol PORT CAGE MAG Value 1 2 3 Description Support failure of a port. Support failure of a drive cage. Support nodes. Nodes are identified by one or more integers. Multiple nodes are separated with a single comma (1,2,3). A range of nodes - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 31
Table 12 CPG diskPatterns JSON Object (continued) Member Value Ignored values Description magList string Null Specifies one or more drive magazines. Drive magazines are identified by one or more integers. Multiple drive magazines are separated with a single comma (1,2,3). A range of - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 32
CPG Space Usage Objects The SDUsage, SAUsage and UsrUsage objects, all of which use the same members, are sub-objects of the cpg object returned by queries. Those members are listed in Table 14 (page 32). Table 14 CPG SDUsage, SAUsage, and UsrUsage JSON Objects Member totalMiB rawTotalMiB usedMiB - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 33
Table 17 CPG DetailedState Enumeration Symbol SA_LIMIT_REACHED SD_LIMIT_REACHED SA_GROW_FAILED SD_GROW_FAILED SA_WARN_REACHED SD_WARN_REACHED Value 1 2 3 4 5 6 Description Admin space at limit. Copy space at limit. Admin space grow failed. Copy space grow failed. Admin space at warning level. - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 34
CPG Creation Errors If an error occurs, the system returns one of the error codes shown in Table 19 (page 34), or a general error code listed in "Generic WSAPI code Member Status and Error Codes" (page 17): Table 19 CPG Creation and Modification Error Codes API Error BAD_CPG_PATTERN - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 35
NOTE: Any user with Super, Service, or Edit role, or any role granted the cpg_set right, can perform this operation. Access to all domains is required for this operation. Table 20 - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 36
Table 21 CPG Removal Error Codes API Error HTTP Code NON_EXISTENT_CPG 404 Not Found IN_USE 409 Conflict Description CPG not found. The CPG cannot be removed because it is in use by a volume. Querying CPG Information You can query for information about all the CPGs on the storage system or - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 37
Table 22 CPG Query members JSON Objects (continued) Member JSON Type API Type Description degradedStates array of numbers array of DetailedState enum Detailed state of CPG. additionalStates array of numbers array of DetailedState enum Detailed state of CPG. CPG Query Success Upon success, - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 38
space that is associated with the userCPG property. Also includes old-style thin provisioned VV (created on a 2.2.4 release or earlier) where both the base VV and snapshot data are allocated from the snapshot space associated with userCPG. SNP PEER UNKNOWN 3 The VV is a snapshot (Type vcopy) and - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 39
Table 27 Volume state Enumeration Symbol NORMAL DEGRADED FAILED Value 1 2 3 Description The virtual volume (VV) is operating normally. VV is in degraded state. VV is operating abnormally. Volume DetailedState Enumeration Types Details of the volume's state are enumerated in Table 28 (page 39). - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 40
Volume policies Configuration Object The policies of a volume are specified by the policies JSON object, as detailed in Table 29 (page 40). Table 29 Volume policies JSON Objects Member staleSS Value Boolean Description true: Stale snapshots. If there is no space for a copy-on-write operation, the - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 41
role granted the vv_create right (for base volumes) or sv_create (for snapshot volumes), can create a volume. Creating Base Volumes To create a storage volume, use The definition of members can be found in the HP 3PAR Command Line Interface Reference or in the column help for the CLI command createvv - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 42
Table 31 Message Body JSON Objects for Base-volume Creation (continued) Member JSON Type API Type ssSpcAllocLimitPct number igint32 tpvv Boolean Boolean Ignored Values Negative values None Description warning. A warning alert is generated - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 43
error condition returns one of the errors in Table 33 (page 43). For generic API error codes, see Table 5 (page 17). Table 33 Base-volume and Snapshot-volume Creation Error Codes API Error INV_INPUT EXISTENT_VOL HTTP Code 400 Bad Request 409 Conflict Description Invalid parameter or JSON object - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 44
Table 33 Base-volume and Snapshot-volume Creation Error Codes (continued) API Error HTTP Code Description INV_INPUT_WARN_GT_LIMIT 400 Bad Request Allocation warning level is higher than the limit. - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 45
Table 34 Message Body JSON Objects for Volume Modification Request (continued) Member JSON Type API Type Ignored Values Description (Since WSAPI 1.2) userCPG string name31 None User CPG name. (Since WSAPI 1.2) usrSpcAllocWarningPct number igint32 Zero and negative values User space - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 46
Table 34 Message Body JSON Objects for Volume Modification Request (continued) Member JSON Type API Type Ignored Values Description (Since WSAPI 1.2) rmUsrSpcAllocLimit Boolean None If true, remove User Space allocation limit. If False, and limit value is 0, then ignore. If False, and limit - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 47
Table 35 Volume Modification Request Error Codes (continued) API Error HTTP Code CPG_NOT_IN_SAME_DOMAIN 403 Forbidden INV_OPERATION_VV_PEER_VOLUME 403 Forbidden INT_SERV_ERR INV_OPERATION_VV_SYS_VOLUME 500 Internal Server Error 403 Forbidden INV_OPERATION_VV_INTERNAL_VOLUME 403 Forbidden - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 48
Removing a Storage Volume To remove a volume, use the HTTP DELETE method in the URI, with no message body: https://:8080/api/v1/volumes/ Storage Volume Removal Success A successful storage-volume removal returns the HTTP status code 200 OK. Storage Volume Removal - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 49
or virtual copy of another VV, this field indicates the VV that this VV is a copy of. The ID of the VV that is the base VV (at the root of the snapshot tree) for the VV. true: Read only false: Read and write allowed. state failedStates degradedStates additionalStates adminSpace snapshotSpace - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 50
Table 37 Message Body JSON Objects for Volume Query (continued) Member JSON Type API Type Description exceeds the indicated percentage of the virtual volume size. ssSpcAllocLimitPct number igint32 Sets a snapshot space allocation limit. The snapshot space of the virtual volume is prevented - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 51
Table 39 Single-volume Query Error Codes API Error HTTP Code NON_EXISTENT_VOL 404 Not Found INV_INPUT_ILLEGAL_CHAR 400 Bad request Description Volume does not exist. (Since WSAPI 1.2) Invalid character for volume name. (Since WSAPI 1.2) Querying Volume Information 51 - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 52
5 Working with Hosts This chapter describes how to manage hosts. The sections apply to creation, modification, removal, and query operations on hosts. Creating a Host Create a host using the HTTP POST method. Use the following URI: https://:8080/api/v1/hosts Table 40 (page 52) - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 53
/api/v1/hosts/ For example: URL: https://:8080/api/v1/hosts Post: {"name":"apitesthost","persona":5} Response: HTTP/1.1 201 Created with with the location header: /api/v1/hosts/apitesthost Host Creation Errors Table 41 (page 53) shows possible host creation errors - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 54
Modifying a Host Modify a host using the HTTP POST method. Use the following URI: https://:8080/api/v1/hosts/ NOTE: Any user with Super or Edit role, or any role granted the host_set right, can perform this operation. Access to all domains is required for this operation. - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 55
Table 42 Message Body JSON Objects for Host Modification Request (continued) Member chapSecret JSON Type string API Type string Ignored Values Null Description The chap secret for the host or the target (Since WSAPI 1.2) chapSecretHex Boolean None If True, then chapSecret is treated as Hex. - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 56
Table 45 Host hostPersona Enumeration (continued) Symbol Value ONTAP_LEGACY 7 VMWARE 8 OPENVMS 9 Description Persona with capability of SoftInq. Persona with capability of SubLun, ALUA. Persona with capability of UARepLun, Lun0SCC. Host Modification Success Upon successful modification of - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 57
Table 46 Host Modification Error Codes (continued) API Error HTTP Code INV_INPUT_ONE_REQUIRED 400 Bad Request INV_INPUT_BAD_ENUM_VALUE 400 Bad Request INV_INPUT_MISSING_REQUIRED 400 Bad Request INV_INPUT_EXCEEDS_LENGTH 400 Bad Request INV_INPUT_ILLEGAL_CHAR 400 Bad Request EXISTENT_HOST 409 - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 58
Table 46 Host Modification Error Codes (continued) API Error HTTP Code EXPORTED_VLUN 409 Conflict NON_EXISTENT_PATH LUN_HOSTPERSONA_CONFLICT 400 Bad Request 409 Conflict INV_INPUT_DUP_PATH 404 Bad Request Description Setting persona with active export; remove a host path on an active export - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 59
Table 48 Host Query JSON Objects (continued) Member JSON Type API Type FCPaths iSCSIPaths domain FCPaths iSCSIPaths string name31 descriptors Descriptors agent Agent initiatorChapName string Boolean Name223 True or False targetChapName string targetChapEnabled Boolean Name223 True - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 60
Table 49 Host descriptors JSON Objects (continued) Member JSON Type comment string Description (Since WSAPI 1.2) Any additional information for the host. (Since WSAPI 1.2) When a host object is queried, it may include an array of one or more FCPaths objects. See Table 50 (page 60). Table 50 - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 61
See Table 52 (page 61). Table 52 Host portPos Configuration JSON Objects Member node JSON Type number API Type igint32 (0 - 7) Description System node. slot number igint32 (0 - 5) PCI bus slot in the node. cardPort number igint32 (0 - 4) Port number on the FC card. agent is an optional - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 62
Table 53 Host agent JSON Objects (continued) Member JSON Type clusterName string API Type Name255 clusterSoftware clusterVersion clusterId hostId string string string string Name255 Name255 Name255 Name255 Description Name of the host cluster of which the host is a member. (Since WSAPI 1.2) - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 63
and configuration objects that are used by VLUN operations. The Inform API server configuration object portPos is defined in Table 52 (page 61). The HP 3PAR OS API server returns the port mode enumeration, as shown in Table 55 (page 63). Table 55 Port portMode Enumeration Symbol SUSPENDED Value - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 64
(Since WSAPI 1.2) Link is idle for reset. (Since WSAPI 1.2) DHCP is in progress. (Since WSAPI 1.2) Link reset is pending. (Since WSAPI 1.2) The HP 3PAR OS API server returns port connection type enumeration, as shown in Table 57 (page 64). Table 57 Port portConnType Enumeration Symbol HOST Value - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 65
. (Since WSAPI 1.2) Fibre Channel over Ethernet (Since WSAPI 1.2) Internet Protocol (Remote Copy) (Since WSAPI 1.2) Serial-attached SCSI. (Since WSAPI 1.2) The HP 3PAR OS API server returns port failover state enumeration as shown in Table 59 (page 65). Table 59 Port portFailOverState Enumeration - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 66
WSAPI 1.2) mode number portMode Enum Port mode. (Since WSAPI 1.2) linkState number portLinkState Enum Port link state. (Since WSAPI 1.2) nodeWWN string WWN Node WWN that is unique across all ports. (Since WSAPI 1.2) portWWN string WWN Port WWN for FCoE and FC ports. Not included in - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 67
the JSON object for other ports. (Since WSAPI 1.2) For iSCSI port only; not included in the JSON object for other ports. (Since WSAPI 1.2) Ethernet node MAC address. PFC mask. All-ports Query Errors The INT_SERV_ERR might be returned upon querying all volumes. For details about this error code, see - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 68
slot cardPort JSON Type number number number API Type igint32 igint32 igint32 Description System node (0-7). PCI bus slot in the node (0-5). Port number on the FC card (0-4). VLUNtype Enumeration This component enumerates the type of VLUNs (VLUNType) assigned in the system, as defined in Table - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 69
range can be n+ (minimal n) or m-n (m to n). To support auto lun, the fields autoLun and maxAutoLun are now supported in the message body for VLUN creation. Table 68 Message Body JSON None* (optional) exported to. It includes node number, slot number, and card port number. Creating a VLUN 69 - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 70
Table 68 Message Body JSON Objects for VLUN Template Request (continued) Member noVcn JSON Type Boolean overrideLowerPriority Boolean autoLun Boolean API Type Description Ignored Values A VLUN change None* (optional) notification (VCN) not be issued after export (-novcn). Default: False - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 71
invalid port type. EXISTENT_LUN 409 Conflict LUN already exists. INV_INPUT_PORT_SPECIFICATION 400 Bad Request Incorrect portPos specification or the node or slot or cardPort in portPos object maybe out of range. INV_INPUT_PARAM_CONFLICT 400 Bad Request OverrideLowerPriority is being specified - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 72
, or Specifies the system port of the VLUN export. It to both host and port) includes the system node number, PCI bus slot number, and card port number on the FC card in the format: :: None Can be replaced with a Boolean value: • noVcn=True • noVcn=False *Must be - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 73
Table 71 VLUN Removal Error Codes API Error HTTP Code INV_INPUT 400 Bad Request NON_EXISTENT_HOST 404 Not Found NON_EXISTENT_VLUN 404 Not Found INV_INPUT_PORT_SPECIFICATION 400 Bad Request INV_INPUT_EXCEEDS_RANGE 400 Bad Request INV_INPUT_MISSING_REQUIRED 400 Bad Request - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 74
on port type. portPos object For more information, see "VLUN portPos JSON Objects" (page 68). System port of VLUN exported to. It includes node number, slot number, and cardPort number. VLUNtype enum For more information, see "VLUNType Enumeration" (page 68). VLUN type. WWN WWN of exported - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 75
{"total": 2, "members": [ { "lun": 1, "volumeName": "vol1.0", "hostname": "host", "remoteName": "10000000C978500E", "portPos": { "node": 0, "slot": 4, "cardPort": 1 }, "type": 4, "volumeWWN": "60002AC0000000000000020D0000017D", "multipathing": 1, "failedPathPol": 1, "failedPathInterval": 0, "active - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 76
are optional, but one or both of them must be specified. NOTE: The use of patterns or sets in querying volumes and hosts is not supported in WSAPI 1.2. In order to query a single instance of a VLUN object, the specific volume name and host name must be specified. Single-VLUN Query Success - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 77
(continued) Member JSON Type API Type Description (Since WSAPI 1.2) portPos object portPos object System port of VLUN exported to. It includes node number, slot number, and cardPort number. type number VLUNType enum VLUN type. (Since WSAPI 1.2) volumeWWN string WWN WWN of exported - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 78
Table 76 Single-VLUN Query Error Codes (continued) API Error HTTP Code NON_EXISTENT_VOL 404 Not found NON_EXISTENT_HOST 404 Not found INV_INPUT_PORT_SPECIFICATION 400 Bad Request INV_INPUT_ILLEGAL_CHAR 400 Bad Request INV_INPUT_EXCEEDS_RANGE 400 Bad Request Description Requested volume - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 79
IPv4 address. System IPv6 address. System model. System serial number. Storage system software version number. Total number of nodes in the system. Master node ID. Node IDs online. Node IDs in cluster Chunklet size. Total capacity (MiB) in the system. Allocated capacity (MiB) in the system. Free - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 80
minor number. A build number not meant to be interpreted by clients, but useful for identifying specific builds of versions for defect reports or support requests. Version Information Query Errors Upon an unsuccessful query for version information, the error code shown in Table 80 (page 80) might - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 81
9 Querying Available Space This chapter describes querying for information about overall available space on the system, and about querying available space based on CPG and LD layout. Querying Overall System Capacity Space information can be queried for the overall capacity, for a given CPG name, - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 82
Table 82 DeviceCapacity JSON Objects (continued) Member JSON Type API Type failedCapacityMiB failedCapacityMiB Number unavailableCapacityMiB Number uint64 uint64 Description (Since WSAPI 1.2) Failed capacity in MiB. (Since WSAPI 1.2) Unavailable Capacity. (Since WSAPI 1.2) AllocatedCapacity - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 83
Table 84 Volumes JSON Objects (continued) Member JSON Type CPGUserMiB number Value Range uint64 CPGUserUsedMiB number uint64 CPGUserUnusedMiB number uint64 CPGSnapshotMiB number CPGSnapshotUsedMiB number uint64 uint64 CPGSnapshotUnusedMiB number uint64 CPGAdminMiB CPGAdminUsedMiB - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 84
Type string API Type name31 Description The CPG name. (Since WSAPI 1.2) LDLayout Object Space Query Members The members required to query space information based on an LDLayout object are shown in Table 88 (page 85). Space Query Success Upon a successful query for available space, the HTTP code - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 85
Table 87 JSON Objects for cpg Space Query Response (continued) Member JSON Type Value Range Description (Since WSAPI 1.2) Upon querying for space information based on an LDLayout object, the system will return a single JSON object. Its members are described in Table 89 (page 85). Table 88 JSON - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 86
of support you are requesting: HP 3PAR storage system HP 3PAR StoreServ 7200, 7400, and 7450 Storage systems HP 3PAR StoreServ 10000 Storage systems HP 3PAR T-Class storage systems HP 3PAR F-Class storage systems Support request StoreServ 7000 Storage 3PAR or 3PAR Storage HP 3PAR documentation - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 87
, and detailed alert information HP 3PAR F-Class, T-Class, and StoreServ 10000 Storage Troubleshooting Guide Installing, configuring, and maintaining the HP 3PAR Policy HP 3PAR Policy Server Installation and Setup Guide Server HP 3PAR Policy Server Administration Guide HP 3PAR documentation 87 - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 88
3PAR StoreServ 7000 Storage Service Guide HP 3PAR StoreServ 7450 Storage Service Guide Troubleshooting 7200, 7400, and 7450 storage systems HP 3PAR StoreServ 7000 Storage Troubleshooting Guide HP 3PAR StoreServ 7450 Storage Troubleshooting Guide Maintaining the Service Processor HP 3PAR Service - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 89
followed as directed in order to achieve a functional and supported implementation based on testing at HP. HP 3PAR branding information • The server previously referred to as the "InServ" is now referred to as the "HP 3PAR StoreServ Storage system." • The operating system previously referred to as - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 90
documentation that meets your needs. To help us improve the documentation, send any errors, suggestions, or comments to Documentation Feedback ([email protected]). Include the document title and part number, version number, or the URL when submitting your feedback. 90 Documentation feedback - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 91
, 81 B BAD_CPG_PATTERN CPG creation and modification API error, 34 space query API error, 85 BAD_PORT_TYPE VLUN creation API error, 71 BASE enumeration for volume operations, 38 base volume creating, 41 baseId JSON object member for all-volumes query, 49 Boolean vs. boolean attributes, 26 build JSON - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 92
operations, 64 code JSON object member error codes, 16 command line interface see CLI comment JSON object member for all-volumes query, 50 for base-volume creation, 41 for host query, 60 for storage-system query response, 80 for volume modification, 44 common provisioning group see CPG CONFIG_WAIT - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 93
objects for, 29 modifying, 34 removing, 35 single-CPG query, 37 space query, 84 with FPVVs, 29 with TPVVs, 29 cpg JSON object member for base-volume creation, 41 for CPG space query, 84 CPG creation success response, 33 CPG modification error codes, 34, 35 success response, 35 CPG query error - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 94
desriptors JSON object for host query, 59 DetailedState enumeration for CPG operations, 32 enumeration for volume operations, 39 device JSON object member for port query, 66 DeviceCapacity JSON object overall system capacity query response, 81 DHCP_IN_PROGRESS enumeration for port operations, 64 - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 95
creation API error, 53 host modification API error, 57 EXISTENT_VOL volume creation API error, 43 expirationHours JSON object member for base-volume creation, 42 for volume modification, 44 expirationHourse JSON object member for snapshot-volume creation, 43 expirationTime8601 JSON object member - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 96
HP 3PAR Command Line Interface see CLI HP 3PAR Management Console see MC HP 3PAR removing a storage volume, 48 for removing a VLUN, 72 supported, 14 HTTP GET for querying a single CPG, 37 for querying information, 79 for querying version information, 80 supported, 14 HTTP header server, 13 HTTP - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 97
, 44 supported, 14 HTTP request format, 12 HTTP status and error codes, 16 HTTPS, 11 HWAddr JSON object member for port query, 66 Hypertext Transfer Protocol see HTTP Hypertext Transfer Protocol Secure see HTTPS I id JSON object for CPG query, 36 JSON object member for all-volumes query, 48 for base - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 98
object code, 16 defined, 10 desc, 24 null members, 26 optional members for input, 25 ref, 25 required members for input, 25 JSON objects for base-volume creation, 42 for CPG creation, 33 for CPG growth objects, 32 for CPG modification, 35 for CPG query, 37 for CPG space usage, 32 - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 99
K key, 14 see also session key JSON object member for creating a session key, 15 L label JSON object member for port query, 66 LAST enumeration for CPG operations, 30 LDLayout JSON object for CPG creation, 33 for CPG operations, 29 JSON object member for CPG operations, 32 for CPG space query, 85 - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 100
for CPG query, 36 JSON object member, 52 for all-volumes query, 48 for base-volume creation, 41 for host query, 58, 60 for snapshot volume creation, 43 error, 53 space query API error, 85 volume creation API error, 43 node JSON object member for host query, 61 for VLUN operations, 68 nodeList JSON - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 101
JSON object member for all-volumes query, 49 policies JSON object for volume operations, 40 JSON object member for all-volumes query, 50 for base-volume creation, 41 for volume modification, 44 PORT enumeration for CPG operations, 30 enumeration for VLUN operations, 68 Port Property API type for - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 102
volume space operations, 40 RESYNC_TARGET enumeration for volume operations, 39 RETAINED volume removal API error, 48 retentionHours JSON object member for base-volume creation, 42 for snapshot-volume creation, 43 for volume modification, 44 retentionTime8601 JSON object member for all-volumes query - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 103
, 35 for host creation, 52 for host modification, 54 for host removal, 58 for VLUN creation, 69 for VLUN removal, 72 for volume creation, 41 Service for CPG modification, 35 Super for CPG creation, 33 for CPG modification, 35 for CPG removal, 35 for host creation, 52 for host modificaton, 54 - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 104
response, 50 sizeMiB JSON object member for all-volumes query, 49 for base-volume creation, 41 slot JSON object member for host query, 61 for VLUN 30 snapCPG JSON object member for all-volumes query, 50 for base-volume creation, 41 for volume modification, 44 SNAPDATA_INVALID enumeration for volume - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 105
object member overall system capacity query response, 83 URI for creating a CPG, 33 for creating a host, 52 for creating a VLUN, 69 for creating base volumes, 41 for creating snapshot volumes, 42 for deleting a session key, 16 for modifying a host, 54 for modifying a volume, 44 for querying a single - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 106
JSON object member for all-volumes query, 50 for base-volume creation, 42 for volume modification, 45 usrSpcAllocWarningPct JSON object member for all-volumes query, 50 for base-volume creation, 42 for volume modification, 45 UsrUsage JSON object 106 - HP 3PAR StoreServ 7450 2-node | HP 3PAR Web Service API 1.2 Developer's - Page 107
vv_create permissions for, 41 VVs, 68 W warningMiB JSON object member for CPG operations, 32 warningPct JSON object for CPG query, 36 Web Services application program interface see WSAPI WSAPI accessing, 11 description, 9 hostname, 14 overview, 11 request input, 25 session key, 14 system access, 14
HP 3PAR Web Services API 1.2 Developer's
Guide
Abstract
This guide provides instructions and reference information for the HP 3PAR Web Services API.
HP Part Number: QR482-96192
Published: June 2013
Edition: First