HPE StoreVirtual REST API Reference Guide

Transcription

1 HPE StoreVirtual REST API Reference Guide Abstract This reference guide provides information about the HPE StoreVirtual Storage REST API which can be integrated with the management of applications hosted in the cloud. Part Number: AX Published: March 2016 Edition: 3

2 Copyright 2015 Hewlett Packard Enterprise Development LP The information contained herein is subject to change without notice. The only warranties for Hewlett Packard Enterprise products and services are set forth in the express warranty statements accompanying such products and services. thing herein should be construed as constituting an additional warranty. Hewlett Packard Enterprise shall not be liable for technical or editorial errors or omissions contained herein. Confidential computer software. Valid license from Hewlett Packard Enterprise required for possession, use, or copying. Consistent with FAR and , Commercial Computer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor's standard commercial license. Links to third-party websites take you outside the Hewlett Packard Enterprise website. Hewlett Packard Enterprise has no control over and is not responsible for information outside the Hewlett Packard Enterprise website. Acknowledgements Microsoft and Windows are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries. OpenStack is a U.S. registered trademark of the OpenStack Foundation Revision History Revision 1 January 2015 First release of the HP StoreVirtual Storage REST API which can be integrated with the management of applications hosted in the cloud Revision 2 August 2015 Corrected minor errors such as duplicated text and typographical errors. Revision 3 March 2016 Updated for Hewlett Packard Enterprise branding. Add Management Group API calls; added createsnapshotset Action Object Model and rollbackvolume Action Object Model; added createdby field to snapshot actions; corrected references to clusterid.

3 Contents 1 HPE StoreVirtual REST API Overview...4 OpenStack...4 Naming conventions...5 Framework...5 Authentication...7 Object models...8 Resources Query parameters...11 Fields...11 Expand-links...13 Name...15 Query...15 listactions Supported API calls...18 Credentials...18 Management Group...25 Clusters...28 Volumes...44 Snapshots...77 Servers API client tutorial Prerequisites Creating and deleting an authorization token Common REST helper functions Getting a collection Finding an entity by name within a collection Creating a volume Creating a server Assigning server access to a volume Removing server access from a volume Modifying an entity Getting an entity Using the listactions query parameter Using the query query parameter Error object messageids Support and other resources Accessing Hewlett Packard Enterprise Support Accessing updates Websites Customer self repair Remote support Documentation feedback Index Contents 3

4 1 HPE StoreVirtual REST API Overview OpenStack The HPE StoreVirtual REST API (also referred to as REST API) allows authenticated users of HPE StoreVirtual storage systems to perform operations on associated objects, such as clusters, storage systems, volumes, and snapshots. Additionally, authorization polices may be established at the user and user-group level. This mechanism enhances security by preventing unauthorized access to, and operation of, the storage pool. In StoreVirtual, a single management group may consist of one or more clusters, which contain storage systems and volumes. With REST API-based management, you can complete the following tasks: NOTE: For all tasks listed, the REST API supports all operations available through the StoreVirtual Centralized Management Console (CMC). Read, create, and modify volumes. Use the volume templates available through the REST API to create multiple volumes of the same configuration. With a single command, obtain the status of all associated storage volumes. You can specify additional volume attributes when creating or modifying volumes with the REST API, including the designation of thin or full provisioned volumes and Adaptive Optimization capability. Create and manage snapshots. Create, modify, and delete server access to data on storage clusters. When creating servers, you can manage the associated volume assignment and unassignment through a single command or a script. The REST API returns standard error codes when the server cannot fulfill a request from the client. With standard error codes, you can quickly understand the root cause of a problem and expedite resolution. The StoreVirtual REST API is using JSON, a resource-based data transfer mechanism, to further simplify communications between the scripting client and the StoreVirtual storage system. JSON is derived from the JavaScript scripting language to enhance interfaces and build dynamic websites. Like REST API, JSON is noted for its simplicity and usability as it can send data in plain text, making it easy to read and understand. REST API for StoreVirtual can be integrated with the management of applications hosted in the cloud such as OpenStack. OpenStack is an open source infrastructure as a service (IaaS) initiative for creating and managing large groups of storage, processing, and networking in a cloud computing environment. The goals of the OpenStack initiative are to support interoperability between cloud services and allow small to enterprise businesses to build cloud services in their own data centers. This technology consists of a series of interrelated projects that control pools of compute, storage, and networking resources throughout a data center that can easily be managed or provisioned through the REST API. New OpenStack drivers, such as OpenStack Block Storage a.k.a. Cinder, are available to provision StoreVirtual storage. HPE LeftHand OS v 1 and later provides the necessary compatibility for the Cinder drivers. The Cinder driver is referenced in section 4 of the HPE StoreVirtual 4000 Storage Compatibility Matrix found at As new drivers are approved and made available, they will be listed in the Compatibility Matrix. Drivers can be downloaded from the website: These drivers act as a set of REST APIs for which all authentication and container/object operations can be performed with standard HTTP calls, creating the foundation of cloud offerings. This augments the existing OpenStack drivers for StoreVirtual, which are based on the proprietary CLI StoreVirtual CLIQ. 4 HPE StoreVirtual REST API Overview

