Contents

Dell EMC VMAX 100K V8.3.0 Storage REST API Concepts And Programmer's Guide PDF

1 of 22
1 of 22

Summary of Content for Dell EMC VMAX 100K V8.3.0 Storage REST API Concepts And Programmer's Guide PDF

EMC Unisphere for VMAX Version 8.3.0

REST API Concepts and Programmer's Guide

Copyright 2014-2016 EMC Corporation. All rights reserved. Published in the USA.

Published September 23, 2016

EMC believes the information in this publication is accurate as of its publication date. The information is subject to change without notice.

The information in this publication is provided as is. EMC Corporation makes no representations or warranties of any kind with respect to the information in this publication, and specifically disclaims implied warranties of merchantability or fitness for a particular purpose. Use, copying, and distribution of any EMC software described in this publication requires an applicable software license.

EMC, EMC, and the EMC logo are registered trademarks or trademarks of EMC Corporation in the United States and other countries. All other trademarks used herein are the property of their respective owners.

For the most up-to-date regulatory document for your product line, go to EMC Online Support (https://support.emc.com).

EMC Corporation Hopkinton, Massachusetts 01748-9103 1-508-435-1000 In North America 1-866-464-7381 www.EMC.com

2 EMC Unisphere for VMAX 8.3.0 REST API Concepts and Programmer's Guide

5

PREFACE 7

Introduction 9

Product overview...........................................................................................10 REST model................................................................................................... 10 Unisphere for VMAX REST Client.................................................................... 10

Documentation 13

Downloading documentation........................................................................ 14 Transport protocol.........................................................................................14 Product version and compatibility................................................................. 14

Backward compatibility....................................................................14 Client/Server compatibility...............................................................14

Making the JSON root element backwards compatible...................................15

Iterators 17

How iterators are used in REST API................................................................ 18 Sample iterator methods and typical use case...............................................18

Sample 19

Setting up user authentication...................................................................... 20 Client authentication.....................................................................................20 Sample client request and response examples..............................................21

Tables

Chapter 1

Chapter 2

Chapter 3

Chapter 4

CONTENTS

EMC Unisphere for VMAX 8.3.0 REST API Concepts and Programmer's Guide 3

CONTENTS

4 EMC Unisphere for VMAX 8.3.0 REST API Concepts and Programmer's Guide

REST resource methods................................................................................................. 101

TABLES

EMC Unisphere for VMAX 8.3.0 REST API Concepts and Programmer's Guide 5

TABLES

6 EMC Unisphere for VMAX 8.3.0 REST API Concepts and Programmer's Guide

PREFACE

As part of an effort to improve its product lines, EMC periodically releases revisions of its software and hardware. Therefore, some functions described in this document might not be supported by all versions of the software or hardware currently in use. The product release notes provide the most up-to-date information on product features.

Contact your EMC technical support professional if a product does not function properly or does not function as described in this document.

Note

This document was accurate at publication time. Go to EMC Online Support (https:// support.emc.com) to ensure that you are using the latest version of this document.

Purpose This document describes how to configure and use EMC Unisphere for VMAX REST API.

Audience This guide is intended for programmers who want to create interfaces, using these API's, in any of the programming environments that support standard REST clients such as web browsers and programming platforms that can issue HTTP requests.

Related documentation The following EMC publications provide additional information:

l EMC Unisphere for VMAX Release Notes

l EMC Unisphere for VMAX Installation Guide

Special notice conventions used in this document EMC uses the following conventions for special notices:

DANGER

Indicates a hazardous situation which, if not avoided, will result in death or serious injury.

WARNING

Indicates a hazardous situation which, if not avoided, could result in death or serious injury.

CAUTION

Indicates a hazardous situation which, if not avoided, could result in minor or moderate injury.

NOTICE

Addresses practices not related to personal injury.

Note

Presents information that is important, but not hazard-related.

PREFACE 7

Typographical conventions EMC uses the following type style conventions in this document:

Bold Used for names of interface elements, such as names of windows, dialog boxes, buttons, fields, tab names, key names, and menu paths (what the user specifically selects or clicks)

Italic Used for full titles of publications referenced in text

Monospace Used for:

l System code

l System output, such as an error message or script

l Pathnames, filenames, prompts, and syntax

l Commands and options

Monospace italic Used for variables

Monospace bold Used for user input

[ ] Square brackets enclose optional values

| Vertical bar indicates alternate selections - the bar means or

{ } Braces enclose content that the user must specify, such as x or y or z

... Ellipses indicate nonessential information omitted from the example

Where to get help EMC support, product, and licensing information can be obtained as follows:

Product information

For documentation, release notes, software updates, or information about EMC products, go to EMC Online Support at https://support.emc.com.

Technical support

Go to EMC Online Support and click Service Center. You will see several options for contacting EMC Technical Support. Note that to open a service request, you must have a valid support agreement. Contact your EMC sales representative for details about obtaining a valid support agreement or with questions about your account.

Your comments Your suggestions will help us continue to improve the accuracy, organization, and overall quality of the user publications. Send your opinions of this document to VMAXContentFeedback@emc.com.

PREFACE

8 EMC Unisphere for VMAX 8.3.0 REST API Concepts and Programmer's Guide

CHAPTER 1

Introduction

This chapter contains the following:

l Product overview...................................................................................................10 l REST model........................................................................................................... 10 l Unisphere for VMAX REST Client............................................................................ 10

Introduction 9

Product overview The EMC Unisphere for VMAX REST (Representational State Transfer) API allows for accessing diagnostic performance data, accessing configuration data, and performing storage provisioning operations for VMAX hardware through robust APIs. These API's can be used in any of the programming environments that support standard REST clients such as web browsers and programming platforms that can issue HTTP requests. The Unisphere for VMAX REST API supports both XML and JavaScript Object Notation (JSON) MIME types.

REST model REST is a manner of building networked software systems that allows merging of documents, data and information services into an ecosystem of named resources.

l Resource - Anything important enough to be referenced as a noun.

l Resource name - Unique identification of the resource.

l Resource representation - Useful information about the current state of resource. Resource representation is what is used to transfer its information to the client using the HTTP protocol.

l Resource link - Link to another representation of the same resource.

l Resource interface - Uniform interface for accessing the resource and manipulating its state.

The following table describes the standard resource methods.

Table 1 REST resource methods

HTTP operation Description Access to Method

PUT Modify resource Administrator

Storage Administrator

GET Retrieve state of resource All roles

POST Create a new resource Administrator

Performance Monitor (for Performance URLs only)

Storage Administrator

DELETE Delete resource Administrator

Storage Administrator

For assigning user roles for each array, refer to Setting up user authentication.

Unisphere for VMAX REST Client

The Unisphere for VMAX REST Client provides both a front-end GUI for the REST API documents and a Unisphere for VMAX-specific REST client based on the WADL file received from the Unisphere for VMAX Host.

Introduction

10 EMC Unisphere for VMAX 8.3.0 REST API Concepts and Programmer's Guide

For more information, reference the Unisphere for VMAX REST Client available on the VMAX Community on ECN: https://community.emc.com/community/products/vmax

Introduction

Unisphere for VMAX REST Client 11

Introduction

12 EMC Unisphere for VMAX 8.3.0 REST API Concepts and Programmer's Guide

CHAPTER 2

Documentation

This chapter contains the following:

l Downloading documentation................................................................................ 14 l Transport protocol.................................................................................................14 l Product version and compatibility......................................................................... 14 l Making the JSON root element backwards compatible...........................................15

Documentation 13

Downloading documentation Clients can download the UNIVMAX REST API documentation (URLs, required parameters, and returned results) as follows:

Before you begin

Prior to downloading REST API documentation, Unisphere for VMAX must be installed and user access roles must be setup (see Setting up user authentication on page 20).

Procedure

1. Point the browser to: https://{UNIVMAX_IP}:{UNIVMAX_PORT}/univmax/ restapi/docs

Where, UNIVMAX_IP is the IP address and UNIVMAX_PORT is the port of the host running Unisphere for VMAX.

2. Copy the zip file (restapi-docs.zip) locally, unzip the file, and navigate to target/docs/ index.html.

3. Open the html file to access the documented resources.

Transport protocol REST API uses the Hypertext Transfer Protocol Secure (HTTPS) version 1.1 as the transport for API requests. For PUT and POST requests, method arguments are passed in the HTTP Request message body. API methods return standard HTTP status codes and result content in the HTTP Response message body.

Unisphere for VMAX REST API supports two media-types:

l application/xml Allows marshalling/un-marshalling using XML

l application/json Allows marshalling/ un-marshalling using JSON

Product version and compatibility The Unisphere REST API is the same version as the Unisphere for VMAX application.

Backward compatibility Since the REST API is a method-based API, the methods will remain backwards compatible with older versions as long as the argument and result types have only optional properties added to newer versions of the API.

If additional properties are required or existing properties require modification, an additional method should be created. Deprecated methods will be maintained to service older clients, and eventually removed. New REST API methods are backwards compatible.

REST API guarantees backwards compatibility for two major releases. For example if the server REST API version is 8.0.x, then it is backward compatible with REST API version 7.6.x or 7.5.x on the client.

Client/Server compatibility If the Unisphere for VMAX REST Client API version is older than the server version, interaction proceeds as designed. If the client REST API version is newer than the server

Documentation

14 EMC Unisphere for VMAX 8.3.0 REST API Concepts and Programmer's Guide

version, the server delivers an HTTP status 400 or HTTP status 404, indicating an illegal request.

Making the JSON root element backwards compatible For prior versions of the Unisphere for VMAX REST API, the JSON root is included in the API request and response. The current version of Unisphere for VMAX REST API does not include the JSON root in the API request and response. To make the server backwards compatible, the property that controls this must be modified as follows:

Procedure

1. Locate the web.xml file at:

<location of Unisphere installation>\jboss\domain \deploy0\smc0ear\smc.war\WEB-INF\web.xml

2. Open the file and set the property com.emc.em.restapi.WrapJsonRoot to True.

3. Save the file and restart the server.

Documentation

Making the JSON root element backwards compatible 15

Example 1 REST API request and response example

The following example shows a REST API request and response with and without the JSON root:

Request:

https://<UnimaxIP:UnimaxPort>/univmax/restapi/provisioning/ symmetrix/000195900063/storagegroup

Where UNIVMAX_IP is the IP address and UNIVMAX_PORT is the port of the host running Unisphere for VMAX.

Response without JSON root (default):

{ "num_of_storage_groups": 64, "storageGroupId": [ "appEng", "appEng2", ], "success": true }

Response with JSON root:

{ "listStorageGroupResult": { "num_of_storage_groups": 64, "storageGroupId": [ "appEng", "appEng2", ], "success": true } }

Documentation

16 EMC Unisphere for VMAX 8.3.0 REST API Concepts and Programmer's Guide

CHAPTER 3

Iterators

This chapter contains the following:

l How iterators are used in REST API........................................................................ 18 l Sample iterator methods and typical use case.......................................................18

Iterators 17

How iterators are used in REST API An iterator is an object that allows you to cycle through the elements in a collection and display each element. Unisphere for VMAX REST API uses iterators to retrieve a collection of performance data only when the API interface defines that there are unbounded instances in the result. For example, the method to retrieve array metrics takes an ArrayParamType argument and returns an unbounded number of ArrayResultType results.

See Downloading documentation on page 14 for instructions on how to access the REST resources. From the EMC Unisphere for VMAX RESTAPI Home page, select Performance, then any /metrics resource, and under Response Body select Iterator to view how the iterator cycles through the elements in a collection results.

The Unisphere for VMAX REST API also uses iterators to control resource consumption on the server when multiple clients are querying for large sets of data. Each iterator has a unique ID and provides two ways to control excess server consumption: maximum page size, and an expiration time for the iterator instance. The page size and expiration time are dependent on server load and resource availability. In addition, Unisphere for VMAX imposes limits on the number of concurrent requests it will accept. See Sample iterator methods and typical use case.

Sample iterator methods and typical use case The infrastructure provides three method endpoints for clients to interact with the iterators.

l Get iterator info

l Get iterator page

l Delete iterator

A typical use case is as follows:

Note

If a client becomes unresponsive, or disconnects from the Unisphere for VMAX server, the iterator expires, based on a pre-configured timeout. When the iterator expires, server resources are released. If the iterator expires before the client has finished paging over all the results, the client must reissue the request.

1. The client invokes a REST API method that returns an iterator.

2. The client pages over the results of an existing iterator until all results are retrieved by issuing Get common /Iterator/{iteratorld}/page.

3. If the iterator has not expired, the client deletes the iterator by issuing Delete common/Iterator/{iteratorld}.

Iterators

18 EMC Unisphere for VMAX 8.3.0 REST API Concepts and Programmer's Guide

CHAPTER 4

Sample

This chapter contains the following:

l Setting up user authentication.............................................................................. 20 l Client authentication.............................................................................................20 l Sample client request and response examples......................................................21

Sample 19

Setting up user authentication Prior to using the Unisphere for VMAX REST API, user authorization must be assigned for each VMAX array the user is permitted to access.

Procedure

1. Log into Unisphere for VMAX.

2. From the system selector, select All Symmetrix.

3. Select Home > Administration > Security > Authorized Users and Groups to open the Authorized Users and Groups list view.

4. Click Add to open the Add Authorization Rule dialog box.

5. Select the Roles tab and create a user login profile for each VMAX array to be accessed by the user, and assign them to any of the following roles:

l Users that are allowed VMAX access:

n Administrator Can initiate GET, POST, PUT, and DELETE methods.

n Storage Administrator Can initiate GET, POST, PUT, and DELETE methods.

n Performance Monitor Can initiate GET and POST (for Performance URLS only) methods.

n Monitor Can initiate GET methods.

n Auditor Can initiate GET methods.

n Security Administrator Can initiate GET methods.

l Users that are not allowed VMAX access:

n None

6. Click OK.

Client authentication REST API uses HTTP Basic Access Authentication to authenticate API clients, described in RFC 2617. HTTP Basic Access Authentication is simple, since it does not require cookies, session handling, or login pages. Instead, HTTP Basic Access Authentication uses static headers, requiring no handshakes.

Users of the REST API are assigned user credentials for associated VMAX arrays within Unisphere for VMAX. A username and password is supplied with every request to REST API in the Authorization header, as specified in RFC 2617. Every request to REST API is authenticated and authorized.

Note

If X509 certificate-based client authentication is enabled, the username/password REST basic authentication credential is ignored by Unisphere. However, to meet REST standards basic authentication requirement, REST clients must provide non-empty username/password dummy credential.

Sample

20 EMC Unisphere for VMAX 8.3.0 REST API Concepts and Programmer's Guide

Sample client request and response examples For sample client request and response examples, refer to the REST API documentation. Downloading documentation on page 14 describes how to obtain the documentation.

Sample

Sample client request and response examples 21

Sample

22 EMC Uni

Manualsnet FAQs

If you want to find out how the EMC Dell works, you can view and download the Dell EMC VMAX 100K V8.3.0 Storage REST API Concepts And Programmer's Guide on the Manualsnet website.

Yes, we have the REST API Concepts And Programmer's Guide for Dell EMC as well as other Dell manuals. All you need to do is to use our search bar and find the user manual that you are looking for.

The REST API Concepts And Programmer's Guide should include all the details that are needed to use a Dell EMC. Full manuals and user guide PDFs can be downloaded from Manualsnet.com.

The best way to navigate the Dell EMC VMAX 100K V8.3.0 Storage REST API Concepts And Programmer's Guide is by checking the Table of Contents at the top of the page where available. This allows you to navigate a manual by jumping to the section you are looking for.

This Dell EMC VMAX 100K V8.3.0 Storage REST API Concepts And Programmer's Guide consists of sections like Table of Contents, to name a few. For easier navigation, use the Table of Contents in the upper left corner.

You can download Dell EMC VMAX 100K V8.3.0 Storage REST API Concepts And Programmer's Guide free of charge simply by clicking the “download” button in the upper right corner of any manuals page. This feature allows you to download any manual in a couple of seconds and is generally in PDF format. You can also save a manual for later by adding it to your saved documents in the user profile.

To be able to print Dell EMC VMAX 100K V8.3.0 Storage REST API Concepts And Programmer's Guide, simply download the document to your computer. Once downloaded, open the PDF file and print the Dell EMC VMAX 100K V8.3.0 Storage REST API Concepts And Programmer's Guide as you would any other document. This can usually be achieved by clicking on “File” and then “Print” from the menu bar.