3par web services.pdf

HP 3PAR Web Services API 1.1 Developer'sGuide

AbstractThis guide provides instructions and reference information for the HP 3PAR Web Services API.

HP Part Number: QL226-96939Published: March 2013Edition: Second

© Copyright 2013 Hewlett-Packard Development Company, L.P.

Confidential computer software. Valid license from HP required for possession, use or copying. Consistent with FAR 12.211 and 12.212, CommercialComputer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government undervendor's standard commercial license.

The information contained herein is subject to change without notice. The only warranties for HP products and services are set forth in the expresswarranty statements accompanying such products and services. Nothing herein should be construed as constituting an additional warranty. HP shallnot be liable for technical or editorial errors or omissions contained herein.

Contents1 Introduction...............................................................................................6

About the WSAPI......................................................................................................................6Typographic Conventions......................................................................................................6

User Input......................................................................................................................6System Output................................................................................................................6

Getting Started.........................................................................................................................6Configuring the Server..............................................................................................................6About the SDK.........................................................................................................................7

Java SDK............................................................................................................................7Perl SDK.............................................................................................................................7

2 Overview..................................................................................................8Protocol and Message Format....................................................................................................9

Client Headers....................................................................................................................9Examples.....................................................................................................................10

Querying CPGs........................................................................................................10Creating CPGs.........................................................................................................10

Server Headers.................................................................................................................10Supported HTTP Methods....................................................................................................10

GET............................................................................................................................10POST...........................................................................................................................11DELETE........................................................................................................................11

General URI Format................................................................................................................113 System Access..........................................................................................12

Creating Credentials...............................................................................................................12About Multiple Session Keys................................................................................................12About Session Key Security.................................................................................................12

Creating a Session Key...........................................................................................................12Deleting a Session Key............................................................................................................13Getting Version Information......................................................................................................13

Success............................................................................................................................134 Status and Error Codes.............................................................................14

The code Member..................................................................................................................14Codes Listing.....................................................................................................................14

The desc Member...................................................................................................................18Examples..........................................................................................................................18

The ref Member......................................................................................................................18HTTP Error Codes...................................................................................................................18

5 Request Input and Optional Members.........................................................206 Enumerations...........................................................................................217 JSON Types and API Types........................................................................228 Working with Common Provisioning Groups................................................23

CPG Enumeration and Configuration Objects.............................................................................23LDLayout Object................................................................................................................23RAIDType Enumeration........................................................................................................23HA Enumeration................................................................................................................24chunkletPosPref Enumeration................................................................................................24diskPatterns Object.............................................................................................................24diskType Enumeration.........................................................................................................25

Contents 3

Space Usage Objects.........................................................................................................25Growth Objects.................................................................................................................26state Enumeration..............................................................................................................26detailed state Enumeration..................................................................................................26

Create a CPG........................................................................................................................26Message Body Parameters..................................................................................................27Responses.........................................................................................................................27

Success........................................................................................................................27Error Codes..................................................................................................................27

Remove a CPG.......................................................................................................................27Responses.........................................................................................................................28

Success........................................................................................................................28Errors..........................................................................................................................28

Query CPG Information...........................................................................................................28Responses.........................................................................................................................29

Success........................................................................................................................299 Working with Storage Volumes..................................................................30

Volume Enumeration and Configuration Objects.........................................................................30ProvisioningType Enumeration Types.....................................................................................30CopyType Enumeration Types...............................................................................................30state Enumeration Types......................................................................................................31DetailedState Enumeration Types..........................................................................................31Policies Configuration Object...............................................................................................32space Objects...................................................................................................................32

Create a Storage Volume.........................................................................................................33Create Base Volumes..........................................................................................................33

Message Body Parameters..............................................................................................33Responses....................................................................................................................35

Success...................................................................................................................35Error Codes.............................................................................................................35

Create Snapshot Volumes........................................................................................................35Message body parameters..................................................................................................35

Remove a Storage Volume.......................................................................................................36Responses.........................................................................................................................36

Success Response..........................................................................................................36Error Codes..................................................................................................................36

Query Volume Information.......................................................................................................3610 Working with Virtual LUNs.......................................................................39

Configuration and Enumeration Objects....................................................................................39VLUN portPos Configuration Object......................................................................................39VLUNtype Enumeration.......................................................................................................39VLUN multipathing Enumeration...........................................................................................39VLUN failedPathPol Enumeration..........................................................................................40

Create a VLUN.......................................................................................................................40URI..................................................................................................................................40Request Body....................................................................................................................40Return Status.....................................................................................................................41Response Body..................................................................................................................41Example...........................................................................................................................41

HTTP Request................................................................................................................41HTTP Response.............................................................................................................42

Remove a VLUN.....................................................................................................................42URI Parameters..................................................................................................................42Responses.........................................................................................................................43

4 Contents

Success........................................................................................................................43Error Codes..................................................................................................................43

Example...........................................................................................................................43HTTP Request................................................................................................................43HTTP Response.............................................................................................................43

Query VLUN Information.........................................................................................................43Responses.........................................................................................................................43

Success........................................................................................................................43JSON Objects in a VLUN Query................................................................................44

Example...........................................................................................................................45HTTP Request................................................................................................................45HTTP Response.............................................................................................................45

11 Support and Other Resources...................................................................47Contacting HP........................................................................................................................47HP 3PAR documentation..........................................................................................................47Typographic conventions.........................................................................................................50HP 3PAR branding information.................................................................................................50

12 Documentation feedback.........................................................................51

Contents 5

1 IntroductionThis Developer's Guide describes how to write a client that uses the HP 3PAR Web Services API(HP 3PAR WSAPI) to manage HP 3PAR storage systems. HP 3PAR storage systems include bothhardware components that store data, and software applications to manage data. The ApplicationProgram Interface (API) provides a more flexible and powerful way to perform storage managementtasks than Command Line Interface (CLI) scripting or the HP 3PAR OS Management Consolesoftware. This API enables you to automate management of volumes, Common Provisioning Groups(CPGs), and Virtual LUNs (VLUNs).

About the WSAPIThe API consists of a server and a definition of the operations, inputs, and outputs of the API. TheSoftware Development Kit (SDK) of the API includes a sample client that can be referenced for thedevelopment of customer-defined clients. Clients of the API interact with the server through HTTPS.For an overview of the supported HTTP methods, see “Supported HTTP Methods” (page 10) below.

Typographic Conventions

User InputUser-supplied text is marked as boldface and enclosed in angle brackets, as follows:https://<Storage System>:8080/api/v1/credentials/<session key>

In this example, the user supplied text is:

DescriptionText

The name of the server processing requests and sending responses.<Storage System>

The session key. For more information on session keys, see “CreatingCredentials” (page 12)

<session key>

System OutputSystem-supplied variables are marked in italics and enclosed in angle brackets, as follows:/api/v1/volumes/<volume name><volume name> in this case is the name of the newly created volume, returned in the HTTP Locationheader.

Getting StartedThis section of the HP 3PAR Web Services API Developer's Guide shows how to configure theserver. Included also is an introduction to the WSAPI commands and a summary of the itemsincluded in the HP 3PAR Web Services API Server SDK. It contains the following topics:

• Configuring the server

• About the SDK

Configuring the ServerThe API server is part of the HP 3PAR OS 3.1.2 and will run on the HP 3PAR Storage Server. Theserver must be started with the startwsapi CLI command. It is possible to configure the serverwith setwsapi. To start the server, do the following:1. In the Command Line Interface (CLI), enter the startwsapi command.

6 Introduction

NOTE: This command does not run by default.

2. To configure the server, enter the setwsapi command.

About the SDKIn addition to the WSAPI, HP provides an SDK for Java and Perl, available via download fromsoftware.hp.com.

Java SDKThe Java SDK includes:

• Core "storage-entity" classes representing the attributes of HP 3PAR storage system objects(CPGs, volumes, VLUNs) and input parameters for creating objects.

• An example client interface which demonstrates the use of JavaScript Object Notation (JSON)processors with the base classes.

• Example programs to illustrate the creation and query of base entities. These examples relyon the accessor and base packages.

Perl SDKThe Perl SDK includes:

• A module with methods for accessing the HP 3PAR storage system.

• Modules with mappings of the error codes and enumerated properties used by WSAPI.

• An example program that demonstrates creation, querying, and deleting of base entities.

About the SDK 7

www.software.hp.com

2 OverviewThe HP 3PAR Web Services API (WSAPI) makes it possible to manage storage volumes, CommonProvisioning Groups (CPGs) and Virtual Logical Unit Numbers (VLUNs) through a series of HTTPor HTTPS requests.

NOTE: For security reasons, HTTPS is the preferred choice and is used by default. Throughoutthis document, HTTP is used to refer to both. The behavior is the same using both protocols.