5 It is a lightweight framework with capabilities for service components to expose feature sets via declarative sets for the purpose of interacting with the outside world. Naming conventions Framework Camel case: All attributes use camel case names, beginning with a lower case character (for example, virtualporttype). Acronyms: In a two-character acronym, both characters are capitalized, except when used as the first word in a camel case identifier (for example, remote IP). In an acronym with three or more characters, only the first character is capitalized, except when used as the first word in a camel case identifier (for example, virtualwwn). Units: For attributes that have units, the unit identifier is appended to the name (for example, portspeedmbps). Value consistency: Constants use PascalCase, which uses upper case for the first character, and then follows camel case rules (for example, PoweredOn). Protocol and message format (HTTPS and JSON) API version The REST API uses: HTTPS 1.1 media types application/json Internet media types application/schema+json UTF-8 character encoding An X-API-Version header is used to implement a blanket version of the REST API. All requests contain the X-API-Version header on responses. HTTP request headers The following HTTP headers are accepted in client requests. Values Required Accept application/json The REST API supports only JSON for return data. Accept-Charset UTF-8 The REST API supports only UTF-8 character encoding. Accept-Language en_us,en_ca,es,ja,ko,zh Preferred natural language of response. Default is en_us. Authorization Auth <session token> A valid token used for API calls. Yes. Either Authorization or Auth are required. Content-Length <length in bytes> Length of content contained in message body. Content-Type application/json Type of content contained in message body. Currently, JSON is the only accepted content type. Naming conventions 5

6 Host <domain name and port> Identifies the host receiving the message. Yes (HTTP 1.1 requirement) X_HP-CHRP-Client-Version.4 Declares the specification version of the API that this client was programmed against. x.y.z format with no leading zeros. X-API-Version x.x The REST API version that runs on the system. Yes HTTP response headers The following HTTP headers may be returned in server responses. Cache-Control Content-Length Content-Type Date Location X_HP-CHRP-Service-Version X-API-Version Values no-cache <length in bytes> application/json <current date/time> <uri to new resource>.4 x.x Indicates to the client or intermediary proxy servers not to cache the response. Length of the response body. Type of content contained in the response body. Currently, JSON is the only accepted content type. Time the message response was sent. ISO 8601 format. Location of a newly created resource from a POST operation. Declares the specification version of the API that this service was programmed against. x.y.z format with no leading zeros. API Version that the response is given. HTTP methods (GET, PUT, POST, DELETE) URI format GET, PUT (update), POST (create/action/event), and DELETE are supported. GET Retrieve the object. The message body is ignored. PUT Update with complete or partial information sent in the request body. If one field encounters an error, then none of the update request is applied. POST Used for creation/action/event. A resource is created by sending the HTTP POST method to the URI of the collection in which the resource will reside. The body of the request is used to send either a representation of the object to be created, or a list of parameters defining the resource. If a resource representation is sent, the service can ignore any service controlled attributes (for example, id), forcing those attributes to be overridden by the service. The service sets the Location header to the URI of the newly created resource. The response optionally includes a representation of the newly created resource. DELETE Call on the resource URI to delete the resource. The Resource URI format is: node ip>:8081/lhos/<resource-type-in-plural></ id><?><query-string> 6 HPE StoreVirtual REST API Overview

7 URIs use all lower case characters without spaces. Use the hyphen character (-) between words. The IP address and port portion of the URI is omitted for returned URIs, for example, the POST location header contains /lhos/volumes/<id>. Authentication Any operation on the API requires a valid session key. Create a session key by using the established credentials for the management group containing the REST server. A POST is made to the credentials URI to establish a new session key; see the POST /lhos/credentials API call for more details. Use the HTTP standard Authorization (or Auth) header to pass the session key when making REST API calls. If a valid session key is not used in a REST API call, the call fails with a 401 http status. Clients using session tokens on the VIP require retry logic in the event the VIP system becomes unavailable. A session key can be used for multiple calls, reducing overhead by not invoking PAM authentication for each API call. Once a client completes a series of commands and the token is no longer needed, the recommended practice is to remove the session key using the DELETE /lhos/credentials/<resource id> API call. Session token expiration The maximum number of REST sessions that can be established is 1,000 entries. The REST server enforces a session inactivity timer and a session lifetime timer. Once a REST session is established, the creation time and last modification time are recorded. Each time a REST call uses an authorization token, the last modification time for the session is updated. If a REST session has not been used for 15 minutes, it is automatically removed. Furthermore, even when a REST session is constantly active, a 24 hour lifetime timeout is enforced. Once a REST session has been in existence for 24 hours, it will be automatically removed. If a new session is established while the session table is at the maximum capacity of 1,000, the least recently used algorithm removes the oldest session so the new session can be added. Authorization groups LeftHand OS supports four authorization groups. See LeftHand OS authorization groups (page 7). Access to each of these groups can be customized within the management group, including creation of a new user group. The custom user group defines the permissions allowed for each of the authorization groups: Read-Only Read-Modify Full Table 1 LeftHand OS authorization groups Authorization Group Management Groups Network System Administration Reports Management Groups, RAID, Drive Hot Swap TCP/IP, SNMP, DNS, Time Storage System Administration, Boot, Upgrade System and Disk Report A user can be a member of one or more user groups. The REST API enforces the appropriate level of authorization when servicing a request. The client must validate whether the user credentials used in a session key have the necessary authorization capabilities for the intended Authentication 7

