Dell EMC PowerStore REST API Developers Guide 1.x December 2020 Rev.
Notes, cautions, and warnings NOTE: A NOTE indicates important information that helps you make better use of your product. CAUTION: A CAUTION indicates either potential damage to hardware or loss of data and tells you how to avoid the problem. WARNING: A WARNING indicates a potential for property damage, personal injury, or death. © 2020 Dell Inc. or its subsidiaries. All rights reserved. Dell, EMC, and other trademarks are trademarks of Dell Inc. or its subsidiaries.
Contents Additional Resources................................................................................................................................................................ 5 Chapter 1: Overview...................................................................................................................... 6 The PowerStore Management REST API......................................................................................................................
Deleting a resource instance.......................................................................................................................................... 38 Performing an instance-level resource-specific action............................................................................................38 Performing a class-level action......................................................................................................................................
Additional Resources As part of an improvement effort, revisions of the software and hardware are periodically released. Some functions that are described in this document are not supported by all versions of the software or hardware currently in use. The product release notes provide the most up-to-date information about product features. Contact your technical support professional if a product does not function properly or does not function as described in this document.
1 Overview Topics: • • • The PowerStore Management REST API Resource-oriented architecture and REST JSON data exchange format The PowerStore Management REST API The PowerStore Management REST API is a set of resources (objects), operations, and attributes that provide interactive, scripted, and programmatic management control of the PowerStore cluster. Here are some examples of what you can do with the REST API: ● ● ● ● ● ● Provision new cluster components, such as appliances and volumes.
instance. The REST API also uses POST for a limited set of other operations to implement resource-specific actions. Thus, an application can interact with a resource by knowing the URI pattern, resource identifier, and action required. ● Communication between the client and server occurs through HTTP requests and responses. In the PowerStore Management REST API, requests and responses represent resource data using JavaScript Object Notation (JSON).
2 REST request components Topics: • • • • HTTP request headers URI patterns Request parameters REST requests HTTP request headers The following table describes the HTTP request headers used by the PowerStore Management REST API. The API uses these headers in standard ways. HTTP header Value Description Accept: application/json Format of the body content desired in the response. All requests use Accept: application/json, which is the default and only value accepted.
URI patterns Basic URI patterns The following table describes the basic URI patterns that the PowerStore Management REST API supports: Table 1. Basic patterns in the REST API URI pattern HTTP Operations Description Collection type resource URI GET Retrieves a list of instances for the specified resource type. POST Creates a new instance of the specified resource type, using data specified in the request body, if allowed. Instance resource URI GET Retrieves the specified resource instance.
Related references HTTP request headers on page 8 Request parameters on page 10 REST requests on page 12 Request parameters The PowerStore Management REST API supports the following request parameters: Request parameter Applicable request types Description select Collection and instance queries Specifies a comma-separated list of attributes to return in a response. If you do not use this parameter, a query returns the id attribute only.
after which no new storage provisioning will be allowed." }, { "id":"2d3cc48d-0296-4d15-afb9-252061cf7df9", "severity":"Minor", "description_l10n":"Bus 0 enclosure 0 LCCA is initializing." }, { "id":"37583ff1-b0fe-41f2-9b3d-e5e5d2e5e525", "severity":"Info", "description_l10n":"The remote system volume discovery or refresh has failed." }, . . .
{ ] }, { "id":"2d3cc48d-0296-4d15-afb9-252061cf7df9", "severity":"Minor" Using the is_async request parameter The following asynchronous request deletes a local_user instance. The request returns the job ID: Request Response DELETE https://1.2.3.
3 REST responses Topics: • • • • • • • • • Response components HTTP response headers HTTP status codes JSON collection response body JSON instance response body JSON create response body Response with no body JSON job response body Error response Response components Each response to a REST API request consists of a response header, HTTP status code (in the response header), and JSON response body, if applicable: ● The response header contains metadata about the response being sent.
Table 2. HTTP response headers in the REST API (continued) HTTP header Description named DELL-EMC-TOKEN. Use the value of token from the response header obtained from the GET call as a Header value in the subsequent calls for this session. Content-Range Paginated responses contain this header, which indicates how many instances were successful and how many were returned.
Table 3. HTTP status codes in the REST API (continued) Status code Name Applies to Description The role of the authenticated user does not have the privilege required to perform the requested operation. 404 Not Found All requests Resource does not exist. This can be caused by an invalid ID in an instance URI. 405 Method Not Allowed All requests Specified resource does not support the request's operation. For example, requesting a DELETE on a hardware resource can cause this error.
Request Response GET https://1.2.3.4/api/rest/event?select=id,severity List of all instances in the specified collection that meet the request criteria. The response includes attribute values as a set of name:value pairs for each returned instance: [ { }, { ] }, . . .
Request Request body POST https://1.2.3.4/api/rest/local_user { } Response { } "name": "User1", "password": "myPassword", "role_id": "1" "id": "4" Response with no body A response with no body occurs in response to a DELETE request that results in a 204 No Content status code. In this circumstance, response headers are returned with the empty response body. A response with no body also occurs in response to an action POST request that does not have output data.
Request Request body Response POST https://1.2.3.4/api/rest/volume_group/ 257f2597-7c11-46c9-8941-3793e1cb2baa/refresh { "from_object_id": "22f3bf53-ad83-4466-8e5e-5b0fade650da" } { "messages":[ { "code": "0xE0A070020007", "severity": "Error", "message_l10n": "Family mismatch for snapshot target 257f2597-7c11-46c9-8941-3793e1cb2baa and source 22f3bf53ad83-4466-8e5e-5b0fade650da.
4 JSON encodings Topics: • • JSON base value encodings JSON list encoding JSON base value encodings The following table shows the JSON encodings for each base type: NOTE: A property that has no value appears as the type null. Type name JSON definition Format after "": Example Notes short type: integer "drive_count":600 N/A "answer": 42 N/A "size": 123456789 N/A "progress": 99.9 N/A "throughput": 123456.
Type name JSON definition Format after "": Example date-time type: string yyyy-mmddThh:mm:ss[.sss]Z "updated": As defined by full-date "2015-07-14T18:21:3 RFC3339. All times are 2.621Z" expressed in UTC time. The optional [.sss] contains fractional milliseconds. "password":"wordpas This is a string in the API and s" may be presented differently by a client (to hide typed input). This is handled differently on the server (for example, the values are not logged).
Examples An empty list "addresses":[ ] A list with one value "addresses":["1.2.3.4"] A list with three values "addresses":["1.2.3.4","5.6.7.8","4.3.2.
5 Managing a REST API session Topics: • • • Connecting and authenticating Obtaining login session information Logging out of the REST API session Connecting and authenticating All requests to the REST API must be authenticated. The REST API uses the standard HTTP Basic access authentication mechanism to authenticate REST requests. The same users are valid for REST or GUI access.
Attribute Description is_password_change_r equired Indicates whether the password must be changed in order to use this session created for the built-in admin account. The values are: ● true - Password must be changed. ● false - Password does not need to be changed. For information about changing the password for a local user, see the Help topic for the local_user resource type in the Reference content on page 43. is_built_in_user Indicates whether the user is a system-defined user, such as admin.
6 Querying a resource Topics: • • • • • • • Pagination Retrieving data for multiple occurrences in a collection Retrieving data for a specified resource instance Specifying the attributes to return in a query response Filtering response data Sorting response data Including data from a related resource type in a query Pagination When you query a resource, the server limits the size of the returned collection by default.
Retrieving data for multiple occurrences in a collection To retrieve data for multiple occurrences of a resource type, use the following request components: Headers Operation URI pattern Accept: application/json Authorization: GET /api/rest/ where is the resource type for the collection you want to return. For additional functionality, such as filtering instances, you can append one or more request parameters to the URI. Body Empty.
}, { "description_l10n":"Bus 0 enclosure 0 LCCA is initializing." "id":"37583ff1-b0fe-41f2-9b3d-e5e5d2e5e525", "severity":"Info", "description_l10n":"The remote system volume discovery or refresh has failed.
Specifying the attributes to return in a query response Use the select request parameter in a collection query to specify the set of attributes to return in a response. If you do not use this parameter, a query will return the id attribute only. When you use the select request parameter, you can refer to attributes in a related resource type, as described in the Syntax section below. Syntax As the first parameter on the request URI: ?select=,,...
Filtering response data Use one or more filter expressions in a request parameter to specify matching criteria for a list of resources returned by a collection query. A filter expression works like an SQL WHERE clause. You specify a filter expression composed of boolean predicates, and the expression is applied against the attribute values of the requested resource type. Only those instances that cause the filter expression to evaluate to true are returned in the query response.
Comparator Description Applicable data types Example lte Less than or equal. All ? modify_time=lte.2018-05-07T17: 56:28.859+00:00 Returns true when the expression on the left of =eq is less than or equal to the expression on the right. neq Not equal. True if the value of modify_time is 2018-05-07T17:56:28.859+00:00 or earlier. All Returns true when the expression on the left of =eq is not equal to the expression on the right. ilike Case-insensitive substring match.
Comparator Description Applicable data types Example True if either the value of size is greater than 50 MB or the value of performance_policy is High or both. Sorting response data Use the order request parameter to specify sort criteria for one attribute in a list of resources returned by a collection query. The order parameter works like an SQL Order By clause. You can specify one of these sort orders for the attribute: ● asc: (Default) Sorts the response data in ascending order.
] } "state": "Cleared" Including data from a related resource type in a query You can extend the scope of a collection query to retrieve data from a related resource type. The REST model describes two kinds of relations: ● A referenced resource type ● An embedded resource type Referenced resource types A referenced resource type describes an instance of a linked object type.
Returning only the id parameter for the appliance related to each node Headers Request Response body Accept: application/json Authorization: https://1.2.3.
Response body [ ] { } "id":"A1", "name":"H0112-appliance-1", "nodes": [ { "id":"N1" }, { "id":"N2" } ] Embedded resource types An embedded resource type describes an instance of nested objects. This resource type is declared in the REST model as a reference to an object or an array of objects with a special note in its description field. ● Embedded resources cannot be queried without a parent object. ● Embedded resources always return all fields.
}, { ] 34 } "id":"9d102db7-048d-4d24-85c2-28c7a5fc91ee", "protection_data": { "family_id": "9d102db7-048d-4d24-85c2-28c7a5fc91ee", "parent_id": null, "source_id": null, "creator_type": "User", "copy_signature": null, "source_timestamp": null, "creator_type_l10n": "User", "is_app_consistent": null, "created_by_rule_id": null, "created_by_rule_name": null, "expiration_timestamp": null } "id":"f0480b0f-cc6f-431b-9e18-e4b39b2b13e1", "protection_data": { "family_id": "f0480b0f-cc6f-431b-9e18-e4b39b2b13e1", "
7 Creating other types of requests Topics: • • • • • • Creating a resource instance Modifying a resource instance Deleting a resource instance Performing an instance-level resource-specific action Performing a class-level action Working with asynchronous requests Creating a resource instance To create a resource instance, use the following request components: Headers Operation URI pattern Accept: application/json Content-Type: application/json Authorization: POST /api/rest/
Request body { } Response body { } "name": "User1", "password": "myPassword", "role_id": "1" "id": "4" Modifying a resource instance To modify a resource instance, use the following request components: Headers Operation URI pattern Accept: application/json Content-Type: application/json Authorization: PATCH /api/rest// where: ● is the resource type of the instance you want to modify. ● is the unique identifier of the instance you want to modify.
Headers Request Request body Accept: application/json Content-Type: application/json Authorization: PATCH https://1.2.3.4/api/rest/volume_group/ad09bfa8-f8d8-41b5-96a9c15c9ebdf214 { } Response body "name":"Storage resources for Marketing", "description":"Volumes for storing competitive analaysis information" Empty.
Deleting a resource instance To delete a resource instance, use the following request components: Headers Accept: application/json Authorization: If a resource type has request arguments for the DELETE operation, you must also use the following header: Content-Type: application/json Operation URI pattern DELETE /api/rest// where: ● is the resource type of the instance you want to delete. ● is the unique identifier of the instance you want to delete.
Headers For operations without request arguments: Accept: application/json Authorization: For operations with request arguments: Accept: application/json Content-Type: application/json Authorization: Operation URI pattern POST /api/rest/// where: ● is the resource type of the instance for which you want to perform an action. ● is the unique identifier of the instance for which you want to perform an action.
Request body (Optional) { } Response body { } "description": "DB copy before application upgrade" "id": "57cdb822-490e-4755-b8b3-99bb779b1472" Performing a class-level action Some resource types have operations that let you perform class-level actions. For example, exchanging SSL certificates with another PowerStore appliance.
If the request does not succeed, the server returns a 4xx or 5xx HTTP status code in the response header and a message entity in the response body. Exchanging SSL certificates The following request exchanges SSL certificates with another PowerStore appliance: Headers Request Request body Accept: application/json Content-Type: application/json Authorization: POST /api/rest/x509_certificate/exchange { } Response body "service": "Management_HTTP", "address": "10.244.53.
Creating an asynchronous request The following example uses the is_async=true request parameter on a request to modify an volume_group instance. Headers Request Request body Accept: application/json Content-Type: application/json Authorization: PATCH https://1.2.3.
8 Reference content This section describes the resource types, methods, and attributes in the PowerStore Management REST API, along with other API information such as datatypes and enumerations. In addition to the PowerStore REST API Reference Guide on https://www.dell.com/support, reference materials are also available on the appliance in several formats: ● Swagger UI—https:///swaggerui ● JSON—https:///api/rest/openapi.