Clients make HTTP requests to the server and receive HTTP replies. When input is provided, suchas with the HTTP POST method, or when output is returned, the body of the messages are codedusing JSON. The message body will be ignored for GET and DELETE operations.The WSAPI enables programmatic management of HP 3PAR storage servers. The clients accessWeb services at specified HTTPS locations that control the following volume management tasks:

• Creating and deleting volumes

• Creating snapshot volumes

• Querying all volumes

• Creating and deleting Common Provisioning Groups (CPGs)

• Querying all CPGs

• Creating and deleting VLUNs

• Querying all VLUNsTasks can be automated by developing a WSAPI client. Because the API is more formally defined,using it is preferable to scripts that use the HP 3PAR CLI, since those scripts will need to processCLI-generated text.

8 Overview

Protocol and Message FormatClients communicate with the WSAPI server using HTTPS and data structures represented withJavaScript Object Notation (JSON). The supported JSON character encodings include the followingformats:

• ASCII

• ISO-8859-1

• US-ASCII

• UTF-8

• UTF-16

• UTF-32

• UTF-16BE

• UTF-32BE

• UTF-16LE

• UTF-32LE

Client HeadersClient header information is required only when the client request has a message body. In theseinstances, the client must provide the HTTP Content-Type specifying application/json and theoptional charset parameter. For example:application/json; charset=UTF-8

The HTTP requests that clients make to the API server include HTTP headers. The following tableshows the required and optional HTTP headers. Optional headers, when present, must be one ofthe values listed in the Values column:

Table 1 Headers Supported by the HP 3PAR Web Services API for Requests

RequiredValuesDescriptionHeader

NoOne of the following:The response format the clientcan accept.

Accept