8 API calls. Each of the supported API calls defines the minimal authorization level required to satisfy a particular call. Object models The StoreVirtual REST API offers the flexibility to request the details of a single entity using a unique ID or field, or information on a collection of entities using the entity type within the URL. Within an Entity, Unique Resource Identifiers (URIs) to other resources (Entities or Collections) are returned as part of a Link object, which may contain the full resource for user/client convenience. All resources, except for resource schemas, are based on Entities or Collections (see the following definitions). Entity An Entity object can be a complex object with fields containing: A sub-object A link to an Entity object A link to a Collection object The Entity object is also a base class for singular resources and has its own URI. Field JSON Type API Type name The name of the object. description The description of the object. uri URI The URI of the object. type The type of object. created DateTime ISO 8601 extended The date and time in ISO 8601 extended format of when the object was created. modified DateTime ISO 8601 extended The date and time in ISO 8601 extended format of when the object was created or last modified, including addition and deletion of members in the collection. actions Array Action[] (optional) A list of actions. Collection The Collection object is a base class for plural resources, has its own URI, and acts as a container for Entity resources. A Collection contains summary data about the collection as well as an array of Entity members. The Collection members array is homogeneous. Field JSON Type API Type name The name of the object. description The description of the object. uri URI The URI of the object. type The type of object. 8 HPE StoreVirtual REST API Overview

9 total Number Integer The total number of objects in the collection that match the query (regardless of paging). members Array <type>[] The list containing the requested member objects of the collection. Link Within an Entity, URIs to other resources (Entities or Collections) are returned as part of a Link object. When parameters are passed, the Link object contains the full resource it references. Field JSON Type API Type name The display name for the link. type The type of resource to which the URI points. uri URI The URI of the link. resource Object Entity, Collection, or null The default value is null. The field contains the entity or collection it references when certain query parameters are passed. Error When the REST API encounters an error processing a client request, an HTTP error status is returned in the Status header. An Error object may also be returned in the response body. Field JSON Type API Type messageid Enum Unique code identifying the type of error. This code can be used to access a detailed message from a message registry. t currently implemented. messageargs Array [] An array of arguments to be placed into a message string corresponding to the messageid. t currently implemented. message A human readable error message indicating the semantics associated with the error, including the messageargs pre-inserted into the message corresponding to the messageid. recommendedactions Array [] An optional array of free form strings describing the recommended actions to take for resolution. t currently implemented. A detailed listing of possible messageid values appears in Error object messageids (page 125). Object models 9

10 Resources The following table summarizes the resources available with the StoreVirtual REST API. Resource Path /lhos/managementgroup /lhos/clusters /lhos/cluster/<id> /lhos/credentials /lhos/credentials/<session token> /lhos/servers /lhos/servers/<id> /lhos/snapshots /lhos/snapshots/<id> /lhos/volumes /lhos/volumes/<id> Management group entity Cluster collection Cluster entity Credentials collection Credentials entity Server collection Server entity Snapshot collection Snapshot entity Volume collection Volume entity 10 HPE StoreVirtual REST API Overview

11 2 Query parameters Fields Examples The fields query parameter, applicable to both Entities and Collections, returns a partial resource object. The value is a comma-separated list of field names indicating which fields to return in the response. In addition to those fields, uri and type are always returned. If a field is not present in the resource, the field is ignored. When applied to a Collection object, the results include the collection with the children filtered to only the listed attributes. Attributes of nested sub-objects, like the Link object or inline array objects, are specified using square-bracket notation as described in the Query (page 15) section. If the fields query parameter is not specified, or if the service does not support the fields query parameter, all attributes are returned. Entity GET /lhos/volumes/28?fields=name,description,size "name": "windows-vol", "description": "Windows specific volume.", "type": "volume", "uri": "/lhos/volumes/28", "size": Collection GET /lhos/volumes?fields=members[name],members[description],members[size] "type": "volume", "uri": "/lhos/volumes", "total": 1, "members": [ "name": "windows-vol", "description": "Windows specific volume.", "type": "volume", "uri": "/lhos/volumes/28", "size": ] Sub-object within an entity GET /lhos/volumes/28?fields=name,description,sessions[status] "name": "windows-vol", "description": "Windows specific volume.", "type": "volume", "uri": "/lhos/volumes/28", Fields 11

12 "sessions": [ "status": "connected" ] Sub-object within a Collection /lhos/volumes?fields=members[name],members[sessions[status]] "type": "volume", "uri": "/lhos/volumes", "total": 1, "members": [ "name": "windows-vol", "type": "volume", "uri": "/lhos/volumes/28", "sessions": [ "status": "connected" ] Fields within a Link object in an Entity NOTE: Because the requested fields reside in a Link object, expansion occurs automatically and there is no need to specify the expand-links query parameter. /lhos/volumes/28?fields=name,description,sessions[server[resource[name]]], sessions[status] "name": "windows-vol", "description": "Windows specific volume.", "type": "volume", "uri": "/lhos/volumes/28", "sessions": [ "server": "name": "server", "type": "server", "uri": "/lhos/servers/19", "resource": "name": "ftc-work10", "type": "server", "uri": "/lhos/servers/19", 12 Query parameters

13 ] "status": "connected" Fields within a Link object in a Collection /lhos/volumes?fields=members[name],members[sessions[server[resource[name]]]] "type": "volume", "uri": "/lhos/volumes", "total": 1, "members": [ ] Expand-links "name": "windows-vol", "type": "volume", "uri": "/lhos/volumes/28", "sessions": [ ] "server": "name": "server", "type": "server", "uri": "/lhos/servers/19", "resource": "name": "ftc-work10", "type": "server", "uri": "/lhos/servers/19" The expand-links query parameter is applicable to both Entities and Collections. An Entity may contain references to other resources in the form of Link objects (see Object models (page 8)). This may require a client to make multiple requests to obtain the necessary data. The expand-links query parameter can reduce the number of requests by allowing the client to specify which links should be expanded to contain the actual resource. The Link object contains the resource field. The resource field value is null by default, but will contain the actual resource when the expand-links query parameter is applied. The expand-links query parameter is used to populate Link objects with the resources to which they refer. The value is a comma-separated list of field names indicating which links should be expanded. The value all indicates that all links should be expanded. For example: expand-links=snapshots,volumeacl[server]. Every Link object will be automatically expanded if all is used. For example: expand-links=all. Expand-links 13

14 When associated entities link to each other, circular references may exist. The REST API performs a first-level expansion, expanding a given entity only once. Nested Link objects beyond the first level cannot be expanded Link objects within Link objects will not be expanded. The following example illustrates a side-by-side comparison of the effects of the expand-links query parameter. The left-hand column shows an unexpanded embedded server link object and snapshots collection link object. The right-hand side shows the query parameter used to expand these link objects. NOTE: The example uses an abbreviated form of a Volume Entity. n-pertinent fields are replaced with an ellipsis,, and inline comments added with two forward slashes as the prefix, //. Unexpanded link objects for an entity and collection Expanded link objects for an entity and collection GET /lhos/volumes/28 GET /lhos/volumes/28?expand-links= iscsisessions[server],snapshots // Entity "name": "windows-vol", "name": "windows-vol", "iscsisessions": [ " iscsisessions ": [ // Link to an entity "server": "server": "name": "server", "name": "server", "type": "server", "type": "server", "uri": "/lhos/servers/19", "uri": "/lhos/servers/19", "resource": "resource": null // Server link object expanded, // inline... "name": "ftc-work10",... ], // Link to collection, "snapshots":... "name": "snapshots", "type": "snapshot", ], "uri": "snapshots": "/lhos/snapshots?volumename=windows-vol", "name": "snapshots", "resource": null "type": "snapshot", "uri": "/lhos/snapshots?volumename=windows-vol",... "resource": // Snapshot collection expanded // inline "name": "Snapshots Collection", "description": "Collection of Snapshot objects", "type": "snapshot", "uri": "/lhos/snapshots", "members": [ "name": "windows-vol_ss_1", Query parameters

15 ],... Name Query The name query parameter applies only to Collections. The name query parameter retrieves an Entity by name from a Collection. It is a shortcut for: query=name+eq+<entity-name>. The value for name is case-sensitive. For example: GET /lhos/volumes?name=myvolume123 <entity object where name=myvolume123> The response contains the Entity object model for the resource. If the resource is not found, the response contains a 404 t Found return status code and an error object model. The query query parameter applies only to Collections and selects which members of a Collection to return in the response. The value is a filter expression compliant with the HPE URI Filter Language (UFL) format. The field names specified in the filter apply to the Entity type (not the Collection summary data shown below). Square brackets are used to indicate that the context of a filter expression is within a sub-object. Example - Filter on a Collection s Entity field: GET /lhos/servers?query=name+eq+myserver <collection summary>, count : 1, "total": 1, "members": [ ] listactions <full entity object where name=myserver> EQ, the only supported operator, searches for an Entity whose attribute value matches the value passed into the query string. Currently, only certain collections support the query parameter, and only certain fields can be queried. See the API client tutorial (page 110) section for more details. The listactions query parameter applies to both Entities and Collections, and returns the list of available actions. The only acceptable value for this query parameter is true. listactions=true returns a list of action description objects for the addressed resource. An action description object contains the action name, URI, description of the action, and a list of parameter definitions specific to the action. listactions enables a generic tool to inspect the resource and determine valid actions. When listactions=true is sent to a collection, the response contains a list of the actions that can be sent to the collection. Name 15

16 Example NOTE: The fields query parameter is used to limit the response to the actions descriptor object only. GET /lhos/volumes/28?listactions=true&fields=actions "type": "volume", "uri": "/lhos/volumes/28", "actions": [ "action": "addserveraccess", "uri": "/lhos/volumes/28", "description": "Assigns server access to this volume resource.", "parameters": [ "name": "serverid", "type": "integer", "description": "Valid server resource identifier.", "optional": false, "name": "exclusiveaccess", "type": "boolean", "description": "Grants or denies exclusive access rights.", "optional": false, "name": "readaccess", "type": "boolean", "description": "Grants or denies read access rights.", "optional": false, "name": "writeaccess", "type": "boolean", "description": "Grants or denies write access rights.", "optional": false ], "action": "removeserveraccess", "uri": "/lhos/volumes/28", "description": "Remove server access from this volume resource.", "parameters": [ "name": "serverid", "type": "integer", 16 Query parameters

17 ], "description": "Valid server resource identifier.", "optional": false ] "action": "createsnapshot", "uri": "/lhos/volumes/28", "description": "Create a snapshot of this volume resource.", "parameters": [ "name": "name", "type": "string", "description": "Snapshot name.", "optional": false, "name": "description", "type": "string", "description": " of the snapshot.", "optional": true, "name": "inheritaccess", "type": "boolean", "description": "Indicates if access rights should be inherited from the volume.", "optional": true ] listactions 17