• application/*

• application/json

• application/json*

NoOne of the following:The response language theclient can accept.

Accept-Language

• *

• en

• en*

Yes, for requestswith a messagebody.

Number of bytesThe length of the content inbytes.

Content-Length

Yes, for requestswith a messagebody.

application/jsonThe format of the body.Content-Type

Yes, except for arequest to createcredentials.

The result of a credentialscreation request.

A key associated with the userthat created credentials.

X-HP3PAR-WSAPI-SessionKey

Protocol and Message Format 9

Examples

Querying CPGsWhen querying the CPGs, the client sends the following:GET /api/v1/cpgs HTTP/1.1

Accept: application/json

Accept-Language: en

X-HP3PAR-WSAPI-SessionKey: 1-c86aedb2e7e98b4119cd74b624b8576b-b06d2d50

Creating CPGsWhen creating a CPG, the client sends the following:POST /api/v1/cpgs HTTP/1.1

X-HP3PAR-WSAPI-SessionKey: 1-c86aedb2e7e98b4119cd74b624b8576b-b06d2d50


Content-Type: application/json

Content-Length: 27

{

"name" : "t887-cpg"

}

Server HeadersTable 2 HTTP headers Included by the Web Services API in Responses

DescriptionValueHTTP Header

The HP 3PAR Web Services API Server.HP3PAR-WSAPIServer

Disables caching by mechanisms between the Web ServicesAPI server software and client (HTTP RFC 2616), for HTTP/1.0and 1.1.

no-cacheCache-Control

Disables caching by mechanisms between the Web ServicesAPI server software and client (HTTP RFC 2616), for HTTP/1.0and 1.1

no-cachePragma

Included when the message body, which will be in JSONformat, is nonempty.

application/jsonContent-Type

The path portion of the URI of a newly created object, suchas:/api/v1/volumes/foo

Varies. See the example inthe Description column.

Location

Encoding is UTF-8 and percent encoded per RFC 3986.

The date and time at which the message was originated, perRFC 2616.

Varies according to thedate.

Date

Supported HTTP MethodsThis section summarizes the HTTP methods currently supported by the HP 3PAR WSAPI. Theseinclude:

GETThe GET method retrieves information identified by the Request-URI.

10 Overview

POSTThe POST method requests an object described by the body of the request be created in thecollection identified by the URI.

DELETEThe DELETE method requests that the server deletes the resource identified by the Request-URI.

General URI FormatAll operations of the API are performed using an HTTP method (GET, POST, or DELETE) and aUniform Resource Identifier (URI). In this example, the URI corresponds to the volume namedprojectXvol residing on the HP 3PAR storage system with the hostnamestorsys1.example.com:https://storsys1.example.com:8080/api/v1/volumes/projectXvol

General URI Format 11

3 System AccessThis chapter discusses the use of session keys with the WSAPI. Session keys enable access to theHTTP methods for a single session.

Creating CredentialsIn order to use the Web Services, you must create a session key by providing a username andpassword. The username and password are the same that you would use to access the HP 3PARstorage server through the Command Line Interface (CLI) or the Management Console (MC). Theauthorization carries the same user permissions for the WSAPI as for the CLI/MC, in that you havepermission to perform the same operations through the API (where available) as you would withthe CLI or MC.1. Create a session key using the HTTP POST method with a URL of the following format:

https://<Storage System>:8080/api/v1/credentials

2. The message body of the request is a JavaScript Object Notation (JSON) object with thefollowing members:

ValueJSON typeMember

Usernamestringuser

User's passwordstringpassword

NOTE: For error output for this and other conditions, see “Status and Error Codes” (page 14).

About Multiple Session KeysA multi-threaded client application can use one session key in multiple threads concurrently.However, the requested operations will be serialized by the server. When true concurrency isneeded, a client can create a session key for each concurrent thread.

NOTE: This increases server resource usage and should be kept to a small number to avoidaffecting server performance.

About Session Key SecurityBecause session keys allow access to the storage server, client applications should not displaysession keys or otherwise make them visible to end users. Revealing a session key is similar torevealing a password in that an unauthorized person who obtains a session key can use it toaccess the storage server until the key is deleted.

Creating a Session KeyExcept for creating and deleting a session key, the session key is required for all operations andis passed in an HTTP header with the name X-HP3PAR-WSAPI-SessionKey. Each session keyis associated with the IP address of the client that originally requested it, and subsequent use isrestricted to requests from that same IP address. An example of creating a session key using cURL(a command-line utility available for most Linux distributions) is as follows:1. Enter the following:

curl -k -H "Accept:application/json" -H

"Content-Type:application/json" --data-binary'{"user":"example","password":"example"}'

12 System Access

https://storsys1.example.com:8080/api/v1/credentials

2. The system returns the key in the JSON content of the response:{"key":"1-c86aedb2e7e98b4119cd74b624b8576b-b06d2d50"}

Deleting a Session KeyWhen a client is finished making requests to the server it should delete the session keys it created.This frees up server resources and allows for better server performance.

NOTE: Unused session keys expire automatically after fifteen minutes.

1. To delete a session key, send a request with the HTTP DELETE method and the URI:https://<Storage System>:8080/api/v1/credentials/<session key>

NOTE: The <session key> is the key that is returned in the process of creating a session key.For more information, see “Creating Credentials” (page 12).

2. A successful session key deletion returns status code 200 OK. There is no message body.

NOTE: An error condition returns an error object as a message body.

ExampleAn example of deleting credentials using cURL is:curl -X DELETE -H "Accept: application/json"

https://storsys1.example.com:8080

/api/v1/credentials/1-c86aedb2e7e98b41-b06d2d50

Getting Version InformationA client of the WSAPI can query the API server for version information by using a GET request ona URI in the following form:https://<Storage System>:8080/api

NOTE: A session key is not needed to make the request.

SuccessOn success, a JSON object is returned that describes the interface version provided by the APIserver, as described in the following table:

descriptionJSON typemember

The version major number.numbermajor

The version minor number.numberminor

A build number not meant to beinterpreted by clients, but useful for

numberbuild

identifying specific builds of versionsfor defect reports or support requests.

Deleting a Session Key 13

4 Status and Error CodesWhen an operation is successful, the system returns one of the following HTTP status codes:

• 200 OK

• 201 Created

When an operation fails, one of several HTTP status codes is returned. Also, the message bodycontains a JSON object with information specific to the HP 3PAR WSAPI.The JSON object contains the members code, desc, and, when relevant, ref. The code memberis a number and the rest are strings.The JSON object contains the following members:

The code MemberJust as is the case with CLI text, the text in the desc member (see below) is subject to change andcannot be relied upon. To avoid that problem, the WSAPI provides a reliable code for an error.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 snap CPG specified toError: The volume must have a snap CPG in one storage system version to another.The associated WSAPI error code will not change.The Error code member is a JSON numeric type. Only codes that are defined in the table belowwill be returned.

Codes ListingFor applications that change behavior based on errors, only the code member should be reliedon. For ease of reading documentation, a symbol is defined for each numeric code, but the symbolis not part of the API. The numeric value is the contract between client and server. The codes aredescribed in the following table:

Table 3 API General Error Codes Provided by the code Member

HTTP codeDescriptionAPI error symbolAPI error code

500 InternalServer Error

An internal error has occurred inthe server.

INT_SERV_ERR1

400 Bad RequestAn SSL protocol violation hasoccurred.

INV_SSL2

400 Bad RequestThe client has not sent a completerequest.

INPUT_EOF3

413 RequestEntity Too Large

The client has sent a request thatis too long.

INPUT_TOO_LONG4

403 ForbiddenThe username or password isinvalid.

INV_USER_PASS5

403 ForbiddenThe client request has an invalidsession key.

INV_SESS_KEY6

408 RequestTimeout

The client did not send or receivein time.

TIMEOUT7

505 HTTP VersionNot Supported

The client request has anunsupported HTTP method.

UNSUP_HTTP8

501 NotImplemented

The resource does not support themethod.

UNSUP_OP9

14 Status and Error Codes

Table 3 API General Error Codes Provided by the code Member (continued)


404 Not FoundThe resource of the request doesnot exist.

URI_RES_NOT_FOUND11

400 Bad RequestThe client request contains aninvalid value.

INV_INPUT12

403 ForbiddenPermission denied, insufficientprivileges.

PERM_DENIED13

409 ConflictThe CPG already exists.EXISTENT_CPG14

404 Not FoundThe CPG does not exist.NON_EXISTENT_CPG15

409 ConflictThe host already exists.EXISTENT_HOST16

404 Not FoundThe host does not exist.NON_EXISTENT_HOST17

409 ConflictThe VLUN already exists.EXISTENT_LUN18

404 Not FoundThe VLUN does not exist.NON_EXISTENT_VLUN19

400 Bad RequestAttempt to create VLUN withinvalid port type.

BAD_PORT_TYPE21

409 ConflictThe storage volume alreadyexists.

EXISTENT_VOL22

404 Not FoundThe storage volume does notexist.

NON_EXISTENT_VOL23

400 Bad RequestNot enough space is availablefor the operation. This varies

NO_SPACE24

based on the followingcircumstances:• In volume creation, when the

CPG contains insufficientspace for the specified volumesize.

• In CPG creation, when thestorage system's hardwareconfiguration does not supportthe requested LD layout.

• In CPG creation, when thechunklets that are required forthe requested LD layout are inthe process of being cleaned.

409 ConflictThe volume has a read-only child.HAS_RO_CHILD25

409 ConflictVolume retention time has notexpired.

RETAINED27

400 Bad RequestThe client request contains avalue that is too large.

TOO_LARGE28

400 Bad RequestA more specific error could notbe determined.

OTHER29

503 ServiceUnavailable

The server has reached itsmaximum number of connections.

SVC_UNAVAIL31

409 ConflictThe Virtual Volume (VV) has achild VV2.

HAS_CHILD32

409 ConflictThe VV has no snapshot CPGconfigured.

NO_SNAP_CPG33

The code Member 15



409 ConflictThe resource is in use.IN_USE34

406 NotAcceptable

The representation specified inclient's Accept header is notsupported.

UNSUP_REPRESENTATION35

406 NotAcceptable

The language specified in client'sAccept-Language header is notsupported.

UNSUP_LANGUAGE36

400 Bad RequestInvalid RAID set size.INV_SET_SIZE37

404 Not FoundThe domain does not exist.NON_EXISTENT_DOMAIN38

400 Bad RequestA JSON input object contains aname-value pair where the type

INV_INPUT_WRONG_TYPE39

of the value differs from what isexpected (e.g. a number is foundwhere a string is expected). Refcontains the name of thename-value pair.

400 Bad RequestA JSON input object is missing arequired name-value pair. Refcontains the expected name.

INV_INPUT_MISSING_REQUIRED40

400 Bad RequestA JSON input object containsmore than one name-value pair

INV_INPUT_DUP_NAME41

with the same name. Ref containsthe name.

400 Bad RequestA JSON input object contains aname-value pair with a name that

INV_INPUT_UNREC_NAME42

is unrecognized. Ref contains thename.

400 Bad RequestA JSON input object contains aname-value pair with a numeric

INV_INPUT_EXCEEDS_RANGE43

value that exceeds the expectedrange. Ref contains the name

400 Bad RequestA JSON input object contains aname-value pair that cannot be

INV_INPUT_PARAM_CONFLICT44

present with another name-valueparameter that is present. Refcontains the name

400 Bad RequestA JSON input object contains aname-value pair with an empty

INV_INPUT_EMPTY_STR45

string (distinct from a null string)where a string of length greaterthan zero is required.

400 Bad RequestA JSON input object contains anenum property with a value that’snot in the valid range.

INV_INPUT_BAD_ENUM_VALUE46

400 Bad RequestThe allocation warning level ishigher than the allocation limit.

INV_INPUT_WARN_GT_LIMIT47

400 Bad RequestUser space allocation alerts onlyvalid with TPVV.

INV_INPUT_USR_ALRT_NON_TPVV48

400 Bad RequestThe VV retain time is greater thanthe expiration time.

INV_INPUT_RETAIN_GT_EXPIRE49




400 Bad RequestAn invalid policy (e.g., system orcaching) is specified for VV.

INV_INPUT_VV_POLICY50

415 UnsupportedMedia Type

Unsupported content (e.g., asspecified in Content-Type HTTPheader).

UNSUP_CONTENT51

400 Bad RequestA JSON object was expected butanother JSON type was found.

INV_INPUT_NOT_JSON_OBJ52

400 Bad RequestA pattern in a CPG specifiesillegal values.

BAD_CPG_PATTERN53

400 Bad RequestMissing both hostname and portposition.

MISSING_VLUN_EXPORT_INFO54

400 Bad RequestIncorrect port specification.INV_INPUT_PORT_SPECIFICATION55

400 Bad RequestInvalid URL percent encoding.INV_URL_PERCENT_ENCODING56

400 Bad RequestInvalid input: string lengthexceeds limit.

INV_INPUT_EXCEEDS_LENGTH57

400 Bad RequestInvalid time specified.INV_INPUT_TIME58

409 ConflictAn ID exists.EXISTENT_ID59

400 Bad RequestJSON syntax error. When theerror is associated with an object

JSON_SYNTAX_ERR60

member, ref contains the nameof the member.

400 Bad RequestToo many levels of nesting inJSON; numbers too large to be

JSON_NOT_SUPPORTED61

represented; length restrictionsexceeded. When the error isassociated with an objectmember, ref contains the nameof the member.

400 Bad RequestInvalid HTTP header syntax.INV_HTTP_HEADER62

400 Bad RequestA request body contains asequence of characters that is

INV_UTF63

invalid for the supported UTFencodings.

400 Bad RequestA POST request is missing aJSON request body.

INV_INPUT_NO_REQ64

400 Bad RequestThe request line (first line) of anHTTP request does not meet the

INV_HTTP_REQ65

form specified for “Request-Line”in RFC 2616.

400 Bad RequestThe URI is not absolute, containscharacters not allowed in a URI,

INV_URI66

contains invalid percentencoding, or, after percentdecoding, contains an invalidUTF-8 character sequence.

400 Bad RequestA POST request contains anaction member with an invalidvalue.

INV_POST_ACTION67

The code Member 17



503 ServiceUnavailable

Services that the system dependson in order to process therequested operation are notready.

SYS_SVC_NOT_READY68

400 Bad RequestInput contains one or more illegalcharacters.

INV_INPUT_ILLEGAL_CHAR69

403 ForbiddenSystem is not licensed for thisfeature or functionality.

UNLICENSED_FEATURE70

The desc MemberThe desc member provides supplementary information that helps explain the reason for the errorcode.

NOTE: The text in this member is subject to change between releases.

ExamplesExamples of desc are:{"code":28,"desc":"client request contains values that are too large”}

{"code":24,"desc":"insufficient space for requested operation"}

The ref MemberIn the event of an error that may occur for several reasons, the ref member may specify the reasonfor the error. For example, if the client were to send an incorrect value for a JSON member thenthe server may be able to identify which member had the incorrect value.

NOTE: There are errors in which a ref member is not necessary or useful. So, it may not appearfor all errors.

Examplecurl -k -H "Accept:application/bogus" -H

"X-HP3PAR-WSAPI-SessionKey:9-1786eb905dabf39a4d564e799ea4360c-8053d24f"

https://storsys1.example.com:8080

'{"code":35,"desc":"unsupported representation scheme","ref":"Accept"}'

HTTP Error CodesIn addition to the API-specific error information, the response to a client request that has failed willinclude an HTTP error code. Each API error code is associated with an HTTP status code as shownin “API General Error Codes Provided by the code Member” (page 14). The following is anexample of a bad client request, followed by the server response showing how the API error code5 is associated with HTTP status code 403:

RequestPOST /api/v1/credentials HTTP/1.1


Host: storsys1:8080

Content-Length: 44


Expect: 100-continue


{"password":"not bob’s password","user":"bob"}

ResponseHTTP/1.1 403 Forbidden

Date: Tue, Wed, 31 Oct 2012 22:15:52 GMT

Server: hp3par-wsapi


Connection: close

{"code":5,"desc":"invalid user or password"}

HTTP Error Codes 19

5 Request Input and Optional MembersFor some API operations, such as POST, the client passes a JSON object as the message body.The JSON object includes required parameters for the operation and may include optionalparameters. Most operations have optional parameters.For example, to create a volume, only the name of the volume, the name of the CPG that providesdisk space for the volume, and the size of the volume are required. Optional parameters includethe ID of the volume and a comment.When constructing a JSON object, optional members may be omitted or set to values that indicatethe server should ignore them. The client sets only the fields of interest. The JSON object need notinclude all members. A client can perform one of two possible operations when creating the JSONobject:

• Include only the optional members required for the operation,or

• Include a member that is not required, but with a value that means it should be ignored.When writing a client in a language that provides services for serializing a class into a JSONobject, it is convenient to only have a single class that represents all required or optional parameters.The following chapters will specify the special values to use to ignore a member.

20 Request Input and Optional Members

6 EnumerationsSome properties have values from a fixed set of limited values. For example, the state property ofa Storage Volume can be one of Normal, Degraded or Failed. When properties like these arepresent in a JSON object, they are represented numerically.In addition to the values shown in the definition of an enumeration, each enumeration can alsohave the value of -1, meaning that the API server has encountered a value that it does not recognizeand therefore cannot assign a value from the valid set. This usually means a defect in the APIserver.The values defined for an enumeration start with 1; the value 0 is unused.When using tools that deserialize JSON into a class, this allows an omitted property of enumerationtype to be detected, since the member will not be assigned a non-zero value of a property andwill retain its default or pre-set value of 0.For enumerations, the symbols used in this document are for convenience in referring to values ofenumerations, but are not part of the WSAPI. Integer values representing the symbols appear inJSON objects. Clients can use any symbols with the integers.

21

7 JSON Types and API TypesJSON uses primitive types defined by IETF RFC 4627, including:

• String

• Number

• Boolean

• null

The properties returned in JSON output objects and the parameters provided in JSON input objectsuse JSON primitive types with additional restrictions on valid values. Restrictions on values orformat are given names that appear in the Type column in the table below. These API types arereferenced in the sections below describing JSON input and output.

Table 4 API Types

DescriptionType

JSON string with time in ISO 8601 format:YYYY-MM-DDThh:mm:ssTZD ,

8601

where TZD is Z or +hh:mm or -hh:mm

NOTE: For more information, see http://www.w3.org/TR/NOTE-datetime

JSON number restricted to a 32-bit signed integer where negative values areignored by the server, and treated as if not present.

igint32

The number of seconds since 01/01/1970 GMT.epoch

Also known as “Unix epoch.”

JSON number restricted to a 32-bit signed integerint32

JSON string of 31 or fewer characters, in which the following characters areallowed:

name31

a-z

A-Z

0-9

. (dot)- (dash)

NOTE: Dash (-) is disallowed as the first character.A name of 0 characters is represented in JSON as the empty string “”.An unset name is represented in JSON as null.

JSON string of 511 or fewer characters.print511

JSON number restricted to a 32-bit unsigned number.uint32

JSON string of 16 or 32 characters.WWN

For port and FC Host it is always 16 characters.Possible characters are:

• 0 – 9

• a – f

• A – F

JSON members suffixed with MiB represent size or space in mebibtyes where 1 MiB = 1,048,576 bytes (2^20 bytes).Members suffixed with MB represent size or space in megabytes where 1MB = 1,000,000 bytes (10^6 bytes).JSON members suffixed with Pct mean percent.

22 JSON Types and API Types

http://www.w3.org/TR/NOTE-datetime

8Working with Common Provisioning GroupsYou can use a Common Provisioning Group (CPG) to create a virtual pool of logical disks thatallows virtual volumes to share the resources of the CPG and allocates space on demand. You cancreate fully-provisioned virtual volumes and Thinly-Provisioned Virtual Volumes (TPVVs) that drawspace from the logical disk pool.You can use this chapter to:• Create a CPG

• Remove a CPG

• Query a CPG

CPG Enumeration and Configuration ObjectsMany of the CPG operation objects have enumerations or contain sub-objects as detailed in thefollowing sections.

LDLayout ObjectTable 5 LDLayout object

Ignored ValuesDescriptionAPI typeJSON typeMember

Negative valuesSpecifies the RAID type for thelogical disk.

RAIDType enumnumberRAIDType

Negative valuesSpecifies the set size in thenumber of chunklets.

igint32numbersetSize

Negative valuesSpecifies that the layout mustsupport the failure of one port

HA enumnumberHA

pair, one cage, or onemagazine.

Negative valuesSpecifies the chunklet locationpreference characteristics.

chunkletPosPrefenum

numberchunkletPosPref

NoneSpecifies patterns forcandidate disks.

array ofdiskPatternsobjects

array ofobjects

diskPatterns

RAIDType EnumerationTable 6 RAIDType enumeration

DescriptionValueSymbol

RAID level 01R0

RAID level 12R1

RAID level 53R5

RAID level 64R6

CPG Enumeration and Configuration Objects 23

HA EnumerationTable 7 HA Enumeration


Support failure of a port.1Port

Support failure of a drive cage.2cage

Support failure of a drive magazine.3mag

chunkletPosPref EnumerationTable 8 chunkletPosPref enumeration


Lowest numbered available chunklets, where transfer rate is the fastest.1first

Highest numbered available chunklets, where transfer rate is the slowest.2last

diskPatterns ObjectTable 9 diskPatterns Object

IgnoredvaluesDescriptionValueSymbol

NullSpecifies one or more nodes. Nodes areidentified by one or more integers. Multiple

stringnodeList

nodes are separated with a single comma(1,2,3). A range of nodes is separated with ahyphen (0–7). The primary path of the disksmust be on the specified node number.

NullSpecifies one or more PCI slots. Slots areidentified by one or more integers. Multiple slots

stringslotList

are separated with a single comma (1,2,3). Arange of slots is separated with a hyphen (0–7).The primary path of the disks must be on thespecified PCI slot number(s).

NullSpecifies one or more ports. Ports are identifiedby one or more integers. Multiple ports are

stringportList

separated with a single comma (1,2,3). A rangeof ports is separated with a hyphen (0–4). Theprimary path of the disks must be on thespecified port number(s).

NullSpecifies one or more drive cages. Drive cagesare identified by one or more integers. Multiple

stringcageList

drive cages are separated with a single comma(1,2,3). A range of drive cages is separatedwith a hyphen (0–3). The specified drive cage(s)must contain disks.

NullSpecifies one or more drive magazines. Drivemagazines are identified by one or more

stringmagList

integers. Multiple drive magazines areseparated with a single comma (1,2,3). A rangeof drive magazines is separated with a hyphen(0–7). The specified magazine(s) must containdisks.

NullSpecifies one or more disk positions within adrive magazine. Disk positions are identified

stringdiskPosList

by one or more integers. Multiple disk positions

24 Working with Common Provisioning Groups

Table 9 diskPatterns Object (continued)

IgnoredvaluesDescriptionValueSymbol

are separated with a single comma (1,2,3). Arange of disk positions is separated with ahyphen (0–3). The specified portion(s) mustcontain disks.

NullSpecifies one or more physical disks. Disks areidentified by one or more integers. Multiple disks

stringdiskList

are separated with a single comma (1,2,3). Arange of disks is separated with a hyphen (0–3).Disks must match the specified ID(s).

Negativevalues

Specifies that physical disks with total chunkletsgreater than the number specified be selected.

numbertotalChunkletsGreaterThan

Negativevalues

Specifies that physical disks with total chunkletsless than the number specified be selected.

numbertotalChunkletsLessThan

Negativevalues

Specifies that physical disks with free chunkletsless than the number specified be selected.

numberfreeChunkletsGreaterThan

Negativevalues

Specifies that physical disks with free chunkletsgreater than the number specified be selected.

numberfreeChunkletsLessThan

Null arrayelements

Specifies that PDs identified by their models areselected.

array of stringdiskModels

Negativevalues

Specifies that physical disks must have thespecified device type. See diskTypeenumeration.

numberdiskType

Negativevalues

Disks must be of the specified speed.numberRPM

diskType EnumerationTable 10 diskType Enumeration


Fibre Channel1FC

Near Line2NL

SSD3SSD

Space Usage ObjectsTable 11 SDUsage, SAUsage, and UsrUsage Objects

DescriptionAPI typeJSON typeMember

Total logical disk space in MiB.uint32numbertotalMiB

Total physical (raw) logical disk space inMiB.

uint32numberrawTotalMiB

Amount of logical disk used, in MiB.uint32numberusedMiB

Amount of physical (raw) logical diskused, in MiB.

uint32numberrawUsedMiB

CPG Enumeration and Configuration Objects 25

Growth ObjectsTable 12 SAGrowth and SDGrowth Objects


Threshold of used logical disk space, whenexceeded, results in a warning alert.

uint32numberwarningMiB

The auto-grow operation is limited to the specifiedstorage amount that sets the growth limit.

uint32numberlimitMiB

The growth increment, the amount of logical diskstorage created on each auto-grow operation.

uint32numberincrementMiB

Logical disk types to be used for this CPG. SeeLDLayout object for member details.

LDLayout objectobjectLDLayout

state EnumerationTable 13 state Enumeration


The CPG is operating normally.1normal

The CPG is in a degraded state.2degraded

The CPG is operating abnormally.3failed

detailed state EnumerationDetailedState enumeration values are used in multiple arrays including failedStates,degradedStates, and additionalStates. Details of the CPG's state are enumerated in thefollowing table:

Table 14 detailedState Enumeration


Admin space at limit.1SALimitReached

Copy space at limit.2SDLimitReached

Admin space grow failed.3SAGrowFailed

Copy space grow failed.4SDGrowFailed

Admin space at warning level.5SAWarnReached

Copy space at warning level.6SDWarnReached

Invalid7Invalid

Create a CPGThis topic describes how to create a CPG.You create a CPG with the HTTP POST method to the following URI:https://<Storage System>:8080/api/v1/cpgs

NOTE: Any user with Super or Edit role, or any role granted with the cpg_create right canperform this operation.


Message Body ParametersTable 15 CPG creation Members

Ignored valuesDescriptionAPI TypeJSON typeMember

None (Required)Specifies the name of theCPG.

name31stringname

Negative valuesSpecifies the growthincrement, the amount of

igint32numbergrowthIncrementMiB

logical disk storage createdon each auto-growoperation.

Negative valuesSpecifies that the auto-growoperation is limited to the

igint32numbergrowthLimitMiB

specified storage amountthat sets the growth limit.

Negative valuesSpecifies that the thresholdof used logical disk space,

igint32numberusedLDWarningAlertMiB

in MiB, when exceededresults in a warning alert.

NullSpecifies the name of thedomain in which the objectwill reside.

name31stringdomain

NoneSpecifies Logical Disk typesto be used for this CPG.

LDLayoutobject

objectLDLayout

Responses

SuccessA successful operation returns status code 201 Created. There is no message body.On successful creation of the CPG, the Location response header contains the URI for the newlycreated CPG in the following format:/api/v1/cpgs/<cpg name>

Error CodesIf there is an error condition, the system returns one of the following error codes, or a general errorcode listed in “API General Error Codes Provided by the code Member” (page 14):

DescriptionHTTP codeAPI error

Domain doesn’t exist404 Not FoundNON_EXISTENT_DOMAIN

CPG already exists409 ConflictEXISTENT_CPG

A pattern in a CPG specifies illegal values400 Bad RequestBAD_CPG_PATTERN

Invalid RAID set size400 Bad RequestINV_SET_SIZE

Remove a CPGA CPG is removed with the HTTP DELETE method to the URI:https://<Storage System>:8080/api/v1/<cpg name>

Remove a CPG 27

Responses

SuccessStatus code 200 OK is returned with no message body.

Errors

DescriptionHTTP codeAPI error

CPG not found404 Not FoundNON_EXISTENT_CPG

The CPG cannot be removed because it is in use bya volume

408 ConflictIN_USE

Query CPG InformationQuerying for CPG information is done with the HTTP GET method on the URI with no messagebody:https://<Storage System>:8080/api/v1/cpgs

The body is an object with total and members as described below.As is the case with all collection queries, the total object is the number of objects in the collection.The members object is a JSON array of zero or more JSON objects as listed in the following table:

Table 16 JSON objects for CPG Queries

DescriptionAPI TypeJSON typeMember

CPG IDuint32numberid

UUID that was automatically assigned to the CPG atcreation.

uuid stringstringuuid

CPG namename31stringname

Domain that the CPG belongs toname31stringdomain

Percentage usage at which to issue an alert. This is set withthe CLI createcpg –aw parameter which is deprecatedand not exposed by this API

uint32numberwarningPct

Number of Thinly Provisioned Virtual Volumes allocated inthe CPG.

uint32numbernumTPVVs

Number of Fully Provisioned Virtual Volumes allocated inthe CPG.

uint32numbernumFPVVs

User data space usageUsrUsage objectobjectUsrUsage

Snapshot administration usageSAUsage objectobjectSAUsage

Snapshot data space usageSDUsage objectobjectSDUsage

Snapshot administration space auto-growth parametersSAGrowth objectobjectSAGrowth

Snapshot data space auto-growth parametersSDGrowth objectobjectSDGrowth

Overall state of the CPGstate enumnumberstate

Detailed state of CPGarray ofDetailedStateenum

array ofnumbers

failedStates


Table 16 JSON objects for CPG Queries (continued)



array ofnumbers

degradedStates


array ofnumbers

additionalStates

Responses

SuccessOn success, status code 200: OK is returned.

Query CPG Information 29

9Working with Storage VolumesThis chapter describes how to manage storage volumes. The sections apply to creation, modification,and query operations on storage volumes. You can perform the following operations on storagevolumes:

• Query storage volume

• Create a storage volume

• Remove a storage volumeQueries for storage volume information are created with the HTTP GET method on a URI, with nomessage body. The syntax is as follows:https://<Storage System>:8080/api/v1/volumes

Unless an error occurs, the response includes a message body with JSON objects total andmembers. The object members will contain an array of zero or more JSON objects, shown belowas the Output object. The total is the number of objects in the members array.

Volume Enumeration and Configuration ObjectsSeveral enumerations and configuration objects are used for the various volume API operations.These are described in the following sections:

ProvisioningType Enumeration TypesTable 17 Enumeration for the provisioningType JSON Object


Fully provisioned VV, either with no snapshot space or with staticallyallocated snapshot space. Also, a commonly-provisioned VV where the user

1full

space is fully provisioned and the snapshot space is associated with thesnapCPG property.

Thin provisioned VV, with space for the base volume allocated from the Usrspace that is associated with the userCPG property. Also includes old-style

2tpvv

thin provisioned VV (created on a 2.2.4 release or earlier) where both thebase VV and snapshot data are allocated from the Snap space associatedwith userCPG.

The VV is a snapshot (Type vcopy) and its space is provisioned from thebase volume's snapshot space.

3snp

Remote volume admitted into the local storage system.4peer

Unknown5unknown

CopyType Enumeration TypesTable 18 Enumeration for theCopyType JSON Object


Base volume (not a copy)1base

Physical copy (full copy)2physicalCopy

Snapshot copy (virtual copy)3virtualCopy

30 Working with Storage Volumes

state Enumeration TypesTable 19 Volume state Enumeration


The virtual volume (VV) is operating normally1normal

VV is in degraded state2degraded

VV is operating abnormally3failed

DetailedState Enumeration TypesDetails of the volume's state are enumerated in the following table. DetailedState is not aJSON object itself, but rather an enumeration that applies to multiple JSON objects, includingfailedStates, degradedStates, and additionalStates.

Table 20 Volume DetailedState Enumeration


LDs Not Started.1LDsNotStarted

VV Not Started.2NotStarted

Needs to be checked for consistency3NeedsCheck

Maintenance Check Required.4NeedsMaintCheck

Internal Consistency Error.5InternalConsistencyError

Snapshot data Invalid.6SnapdataIinvalid

One or more sets of an LD is unavailable due to missingchunklets and the remaining VV data is preserved.

7Preserved

Parts of the VV contain old data because of acopy-on-write operation.

8Stale

A promote or copy to this volume failed.9CopyFailed

Degraded due to availability10DegradedAvail

Degraded due to performance11DegradedPerf

Volume is currently the target of a promote.12Promoting

Volume is currently the target of a physical copy.13CopyTarget

Volume is currently the target of a resync copy.14ResyncTarget

Volume is tuning.15Tuning

Volume is closing.16Closing

Volume is removing.17Removing

Volume is retrying a remove.18RemovingRetry

Volume is creating.19Creating

Copy source.20CopySource

Volume is importing.21Importing

Volume is converting.22Converting

Invalid23Invalid

Volume Enumeration and Configuration Objects 31

Policies Configuration ObjectTable 21 Policies Object


true: Stale snapshots. If there is no space for acopy-on-write operation, the snapshot is allowed to

BooleanstaleSS

go stale but the host write can proceed without anerror.false: No stale snapshots. If there is no space fora copy-on-write operation, the host write will fail.

true: This indicates a volume is constrained toexport to one host or one host cluster.

BooleanoneHost

false: This indicates a volume exported to multiplehosts for use by a cluster-aware application, orwhen "port presents" VLUNs are used

true: This indicates that the storage system willscan for zeros in the incoming write data.

BooleanzeroDetect

false: This indicates that the storage system willnot scan for zeros in the incoming write data.

true: Special volume used by the system.Booleansystem

false: Normal user volume

This is a read-only policy and cannot be set.true: This indicates that the storage system isenabled for write caching, read caching, and readahead for the volume

Booleancaching

false: This indicates that the storage system isdisabled for write caching, read caching, and readahead for the volume.

space ObjectsThe volume space is specified by the following three sub-objects, each of which uses the samemembers:

• adminSpace

• snapshotSpace

• userSpace

The members are listed in the following table:

Table 22 Members of the JSON Volume Space Objects adminSpace


Reserved space in MiBuint32numberreservedMiB

Raw reserved space in MiBuint32numberrawReservedMiB

Used space in MiBuint32numberusedMiB

Free space in MiBuint32numberfreeMiB


Create a Storage VolumeThis section contains information on creating volumes, and includes the following topics:

• Create base volumes

• Create snapshot volumesWhen creating a snapshot volume, the message body is a JSON object with two members, actionand parameters. The action member is a string with the value "createSnapshot". The parametersmember is a JSON object with members described in “Create Snapshot Volumes” (page 35).

NOTE: Any user with Super or Edit role, or any role granted with the volumes_create rightcan perform this operation.

Create Base VolumesA Storage Volume is created with the HTTP POST method to the URI:https://<Storage System>:8080/api/v1/volumes

NOTE: The <Storage System> will be replaced with the actual storage system’s hostnameor IP address.

Message Body ParametersThe message body is a JSON object with the members shown in the following tables. Most of themembers are optional. When creating a snapshot volume, isCopy is set to true and name andcopyOfName are required. The definition of members can be found in the CLI Reference Manualor in the column help for the CLI command createvv

Ignored valuesDescriptionAPI TypeJSON TypeMember

None (Required)Specifies a VV name upto 31 characters inlength.

name31stringname

None (Required)Specifies the name of theCPG from which the

name31stringcpg

volume user space willbe allocated.

None (Required)Specifies the size for thevolume in MiB. The

uint32numbersizeMiB

volume size is roundedup to the next multiple of256 MiB.

Negative valuesSpecifies the ID of thevolume. If not specified,

igint32numberid

the next available ID ischosen.

NoneSpecifies any additionalinformation up to 511

print511stringcomment

characters for thevolume.

None except cachingand system which areignored if false.

Specifies virtual volumepolicies.

Policies objectobjectpolicies

NoneSpecifies the name of theCPG from which the

name31stringsnapCPG

snapshot space will beallocated.

Create a Storage Volume 33


Negative values.Enables a snapshotspace allocation

igint32numberssSpcAllocWarningPct

warning. A warning alertis generated when thereserved snapshot spaceof the virtual volumeexceeds the indicatedpercentage of the virtualvolume size.

Negative valuesSets a snapshot spaceallocation limit. The

igint32numberssSpcAllocLimitPct

snapshot space of thevirtual volume isprevented from growingbeyond the indicatedpercentage of the virtualvolume size.

Nonetrue: Create TPVVBooleanBooleantpvv

false: (default) CreateFPVV

Negative valuesThis option enables userspace allocation

igint32numberusrSpcAllocWarningPct

warning. It specifies thata warning alert isgenerated when thereserved user space ofthe TPVV exceeds thespecified percentage ofthe virtual volume size.

Negative valuesthis option sets the userspace allocation limit.

igint32numberusrSpcAllocLimitPct

The user space of theTPVV is prevented fromgrowing beyond theindicated percentage ofthe virtual volume size.After this size is reached,any new writes to thevirtual volume will fail.

Negative valuesSpecifies the relativetime from the current time

igint32numberexpirationHours

that the value will expire.Value is a positiveinteger with a range of1 - 43,800 hours (1825days).

Negative valuesSpecifies the amount oftime relative to the

igint32numberretentionHours

current time that thevolume will be retained.Value is a positiveinteger with a range of1 - 43,800 hours (1825days).


Responses

SuccessA successful operation returns status code 200 OK. There is no message body.On successful creation of the volume, the Location response header, contains the URI for the newlycreated volume in the following format:/api/v1/volumes/<volume name>

Error CodesAn error condition returns one of the following:

Descriptionstatus codeAPI error code

The volume already exists409 ConflictEXISTENT_SV

Volume size above architectural limit400 Bad RequestTOO_LARGE

Create Snapshot VolumesA snapshot is created with the HTTP POST method to the URI:https://<Storage System>:8080/api/v1/volumes/<volume name>

<volume name> is the name of the volume being copied.

Message body parametersThe message body is a JSON object with two members, action and parameters.The action member is a string with the value "createSnapshot" and the parameters member isa JSON object with members described below.


None (Required)Specifies a snapshot VV name up to 31characters in length.

name31stringname

Negative valuesSpecifies the ID of the volume. If notspecified, the next available ID ischosen.

igint32numberid

NoneSpecifies any additional information upto 511 characters for the volume.

print511stringcomment

Nonetrue: Specifies that the copied volumeis read-only.

BooleanBooleanreadOnly

false: (default) The volume isread-write.

Negative valuesSpecifies the relative time from thecurrent time that the volume will expire.

igint32numberexpirationHours

Value is a positive integer and in therange of 1–43,800 hours, or 1825days.

Negative valuesSpecifies the relative time from thecurrent time that the volume will expire.

igint32numberretentionHours

Value is a positive integer and in therange of 1–43,800 hours, or 1825days.

Create Snapshot Volumes 35

Remove a Storage VolumeA volume is removed with the HTTP DELETE method to the URI with no message body:https://<server>/api/v1/volumes/<volume>

Responses

Success ResponseA successful removal returns the following code:status code 200: OK

Error CodesAn error returns one of the following:

Descriptionstatus codeAPI error code

The volume does not exist404 Not FoundNON_EXISTENT_VOL

Volume retention time has not expired403 ForbiddenRETAINED

Volume has read-only child403 ForbiddenHAS_RO_CHILD

Query Volume InformationQuerying for Storage Volume information is done with the HTTP GET method on the URI, with nomessage body:https://<Storage System>:8080/api/v1/volumes

Unless an internal server error occurs, the response includes a message body that returns an objectthat has a total member and a members member with members being the array of objects. –one for each volume on the system. These objects are described in the following table:

Table 23 JSON objects for Volume Queries


VV identifierint32numberid

UUID that was automaticallyassigned to the volume at creation.

uuid stringstringuuid

VV namename31stringname

VV domainname31stringdomain

The provisioning for the VV.provisioningType enumnumberprovisioningType

Indicates the copy type of the VV.copyType enumnumbercopyType

If the VV is a physical copy or virtualcopy of another VV, this field

name31stringcopyOf

indicates the VV that this VV is acopy of.

The ID of the VV that is the base VV(at the root of the snapshot tree) forthe VV.

uint32numberbaseId

true: Read onlyBooleanBooleanreadOnly

false: Read and write allowed.

State of the VV.state enumnumberstate


Table 23 JSON objects for Volume Queries (continued)


Detailed state of VV.Array of DetailedState enumArray ofnumbers

failedStates

Detailed state of VV.Array of State enumArray ofnumbers

degradedStates

Detailed state of VV.Array of DetailedState enumArray ofnumbers

additionalStates

Admin space in MiB.SpaceObjectadminSpace

Snapshot space in MiB.SpaceObjectsnapshotSpace

User space in MiB .SpaceObjectuserSpace

Virtual size of volume in MiB(1024^2 bytes).

uint32numbersizeMiB

ID of the parent in the snapshot tree(not necessarily same as the CopyOfVV).

int32numberparentId

ID of the read-only child VV in thesnapshot tree.

int32numberroChildId

Id of the read-write child VV in thesnapshot tree.

int32numberrwChildId

ID of the Physical Parent. Valid onlyfor a physical copy.

int32numberphysParentId

Volume World Wide Name.WWNstringwwn

The time when the VV was created,measured in seconds since 12 AMon 01/01/1970.

epochnumbercreationTimeSec

The time when the VV was created.8601StringcreationTime8601

The time when the VV will expire.epochnumberexpirationTimeSec

The time when the VV will expire.8601numberexpirationTime8601

The time at which the volumeretention time expires.

epochnumberretentionTimeSec

The time at which the volumeretention time expires.

8601stringretentionTime8601

Enables a snapshot space allocationwarning. A warning alert is

igint32numberssSpcAllocWarningPct

generated when the reservedsnapshot space of the virtual volumeexceeds the indicated percentage ofthe virtual volume size.

Sets a snapshot space allocationlimit. The snapshot space of the

igint32numberssSpcAllocLimitPct

virtual volume is prevented fromgrowing beyond the indicatedpercentage of the virtual volume size.

This option enables a user spaceallocation warning. It specifies that

igint32numberusrSpcAllocWarningPct

a warning alert is generated whenthe reserved user space of the TPVVexceeds the specified percentage ofthe virtual volume size.

Query Volume Information 37

Table 23 JSON objects for Volume Queries (continued)


This option sets the user spaceallocation limit. The user space of the

igint32numberusrSpcAllocLimitPct

TPVV is prevented from growingbeyond the specified percentage ofthe virtual volume size. After the sizeis reached, any new writes to thevirtual volume will fail.

Policies used for the VV.policies objobjectpolicies

CPG name from which the user spaceis allocated.

name31stringuserCPG

CPG name from which the snapshot(Snap and Admin) space is allocated.

uint32stringsnapCPG

Comment associated with the volume.print511stringcomment


10 Working with Virtual LUNsThis chapter describes the API operations you can perform on Virtual LUNs (VLUNs). A VLUN is apairing between a virtual volume and a logical unit number (LUN), expressed as either a VLUNtemplate or an active VLUN.A VLUN template sets up an association between a virtual volume and one of the followingcombinations by establishing the export rule, or the manner in which the Volume is exported. Whenyou create a VLUN template, if the current system state meets the conditions established by thetemplate, active VLUNs, e.g. exports that are seen as LUNs by the host, are the result. Dependingon the conditions of the VLUN template, a single template can produce more than one active VLUN.The sections that follow describe the APIs to perform VLUN operations.

Configuration and Enumeration ObjectsSeveral enumerations and configuration objects are used for managing VLUNs. These configurationobjects are defined in this section.

VLUN portPos Configuration ObjectThe SPI server communicates port position as a portPos object as defined below:

Table 24 JSON Components of the portPos Object.

DescriptionAPI typeJSON typeMembers

System node (0-7)igint32Numbernode

PCI bus slot in the node (0-5)igint32Numberslot

Port number on the FC card (0-4)igint32NumbercardPort

VLUNtype EnumerationThis component enumerates the types of VLUNs assigned in the system.

Table 25 Enumeration of VLUN Types.

DescriptionValue

Empty1

Port2

Host.3

Matched set4

Host set5

VLUN multipathing EnumerationThe API server will communicate the multipathing configuration enumerated as follows:

Table 26 Enumeration of multipathing Configurations for VLUNs

DescriptionValue

Unknown1

RoundRobin2

Failover3

Configuration and Enumeration Objects 39

VLUN failedPathPol EnumerationThe API server will communicate the failed path monitoring method (failedPathPol) enumerated asfollows:

Table 27 Enumeration of failedPathPol Configurations for VLUNs

DescriptionValue

Unknown1

scsiTestUnitReady2

inquiry3

readSector04

Create a VLUNThe following section describes the HTTP request and response parameters for creating a VLUNtemplate.No URI parameters are supported for this operation.

NOTE: Any user with Super, Edit role or any role granted with the vlun_create right canperform this operation.

URIA VLUN is created with the HTTP POST method to the URI:https://<Storage System>:8080/api/v1/vluns

Request BodyThe following JSON members are sent in the request body, for specifying the parameters forcreating a VLUN template.

Ignored ValuesDescriptionAPI TypeJSON typeMember

None (required)Name of the volume to beexported

name31StringvolumeName

None (required)LUN idigint32Numberlun

None* (optional)Name of the host which thevolume is to be exported.

name31Stringhostname

None* (optional)System port of VLUNexported to. It includes

portPosObjectportPos

node number, slot number,and card port number

None* (optional)A VLUN changenotification (VCN) not be

BooleanBooleannoVcn

issued after export (-novcn).Default: False.

None* (optional)Existing lower priorityVLUNs will be overridden

BooleanBooleanoverrideLowerPriority

(-ovrd). Use only ifhostname member exists.Default: False.

* When creating a VLUN, the volumeName and lun members are required. Either hostname or portPos (or bothin the case of matched sets) is also required. The noVcn and overrideLowerPriority members are optional.

40 Working with Virtual LUNs

Return StatusWith a successful VLUN creation, status code 201 Created is returned and there is no messagebody.On successful creation of the VLUN, the Location response header contains the URI for the newlycreated VLUN in the following format:/api/v1/vluns/<volumeName>,<lun>,<hostname>,[<port>]

• The volumeName is the volume that the newly created VLUN exports.

• The hostname or port information or both (depending on the VLUN type) for the newlycreated VLUN. The port information will not be displayed for host type VLUN.

An error condition returns one of the following:

DescriptionHTTP codeAPI status code

Missing volumeName or incomplete port info, , specifyingoverride option without hostname.

400 BadRequest

INV_INPUT_MISSING_REQUIRED

Specified volume does not exist.404 Not foundNON_EXISTENT_VOL

Specified hostname not found.404 Not foundNON_EXISTENT_HOST

Missing both hostname and portPos for VLUNcreation.

400 BadRequest

MISSING_VLUN_EXPORT_INFO

Specified port is of invalid link type.404 Not foundBAD_PORT_TYPE

LUN already exists.409 ConflictEXISTENT_LUN

Incorrect portPos specification or the node or slot orcardPort in portPos object maybe out of range.

400 BadRequest

INV_INPUT_PORT_SPECIFICATION

OverrideLowerPriority is being specified withouthostname.

400 BadRequest

INV_INPUT_PARAM_CONFLICT

LUN is greater than 16384.400 BadRequest

TOO_LARGE

Response BodyOn success, there is no content in the response body for this operation. On failure, the error codeand API-specific error information is sent.

ExampleThe following example creates a matched VLUN type template for test_vv02 volume.

HTTP RequestPOST /api/v1/vluns HTTP/1.1

Host: storsys1.example.com:8080



X-HP3PAR-WSAPI-SessionKey: 2-33fe8891e288b34b3f914410e7cc7907-a93d1c50

{

"volumeName":"test_vv02",

"lun":252,

"hostname":"mysystem",

"portPos":{

Create a VLUN 41

"node": 2,

"slot": 2,

"cardPort": 4

},

"noVcn":false,

"overrideLowerPriority":false

}

HTTP ResponseHTTP/1.1 201 Created

Date: Mon, 16 Apr 2012 06:44:26 GMT


Cache-Control: no-cache

Pragma: no-cache

Location: /api/v1/vluns/test_vv02,252,mysystem,2:2:4

Remove a VLUNThe following section describes the HTTP request and response for removing a virtual volume’sSCSI LUN export definition from the system. The VLUN definition is removed with the HTTP Deletemethod to the URI:https://<Storage System>:8080/api/v1/vluns/<volumeName>,<lun>,<hostname>[,<port>][?<query>]

NOTE: Any user with Super, Edit role or any role granted with the vlun_remove right canperform this operation.

URI ParametersThe following parameters are sent in the URI for the delete operation:

Ignored valuesDescriptionURI Parameter*

None (required)Name of the volume to be exportedvolumeName

None (required)LUNlun

None (required if volume is exported to host, orboth host and port)

Name of the host which the volume is exported.For VLUN of port type, the value is empty.

hostname

None (required if volume is exported to port, orboth host and port)

Specifies the system port of the VLUN export. Itincludes the system node number, PCI bus slot

port

number, and card port number on the FC cardin the format:<node>:<slot>:<port>

* Must be percent encoded as in RFC 3968 for reserved characters.

Table 28 Options Parameter (query)

DescriptionQuery

A VLUN change notification (VCN) not be issued after export (-novcn).noVcn=<true|false>


Responses

SuccessA successful removal returns status code 200: OK with no message body.

Error CodesAn error state returns one of the following:

DescriptionStatus codeAPI error

Incomplete VLUN info.400 Bad RequestINV_INPUT_MISSING_REQUIRED

Missing volumeName or lun, or both hostname andport.

Specified hostname not found404 Not FoundNON_EXISTENT_HOST

Incorrect LUN or volumeName404 Not FoundNON_EXISTENT_VLUN

Specified volume name not found404 Not FoundNON_EXISTENT_VOLUME

Specified port is invalid.400 Bad RequestINV_INPUT_PORT_SPECIFICATION

The LUN specified exceeds expected range.400 Bad RequestINV_INPUT_EXCEEDS_RANGE

ExampleIn the following example VLUNs with LUN 252, exported to storsys1 is deleted. The optional portinformation is also sent because the VLUN is of matched type.

HTTP RequestDELETE /api/v1/vluns/test_vv02,252,mysystem,2:2:4 HTTP/1.1





HTTP ResponseHTTP/1.1 200 OK

Date: Mon, 16 Apr 2012 07:16:39 GMT


Cache-Control: no-cache

Pragma: no-cache

Connection: close

Query VLUN InformationThe VLUN query fetches all the VLUN templates and active-VLUNs on the system. Querying forVLUN information is done with the HTTP GET method on the URI. The syntax is as follows:https://<Storage System>:8080/api/v1/vluns

Responses

SuccessA successful query returns status code 200 OK and a response body with the following members:

Query VLUN Information 43

JSON Objects in a VLUN Query


Number of VLUN objectsreturned

int32numbertotal

VLUN propertiesArray of VLUN Propertyobjects

array of objectsmembers

The members object is a JSON array of zero or more JSON objects – one for each VLUN on thesystem.These objects are described in the following table.


Exported LUN Valueuint32numberlun

Name of exported VirtualVolume name

name31stringvolumeName

Hostname the VLUN isexported to

name31stringhostname

host WWN, or iSCSI name,or SAS addr; depends onport type

name31stringremoteName

System port of VLUNexported to. It includes node

portPos objectFor more information, see“JSON Components of the

objectportPos

number, slot number, andcardPort numberportPos Object.”

(page 39)

VLUN typeVLUNtype enumnumbertypeFor more information, see“Enumeration of VLUNTypes.” (page 39)

WWN of exported volumeWWNstringvolumeWWN

Multipathing method in usemultipathing enumnumbermultipathingFor more information see“Enumeration ofmultipathingConfigurations for VLUNs”(page 39)

Failed path monitoringmethod

failedPathPol enumFor more information, see“Enumeration of

numberfailedPathPol

failedPathPolConfigurations for VLUNs”(page 40)

Monitoring interval inseconds after which the hostchecks for failed paths

uint32numberfailedPathInterval

The device name for thisVLUN on the host

name31stringhostDeviceName

Specified if the VLUN is anactive VLUN or a VLUNtemplate. , .

BooleanBooleanactive

true for active VLUNfalse for VLUN template


ExampleThe example lists all the VLUN templates or active VLUNs, including all active and template VLUNson the storage system:

HTTP RequestGET /api/v1/vluns HTTP/1.1





HTTP Response{"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": true

},

{

"lun": 10,

"volumeName": "vol1.0",

"portPos": {

"node": 0,

"slot": 4,

"cardPort": 1

},

"type": 4,

"volumeWWN": "60002AC0000000000000020D0000017D",

"multipathing": 1,

"failedPathPol": 1,

Query VLUN Information 45

"failedPathInterval": 0,

"active": false

}

]

}


11 Support and Other ResourcesContacting HP

For worldwide technical support information, see the HP support website:http://www.hp.com/support

Before contacting HP, collect the following information:

• Product model names and numbers

• Technical support registration number (if applicable)

• Product serial numbers

• Error messages

• Operating system type and revision level

• Detailed questionsSpecify the type of support you are requesting:

Support requestHP 3PAR storage system

StoreServ 7000 StorageHP 3PAR StoreServ 7200 and 7400 Storage systems

3PAR or 3PAR StorageHP 3PAR StoreServ10000 Storage systemsHP 3PAR T-Class storage systemsHP 3PAR F-Class storage systems

HP 3PAR documentation

See:For information about:

The Single Point of Connectivity Knowledge for HPStorage Products (SPOCK) website:

Supported hardware and software platforms

http://www.hp.com/storage/spock

The HP 3PAR StoreServ Storage site:Locating HP 3PAR documentshttp://www.hp.com/go/3parTo access HP 3PAR documents, click the Support link foryour product.

HP 3PAR storage system software

HP 3PAR StoreServ Storage Concepts GuideStorage concepts and terminology

HP 3PAR Management Console User's GuideUsing the HP 3PAR Management Console (GUI) to configureand administer HP 3PAR storage systems

HP 3PAR Command Line Interface Administrator’sManual

Using the HP 3PAR CLI to configure and administer storagesystems

HP 3PAR Command Line Interface ReferenceCLI commands

HP 3PAR System Reporter Software User's GuideAnalyzing system performance

HP 3PAR Host Explorer User’s GuideInstalling and maintaining the Host Explorer agent in orderto manage host configuration and connectivity information

HP 3PAR CIM API Programming ReferenceCreating applications compliant with the Common InformationModel (CIM) to manage HP 3PAR storage systems

Contacting HP 47

http://www.hp.com/support

http://www.hp.com/storage/spock

http://www.hp.com/go/3par


HP 3PAR-to-3PAR Storage Peer Motion GuideMigrating data from one HP 3PAR storage system to another

HP 3PAR Secure Service Custodian Configuration UtilityReference

Configuring the Secure Service Custodian server in order tomonitor and control HP 3PAR storage systems

HP 3PAR Remote Copy Software User’s GuideUsing the CLI to configure and manage HP 3PAR RemoteCopy

HP 3PAR Upgrade Pre-Planning GuideUpdating HP 3PAR operating systems

HP 3PAR F-Class, T-Class, and StoreServ 10000 StorageTroubleshooting Guide

Identifying storage system components, troubleshootinginformation, and detailed alert information

HP 3PAR Policy Server Installation and Setup GuideInstalling, configuring, and maintaining the HP 3PAR PolicyServer HP 3PAR Policy Server Administration Guide

48 Support and Other Resources


Planning for HP 3PAR storage system setupHardware specifications, installation considerations, power requirements, networking options, and cabling information

for HP 3PAR storage systems

HP 3PAR StoreServ 7000 Storage Site Planning ManualHP 3PAR 7200 and 7400 storage systems

HP 3PAR StoreServ 10000 Storage Physical PlanningManual

HP 3PAR 10000 storage systems

HP 3PAR StoreServ 10000 Storage Third-Party RackPhysical Planning Manual

Installing and maintaining HP 3PAR 7200 and 7400 storage systems

HP 3PAR StoreServ 7000 Storage Installation GuideInstalling 7200 and 7400 storage systems and initializingthe Service Processor HP 3PAR StoreServ 7000 Storage SmartStart Software

User’s Guide

HP 3PAR StoreServ 7000 Storage Service GuideMaintaining, servicing, and upgrading 7200 and 7400storage systems

HP 3PAR StoreServ 7000 Storage Troubleshooting GuideTroubleshooting 7200 and 7400 storage systems

HP 3PAR Service Processor Software User GuideMaintaining the Service ProcessorHP 3PAR Service Processor Onsite Customer Care(SPOCC) User's Guide

HP 3PAR host application solutions

HP 3PAR Recovery Manager Software for Oracle User'sGuide

Backing up Oracle databases and using backups for disasterrecovery

HP 3PAR Recovery Manager Software for MicrosoftExchange 2007 and 2010 User's Guide

Backing up Exchange databases and using backups fordisaster recovery

HP 3PAR Recovery Manager Software for Microsoft SQLServer User’s Guide

Backing up SQL databases and using backups for disasterrecovery

HP 3PAR Management Plug-in and Recovery ManagerSoftware for VMware vSphere User's Guide

Backing up VMware databases and using backups fordisaster recovery

HP 3PAR VSS Provider Software for Microsoft WindowsUser's Guide

Installing and using the HP 3PAR VSS (Volume Shadow CopyService) Provider software for Microsoft Windows

HP 3PAR Storage Replication Adapter for VMwarevCenter Site Recovery Manager Implementation Guide

Best practices for setting up the Storage Replication Adapterfor VMware vCenter

HP 3PAR Storage Replication Adapter for VMwarevCenter Site Recovery Manager Troubleshooting Guide

Troubleshooting the Storage Replication Adapter for VMwarevCenter Site Recovery Manager

HP 3PAR VAAI Plug-in Software for VMware vSphereUser's Guide

Installing and using vSphere Storage APIs for ArrayIntegration (VAAI) plug-in software for VMware vSphere

HP 3PAR documentation 49

Typographic conventionsTable 29 Document conventions

ElementConvention

Bold text • Keys that you press

• Text you typed into a GUI element, such as a text box

• GUI elements that you click or select, such as menu items, buttons,and so on

Monospace text • File and directory names

• System output

• Code

• Commands, their arguments, and argument values

<Monospace text in angle brackets> • Code variables

• Command variables

Bold monospace text • Commands you enter into a command line interface

• System output emphasized for scannability

WARNING! Indicates that failure to follow directions could result in bodily harm or death, or inirreversible damage to data or to the operating system.

CAUTION: Indicates that failure to follow directions could result in damage to equipment or data.

NOTE: Provides additional information.

RequiredIndicates that a procedure must be followed as directed in order to achieve a functional andsupported 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 the "InForm OS" is now referred to as the "HP

3PAR OS."• The user interface previously referred to as the "InForm Management Console (IMC)" is now

referred to as the "HP 3PAR Management Console."• All products previously referred to as “3PAR” products are now referred to as "HP 3PAR"

products.

50 Support and Other Resources

12 Documentation feedbackHP is committed to providing documentation that meets your needs. To help us improve thedocumentation, send any errors, suggestions, or comments to Documentation Feedback([email protected]). Include the document title and part number, version number, or the URLwhen submitting your feedback.

51

mailto:[email protected]

3par web services.pdf

Documents

hp products

hp shallnot

par web services api

confidential computer

commercialcomputer software

reference information

technical data

commercial items