18 3 Supported API calls Credentials REST API calls require an established session token as described in Authentication (page 7). A POST to the /credentials URI creates a valid token when proper credentials are used. This session token can then serve as the value in the Authorization HTTP header for all API calls. The Auth header can also be used to pass the session token. Credentials are REST sessions established by a client and associated with a valid username that exists in the management group. The following information details how to create, read, and delete credentials. Create Credentials Entity Overview URI: System>:8081/lhos/credentials Type: credentials Base Type: Collection HTTP Method: POST Use HTTP POST on /lhos/credentials to create a new authorization token. The storage system validates the incoming credentials and returns a valid authorization token. A valid authorization token is required for all subsequent REST API calls. NOTE: A session token may also be referred to as an authorization token. Credentials Creation Object Model Field JSON Type Required? user Valid username that exists in the management group. Yes password Valid corresponding password for the user. Yes HTTP Request Request s Accept-Language Accept Accept-Charset Desired, acceptable human language for response. Example: en_us. If the desired language is not recognized, US English is the default (en_us). Content Types that are acceptable for the response. Only application/json is supported. The acceptable character sets for return data. Example: UTF-8. Required? Supported query parameters ne 18 Supported API calls

19 Message Body The message body of the POST request contains the username and password as outlined in the Credentials Creation Object Model (page 18). Example Request POST /lhos/credentials HTTP/1.1 Host: :8081 HTTP Response "user": "someuser", "password": "apassword" Success Codes Success 201 Created Authorization token successfully created. Error Codes HTTP Status Code 400 Bad Request 401 Unauthorized Invalid contents detected in request message body. Invalid user credentials. Response s Content-Type Content-Length Date X-API-Version X_HP-CHRP-Service-Version Cache-Control Location Value(s) application/json <dynamic number> Origin date of response. x.x.4 no-cache URI to new resource Message Body The Authorization token object model for the token is displayed in the message body if valid credentials were supplied. Otherwise, no message body is returned. Example Response HTTP/ Created Date: T16:34: Z Content-Type: application/json Content-Length: 59 X-API-Version: X_HP-CHRP-Service-Version:.4 Credentials 19

20 Cache-Control: no-cache Location: /lhos/credentials/352f2f e84-a47c-75eb76155c42 "authtoken": "352f2f e84-a47c-75eb76155c42" Read credentials collection Overview URI: System>:8081/lhos/credentials Type: RESTSession Base Type: Collection HTTP Method: GET Use HTTP GET on /lhos/credentials to request all currently active REST sessions. REST Sessions Object Model Field JSON Type API Type name REST Sessions Collection description Collection of authentication sessions used by the REST server uri URI /lhos/credentials type RESTSession total Number Uint32 <dynamic> members Array cluster[] <dynamic> NOTE: See REST Session Entity Object Model (page 22) for the RESTSession object model. HTTP Request Request s Authorization Accept-Language Accept Accept-Charset Valid authorization token obtained from POST /lhos/credentials call. Desired, acceptable human language for response. Example: en_us. If the desired language is not recognized, US English is the default (en_us). ContentTypes that are acceptable for the response. Only application/json is supported. The acceptable character sets for return data. Example: UTF-8. Required? Yes Supported query parameters ne. 20 Supported API calls

21 Message Body t applicable no user input is required. The message body of a GET request is ignored or discarded if sent. HTTP Response Success Codes HTTP Status Codes 200 OK Success, the REST sessions collection is included in the message body Error Codes HTTP Status Code 401 Unauthorized Missing, invalid or expired Authorization token used. Establish a new token (POST /lhos/credentials), and retry the operation. Response s Content-Type Content-Length Date X-API-Version X_HP-CHRP-Service-Version Cache-Control Value(s) application/json <dynamic number> Origin date of response. x.x.4 no-cache Message Body The Rest session collection object model. Example Response HTTP/ OK Date: T16:36: Z Content-Type: application/json Content-Length: 661 X-API-Version: X_HP-CHRP-Service-Version:.4 Cache-Control: no-cache "name": "REST Sessions Collection", "description": "Collection of authentication sessions used by the REST server.", "type": "RESTSession", "uri": "/lhos/credentials", "total": 1, "members": [ Credentials 21

22 "name": "352f2f e84-a47c-75eb76155c42", "description": "REST Session", "type": "RESTSession", "id": 0, "uri": "/lhos/credentials/352f2f e84-a47c-75eb76155c42", "created": " T16:34: Z", "modified": " T16:36: Z", "username": "admin", "clientip": " " ] Read credentials entity Overview URI: System>:8081/lhos/credentials/<resource id> Type: RESTSession Base Type: Entity HTTP Method: GET Use HTTP GET on /lhos/credentials/<resource id> to request a specific REST session. The <resource id> is the authorization token returned in the POST /lhos/credentials call. REST Session Entity Object Model Field JSON Type API Type name Contains the unique authorization token as the name. description type RESTSession id Number Uint64 Default value of 0. uri URI Path to the resource. created DateTime ISO 8601 Time session was created. modified DateTime ISO 8601 Last time the authorization toke was used. username Username used to create this REST session. clientip IP address of the client s node that established the session. 22 Supported API calls

23 HTTP Request Request s Authorization Accept-Language Accept Accept-Charset Valid authorization token obtained from POST /lhos/credentials call. Desired, acceptable human language for response. Example: en_us. If the desired language is not recognized, US English is the default (en_us). Content Types that are acceptable for the response. Only application/json is supported. The acceptable character sets for return data. Example: UTF-8. Required? Yes Supported query parameters ne. Message Body t applicable no user input is required. The message body of a GET request is ignored or discarded if sent. HTTP Response Success Codes HTTP Status Codes 200 OK Success, the REST Session object is included in the message body Error Codes HTTP Status Code 401 Unauthorized Missing, invalid or expired Authorization token used. Establish a new token (POST /lhos/credentials), and retry the operation. Response s Content-Type Content-Length Date X-API-Version X_HP-CHRP-Service-Version Cache-Control Value(s) application/json <dynamic number> Origin date of response x.x.4 no-cache Credentials 23

24 Message Body The REST sessions object model is returned in the message body. Example Response HTTP/ OK Date: T16:39: Z Content-Type: application/json Content-Length: 346 X-API-Version: X_HP-CHRP-Service-Version:.4 Cache-Control: no-cache "name": "352f2f e84-a47c-75eb76155c42", "description": "REST Session", "type": "RESTSession", "id": 0, "uri": "/lhos/credentials/352f2f e84-a47c-75eb76155c42", "created": " T16:34: Z", "modified": " T16:39: Z", "username": "admin", "clientip": " " Delete credentials entity Overview HTTP Request URI: System>:8081/lhos/credentials/<resource id> Type: credentials Base Type: Entity HTTP Method: DELETE Use HTTP DELETE on /lhos/credentials/<resource id> to delete the active session. As a best practice, clients should delete active sessions when no longer needed. Request s Authorization Accept-Language Accept Accept-Charset Valid authorization token obtained from POST /lhos/credentials call. Desired, acceptable human language for response. Example: en_us. If the desired language is not recognized, US English is the default (en_us). Content Types that are acceptable for the response. Only application/json is supported. The acceptable character sets for return data. Example: UTF-8. Required? Yes 24 Supported API calls

25 Supported query parameters ne. Message Body ne. Example Request DELETE /lhos/credentials/87d7ce9a-d661-48e4-9f b4b678ba HTTP/1.1 Host: :8081 HTTP Response Success Codes Success 200 OK Session successfully deleted. Error Codes HTTP Status Code 401 Unauthorized Invalid authorization token. Response s Content-Type Content-Length Date X-API-Version X_HP-CHRP-Service-Version Cache-Control Value(s) application/json <dynamic number> Origin date of response x.x.4 no-cache Message Body ne. Management Group The Management Group section details how to retrieve management group information from a management group. Read Management Group Entity Overview URI: System>:8081/lhos/managementGroup Type: managementgroup Base Type: Entity HTTP Method: GET Authorization groups (page 7) Management Groups = Read-Only Management Group 25

26 Use HTTP GET on /lhos/managementgroup to request the management group resource. There is only 1 managementgroup entity. Management Group Entity Object Model Field JSON Type API Type API Version Name Name of the management group 1.3 description 1.3 Type managementgroup 1.3 Id Number Uint64 Always has a value of uri URI /lhos/managementgroup 1.3 created DateTime ISO 8601 t available 1.3 modified DateTime ISO 8601 t available 1.3 SoftwareVersion Array Software Version Entity Object Model (page 26) The currently installed software versions for the management group. This represents the version of the MG, all patch sets... etc. 1.3 md5sum md5 sum for management group 1.3 SupportedFeatures Array [] Enum: The identifier indicates the list of licensed features supported at the management group level. Valid Values are RMCSTOREONCE RMCSTOREONCEVMWARE RMCSTOREONCESQL 1.3 Software Version Entity Object Model Field JSON Type API Type API Version name Name e.g. GlobalDatabaseVersion 1.3 version Version number (i.e. x.x.x.x), e.g. " " 1.3 description 1.3 HTTP Request Request s Required? API Version Authorization Auth Valid authorization token obtained from POST /lhos/credentials call. Yes. Either an Authorization or Auth is required. Accept-Language Desired, acceptable human language for response. Example: "en_us". If the desired 26 Supported API calls

27 language is not recognized, US English is the default (en_us). Accept Content-Types that are acceptable for the response. Only application/json is supported. Accept-Charset The acceptable character sets for return data. Example: UTF-8. Supported query parameters ne Message Body The message body of a GET request is ignored. HTTP Response Success Codes HTTP Status Codes 200 OK Success, the cluster object is included in the message body API Version Error Codes HTTP Status Code 400 Bad Request 401 Unauthorized 500 Internal Server Error A non-numeric value was used for the resource identifier. Missing, invalid or expired Authorization token used. Establish a new token ( Create Credentials Entity (page 18)), and retry the operation. Unexpected internal error encountered, see the error object returned in the response body and refer to Error object messageids (page 125) for specific details. API Version Response s Content-Type Content-Length Date X-API-Version X_HP-CHRP-Service-Version Cache-Control Value(s) application/json <dynamic number> Origin date of response..4 no-cache API Version Message Body The Management Group Entity object model or an Error object model is returned in the message body. Management Group 27

28 Clusters Example Response HTTP/ OK Content-Type: application/json Content-Length: 994 "name": "MG1", "description": "", "type": "managementgroup", "id": 0, "uri": "/lhos/managementgroup", "created": "N/A", "modified": "N/A", "SoftwareVersion": [ "name": "GlobalDatabaseVersion", "version": " ", "description": "Global Database Version", "name": "CoordinatingManagerVersion", "version": " ", "description": "Coordinating Manager Version" ], "md5sum": "22c42abfe8adcf510038c6a174f235ed" "supportedfeatures": [ RMCSTOREONCE RMCSTOREONCEVMWARE RMCSTOREONCESQL RMCSTOREONCEORACLE RMCSTOREONCEEXCHANGE RMCSTOREONCEHYPERV RMCSTOREONCEFILEPERSONA ] Clusters are comprised of storage systems and volumes on the storage systems. The following REST API calls describe how to retrieve cluster information from a management group. Read Clusters Collection Overview URI: System>:8081/lhos/clusters Type: clusters Base Type: Collection HTTP Method: GET Authorization Group: Management Groups = Read-Only Use HTTP GET on /lhos/clusters to request one or more cluster objects. Cluster Collection Object Model Field JSON Type API Type name Cluster Collection description Collection of Cluster objects uri URI /lhos/clusters 28 Supported API calls

29 type cluster total Number Uint32 <dynamic> members Array cluster[] <dynamic> NOTE: See Cluster Entity Object Model (page 31) for the Cluster entity data model. HTTP Request Request s Authorization Auth Accept-Language Accept Accept-Charset Valid authorization token obtained from POST /lhos/credentials call. Desired, acceptable human language for response. Example: en_us. If the desired language is not recognized, US English is the default (en_us). Content-Types that are acceptable for the response. Only application/json is supported. The acceptable character sets for return data. Example: UTF-8. Required? Yes. Either an Authorization or Auth is required. Supported query parameters fields expand-links name Message Body t applicable no user input required. The message body of a GET request is ignored or discarded if sent. HTTP Response Success Codes HTTP Status Codes 200 OK Success, the Cluster collection is included in the message body Clusters 29

30 Error Codes HTTP Status Code 401 Unauthorized 500 Internal Server Error Missing, invalid or expired Authorization token used. Establish a new token (POST /lhos/credentials), and retry the operation. Unexpected internal error encountered. See the error object returned in the response body and refer to Error object messageids (page 125) for specific details. Response s Content-Type Content-Length Date X-API-Version X_HP-CHRP-Service-Version Cache-Control Value(s) application/json <dynamic number> Origin date of response. x.x.4 no-cache Message Body The Cluster collection object model or an Error object model is returned in the message body. Example Response HTTP/ OK Server: :8081 Content-Type: application/json Content-Length: 1531 "name": "Clusters Collection", "description": "Collection of Cluster objects", "type": "cluster", "uri": "/lhos/clusters", "total": 1, "members": [ "name": "cl", "description": "", "type": "cluster", "id": 21, "uri": "/lhos/clusters/21", "modified": "N/A", "modulecount": 1, "storagemoduleipaddresses": [ " " ], "virtualipaddresses": 30 Supported API calls

31 "ipv4address": " ", "ipv4netmask": " " ], "virtualipenabled": true, "spaceavailable": , "spacetotal": , "volumecreationspace": [ "replicationlevel": 1, "availablespace": ], "supportedfeatures": [ "" ], "adaptiveoptimizationcapable": false, "volumes": "name": "volumes", "type": "volume", "uri": "/lhos/volumes?clustername=cl", "resource": null ] Read Cluster Entity Overview URI: System>:8081/lhos/clusters/<resource id> Type: cluster Base Type: Entity HTTP Method: GET Authorization Group: Management Groups = Read-Only Use HTTP GET on /lhos/clusters/<resource id> to request a single Cluster Entity matching the resource identifier. Cluster Entity Object Model Field JSON Type API Type name Name. description. type cluster. id Number Uint64 Unique ID of the resource. Clusters 31

32 uri URI Path to the cluster resource. created DateTime ISO 8601 t available. modified DateTime ISO 8601 t available. modulecount Number Uint Number of storage modules belonging to the cluster. storagemoduleipaddresses Array [] List of IP addresses for each store in the cluster. virtualipaddresses Array VirtualIPAddress[] List of virtual IP addresses. See VirtualIPAddress definition for more information. virtualipenabled Indicates if the virtual IP address is enabled. spaceavailable Number Uint64 Available space in bytes for the cluster. spacetotal Number Uint64 Total space in bytes for the cluster. volumecreationspace Array AvailableSpaceRecord [] List of available space in bytes that is available at each of the available replication levels. supportedfeatures Array [] List of licensed features supported for the cluster. adaptiveoptimizationcapable Indicates if the cluster supports adaptive optimization. volumes Object LinkObject LinkObject to a volume collection owned by the cluster. VirtualIPAddress Object Model Field JSON Type API Type ipv4address IPv4 formatted IP address. ipv4netmask IPv4 formatted netmask. AvailableSpaceRecord Object Model Field JSON Type API Type replicationlevel Number Uint32 Number of copies. availablespace Number Uint64 Available space in bytes using the accompanying replication Level. 32 Supported API calls

33 HTTP Request Request s Authorization Auth Accept-Language Accept Accept-Charset Valid authorization token obtained from POST /lhos/credentials call. Desired, acceptable human language for response. Example: en_us. If the desired language is not recognized, US English is the default (en_us). Content Types that are acceptable for the response. Only application/json is supported. The acceptable character sets for return data. Example: UTF-8. Required? Yes. Either an Authorization or Auth is required. Supported query parameters fields expand-links Message Body t applicable no user input required. The message body of a GET request is ignored or discarded if sent. HTTP Response Success Codes HTTP Status Codes 200 OK Success, the cluster object is included in the message body Error Codes HTTP Status Code 400 Bad Request 401 Unauthorized 500 Internal Server Error A non-numeric value was used for the resource identifier. Missing, invalid or expired Authorization token used. Establish a new token (POST /lhos/credentials), and retry the operation. Unexpected internal error encountered. See the error object returned in the response body and refer to Error object messageids (page 125) for specific details. Response s Content-Type Content-Length Date Value(s) application/json <dynamic number> Origin date of response Clusters 33

34 X-API-Version X_HP-CHRP-Service-Version Cache-Control x.x.4 no-cache Message Body The Cluster Entity object model or an Error object model is returned in the message body. Example Response HTTP/ OK Content-Type: application/json Content-Length: 994 "name": "cl", "description": "", "type": "cluster", "id": 21, "uri": "/lhos/clusters/21", "created": "N/A", "modified": "N/A", "modulecount": 1, "storagemoduleipaddresses": [ " " ], "virtualipaddresses": [ "ipv4address": " ", "ipv4netmask": " " ], "virtualipenabled": true, "spaceavailable": , "spacetotal": , "volumecreationspace": [ "replicationlevel": 1, "availablespace": ], "supportedfeatures": [ "" ], "adaptiveoptimizationcapable": false, "volumes": "name": "volumes", "type": "volume", "uri": "/lhos/volumes?clustername=cl", "resource": null 34 Supported API calls

35 Create Cluster Entity Overview API Version: 1.1 URI: System>:8081/lhos/clusters Type: clusters Base Type: Collection HTTP Method: POST Authorization Group: Management Groups = Full Use HTTP POST on /lhos/clusters to create a new Cluster resource. Cluster Creation Object Model Field JSON Type API Type Required? Default Value Name Name of the cluster Yes N/A for the cluster storagemoduleipaddresses Array Array of IP addresses of the storage systems that will be included in the cluster. Yes N/A virtualipaddresses Array virtualipaddress[] List of virtualipaddress objects (see virtualipaddress Object Model (page 35)) that represent a Virtual IP Address (VIP) for the cluster. N/A virtualipaddress Object Model Field JSON Type API Type ipv4address Virtual IP address ipv4netmask Subnet Mask HTTP Request Request s Authorization Auth Accept-Language Valid authorization token obtained from POST /lhos/credentials call. Desired, acceptable human language for response. Example: en_us. If the desired Required? Yes. Either an Authorization or Auth is required. Clusters 35

36 Accept Accept-Charset language is not recognized, US English is the default (en_us). Content-Types that are acceptable for the response. Only application/json supported. The acceptable character sets for return data. Example: UTF-8. Supported query parameters ne. Message Body The message body of the POST request should contain a full or partial representation of the XXcluster. Example Request POST /lhos/clusters/72 Host: :8081 Authorization: 95ece7b3-a d-a0e9-ff2c7048f5e9 "name": "NewCluster", "description": "Cluster created via REST API.", "storagemoduleipaddresses": [ " ", " ", ], "virtualipaddresses": [ ] HTTP Response Success Codes "ipv4address": " ", "ipv4netmask": " " Success 201 Created Cluster resource successfully created. Error Codes HTTP Status Code 400 Bad Request Invalid contents detected in request message body. 36 Supported API calls

37 401 Unauthorized 500 Internal Server Error Missing, invalid or expired Authorization token used. Establish a new token (POST /lhos /credentials), and retry the operation. Unexpected internal error encountered, see error object returned in response body and see Error object messageids (page 125) for specific details. Response s Content-Type Content-Length Date X-API-Version X_HP-CHRP-Service-Version Cache-Control Location Value(s) application/json <dynamic number> Origin date of response. x.x.4 no-cache URI to new resource Message Body The Cluster object model of the Cluster that was created. In the case of a 500 Internal Server error or 401 Unauthorized (due to insufficient permissions), an Error object model is returned. See the GET /lhos/clusters/<id> section for the Cluster object model. Example Response HTTP/ Created Date: T16:43: Z Content-Type: application/json Content-Length: 1309 X-API-Version: 1.1 X_HP-CHRP-Service-Version:.4 Cache-Control: no-cache Location: /lhos/clusters/72 "name": "NewCluster", "description": "Cluster created via REST API.", "type": "cluster", "id": 72, "uri": "/lhos/clusters/72", "created": "N/A", "modified": "N/A", "modulecount": 3, "storagemoduleipaddresses": [ ], " ", " ", " " "virtualipaddresses": [ Clusters 37