Transcription
WHITE PAPERTitan T5000Unisphere ManagementREST API Programmer's Guide Dell TechnologiesOverlandTandberg.com
Dell EMC Unity FamilyUnisphere Management REST API Programmer'sGuide5.1Regulatory Model: P/N 302-002-579June 2021Rev. 05
Notes, cautions, and warningsNOTE: 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 avoidthe problem.WARNING: A WARNING indicates a potential for property damage, personal injury, or death. 2016 - 2021 Dell Inc. or its subsidiaries. All rights reserved. Dell, EMC, and other trademarks are trademarks of Dell Inc. or its subsidiaries.Other trademarks may be trademarks of their respective owners.
ContentsAdditional resources. 5Chapter 1: Welcome. 6The Unisphere Management REST API. 6Examples in this guide. 6Chapter 2: REST API overview.7Resource-oriented architecture and REST. 7JSON data exchange format. 7Chapter 3: JSON request components.9HTTP request headers. 9Request parameters. 10URI patterns. 14Request body. 18Chapter 4: JSON response components. 19HTTP response headers. 19JSON response body.20HTTP status codes. 21Collection resource. 22Instance resource. 24Minimal instance resource.24Empty response body.25Job resource instance. 25Message entity.26Chapter 5: JSON encodings.28JSON base value encodings. 28JSON list encoding. 29Chapter 6: Preparing to make a request. 31Connecting and authenticating.31Retrieving basic system information.33Chapter 7: Querying a resource. 34Retrieving data for multiple occurrences in a collection.34Retrieving data for a specified resource instance.36Omitting metadata from responses. 38Specifying the attributes to return in a query response.39Paginating response data.41Filtering response data.45Sorting response data. 50Aggregating response data. 52Contents3
Defining new attributes from existing attributes. 54Extending queries to include related data.60Localizing response text. 63Chapter 8: Creating other types of requests. 66Creating a resource instance. 66Modifying a resource instance. 67Deleting a resource instance. 69Performing a class-level resource-specific action. 71Performing an instance-level resource-specific action.72Creating an aggregated management request.75Working with asynchronous requests.77Chapter 9: Downloading and uploading files. 80Downloading and uploading NAS server configuration files. 80Downloading and uploading x.509 certificates. 84Downloading configuration capture files. 86Downloading service information files.87Downloading import session report files.88Downloading Data at Rest Encryption files.88Uploading upgrade candidates and language packs. 91Uploading license files. 92Chapter 10: Perl example.94Example of creating multiple standalone LUNs. 944Contents
PrefaceAs part of an improvement effort, revisions of the software and hardware are periodically released. Therefore, some functionsdescribed in this document might not be supported by all versions of the software or hardware currently in use. The productrelease notes provide the most up-to-date information on product features. Contact your technical support professional if aproduct does not function properly or does not function as described in this document.Where to get helpSupport, product, and licensing information can be obtained as described below.Product informationFor product and feature documentation or release notes, go to Unity Technical Documentation at: dell.com/unitydocs.TroubleshootingFor information about products, software updates, licensing, and service, go to Support (registration required) at: dell.com/support. After logging in, locate the appropriate product page.Additional resources5
1WelcomeTopics: The Unisphere Management REST APIExamples in this guideThe Unisphere Management REST APIThe Unisphere Management REST API is a set of objects (resources), operations, and attributes that let you interact withUnisphere Management functionality through web browsers and application programs. You can use the REST API to do all of thefollowing: Configure system settings for the storage system. Manage the connections to remote systems, including manage host configurations, iSCSI initiators, and iSCSI CHAPaccounts. Configure network communication, including manage NAS Servers and set up iSNS for iSCSI storage. Manage storage, including configure storage pools and manage file systems, iSCSI, VMware, and Hyper-V storage resources. Protect data, including manage snapshots and replication sessions. Manage events and alerts. Service the system, including change the service password, manage EMC Secure Remote Support (ESRS) settings, andbrowse service contract and technical advisory information.For more information about Unisphere Management REST API functionality, see the Unisphere Management REST APIReference Guide, which is available from the storage system at https:// ip /apidocs/index.html and is also availableon the support website.The Unisphere Management API uses a Representational State Transfer (REST) architecture style to expose data. REST is acommon approach in today's IT management products and a frequent choice for many web-based APIs. Using a REST APIprovides the following advantages: Presents a single, consistent interface to the Unisphere Management functionality. Requires no additional tools, other than standard web browsers or command-line HTTP tools, such as wGET and cURL. Forcomplex interactions, clients can use any procedural programming language, such as C or Java, or scripting language, suchas Perl or Python, to make calls to the REST API. Uses well known HTTP conventions in a standard manner to interact with the storage system. Is easy to transport in the network. REST API traffic looks and acts like standard HTTP network traffic, and requires nospecial ports open in the firewall or special settings in the switches.Examples in this guideMost of the examples in this guide are examples in which the REST API is accessed through a browser plugin. To see an exampleof using the REST API with a Perl script, see Example of creating multiple standalone LUNs.NOTE: The attributes in the example response text may differ from the response text you receive when running the samerequest.6Welcome
2REST API overviewTopics: Resource-oriented architecture and RESTJSON data exchange formatResource-oriented architecture and RESTREST is a client-server architectural style that uses the HTTP protocol in a simple, effective, way. REST is based on thefollowing principles: Application state and functionality are organized into resources. Resources represent physical things, such as a specificStorage Processor (SP); logical things, such as a specific alert; or collections of entities, such as the physical disks in thestorage system. Each resource has a unique Universal Resource Identifier (URI), and each resource instance has a unique ID. For example,you can identify the alert collection with this URI: /api/types/alert/instances. And you can identify the alertinstance that has an ID of 201 with this URI: /api/instances/alert/201. Resources share a uniform interface between the client and server through standard HTTP protocol operations. TheUnisphere Management API uses the HTTP GET operation to retrieve data about a resource collection or resource instance,POST to create or modify a resource instance, and DELETE to delete a resource instance. (The API also uses POST for alimited set of other operations to implement resource-specific actions ) Thus, an application can interact with a resource byknowing the URI pattern, resource identifier, and action required. Communication between the client and server occurs through HTTP requests and responses. In the Unisphere ManagementAPI, requests and responses represent resource data using JavaScript Object Notation (JSON). Each request is stateless, which means that the server does not store application state information. Instead, client requestscontain all the information needed to service the request. Resources in a REST API are self-documenting. A response from the server contains information about the requestedresource in the form of attribute names and values. Some responses also contain HTML links that the user can use toretrieve additional information about the resource.Related conceptsJSON data exchange formatJSON data exchange formatJavaScript Object Notation (JSON) is a text-based, platform-independent data-exchange format that is easy for humans andmachines to read and write. It consists of two structures: A set of name:value pairs enclosed by curly brackets. The pairs may be metadata about the request, such as the time of therequest, or they may be data about a resource. A list of values enclosed by square brackets. This structure is used when the value in a name:value pair is an array.The value in a name can be a simple value, such as a string or a number, or it can be either of the structures above (a list ofname:value pairs in curly brackets, or a list of values in square brackets).The following example shows part of a response body for a GET dnsServer collection request in JSON format. In this content,the value for the addresses attribute is a list structure:"content": {"origin": 1,"addresses": ["10.254.177.14","10.255.134.14"],REST API overview7
}]}}"id": "0"For more information about JSON, see json.org.Related conceptsResource-oriented architecture and REST8REST API overview
3JSON request componentsTopics: HTTP request headersRequest parametersURI patternsRequest bodyHTTP request headersThe following table describes the HTTP request headers that are used by the Unisphere Management REST API. The API usesthese headers in standard ways.HTTP ion n.n Format and version of the body contentdesired in the response.where n.n is the version number forthe desired response.All requests use Accept:application/json, which is thedefault and only value accepted. If theAccept header is not specified, thesystem defaults to the current version.If the client requests a version thatthe server does not support, the serverreturns an error. If the client requestsmultiple versions, the server returnsthe latest supported version that wasrequested.Accept-language:Locale nameLocalization language for error responsemessages, events, alerts, and otherlocalizable query results.Valid values are: -CN:GermanEnglish (default)Latin American SpanishFrenchJapaneseKoreanBrazilian PortugueseRussianChineseNOTE: Support for all supportedlocales except en-US requires theinstallation of language packs.If the requested dialect is not available,the API tries to match on the language,alone. For example, de-AA will matchwith de-DE.JSON request components9
HTTP headerValueDescriptionIf the API cannot find a match, it usesen-US instead of returning an errormessage.For more information, see Localizingresponse text.Content-type:application/jsonBody content type of the request.Set-Cookie:Login session ticketBecause the API uses cookie-basedauthentication, the HTTP client mustsupport cookies in order to use the API.More than one cookie may be required touse the REST API.For more information, see Connectingand authenticating.EMC-CSRF-TOKEN: token CSRF token used to mitigate CrossSite Request Forgery vulnerabilities. Thetoken is gathered from a GET responseand required to send with POST andDELETE requests. The token is good forthe entirety of the session.For more information, see Connectingand authenticating.X-EMC-REST-CLIENT:trueRequired to send in all requests if usingBasic authentication.For more information, see Connectingand authenticating.Application-Type: plugin name / pluginversion Optional. REST client name and version.Related referencesURI patternsRequest parametersRequest bodyRelated tasksConnecting and authenticatingRequest parametersThe REST API supports the following request parameters:Request parameterApplicable request typesDescriptioncompactCollection query and instance queryrequestsOmits metadata from each instance inthe query response. Values are: true (implied when you use&compact without a value) false (default)For more information, see Omittingmetadata from responses.10JSON request components
Request parameterApplicable request typesDescriptionfieldsCollection query and instance queryrequestsSpecifies a comma-separated list ofattributes to return in a response. If youdo not use this parameter, a query willreturn the id attribute only.When using fields, you can: Use dot notation syntax to return thevalues of related attributes. Optionally, define a new attributefrom field expressions associatedwith one or more existing attributes.For more information, see Specifying theattributes to return in a query response,Extending queries to include relateddata, and Defining new attributes fromexisting attributes.filterCollection query requestFilters the response data against aset of criteria. Only matching resourceinstances are returned. Filtering is caseinsensitive.When using filter, you can use dotnotation syntax to filter by the attributesof related resource types.For more information, see Filteringresponse data and Extending queries toinclude related data.groupbyCollection query requestGroups the specified values and appliesthe @sum function to each group.For example, you could use groupbywith @sum to return a summary of disksizes for each disk type.For more information, see Aggregatingresponse data.languageAll request typesOverrides the value of the Acceptlanguage: header. This is useful fortesting from a plain browser or from anenvironment where URL parameters areeasier to use than HTTP headers.The language parameter specifies thelocalization language for error messages,events, alerts, and other localizableresponses.Valid values are: -CN:GermanEnglish (default)Latin American SpanishFrenchJapaneseKoreanBrazilian PortugueseRussianChineseJSON request components11
Request parameterApplicable request typesDescriptionFor more information, see Localizingresponse text.orderbyCollection query requestSpecifies how to sort response data.You can sort response data in ascendingor descending order by the attributesof the queried resource type. And youcan use dot notation syntax to sortresponse data by the attributes ofrelated resource types.For more information, see Sortingresponse data and Extending queries toinclude related data.Collection query requestpageIdentifies the page to return in aresponse by specifying the page number.If this parameter is not specified, theserver returns all resource instances thatmeet the request criteria in page 1.For more information, see Paginatingresponse data.per pageCollection query requestSpecifies the number of resource typeinstances that form a page. If thisparameter is not specified, the serverreturns all resource instances that meetthe request criteria in the page specifiedby page (or in page 1, if page is also notspecified).NOTE: The server imposes an upperlimit of 2000 on the number ofresource instances returned in apage.For more information, see Paginatingresponse data.with entrycountCollection query requestIndicates whether to return theentryCount response component inthe response data. The entryCountresponse component indicates thenumber of resource instances in thecomplete list. You can use it to getthe total number of entries when pagingreturned a partial response.By default, the entryCount responsecomponent is not returned. Setwith entrycount true to returnthe entryCount response component.For more information, see Paginatingresponse data.timeout12JSON request componentsMost non-GET requestsExecutes the request in the background.Most active management requests(ones that attempt to change theconfiguration) support this option. Thedocumentation for each API method inthe Unisphere Management REST APIReference Guide specifies whether themethod supports this option.
Request parameterApplicable request typesDescriptionFor more information, see Working withasynchronous requests.To use request parameters, append the parameters to the request URI. The first request parameter appended to the URI beginswith a ? character. Additional request parameters begin with & instead of ?. You can combine request parameters and can usethem in any order. If a request parameter is repeated, all but the last one is ignored.Example 1The following request uses a fields query parameter to return the name, and rpm attributes, a filter query parameterto return disk instances that have an RPM of 15000, and a compact query parameter to omit metadata from each instancein the query response. It also sets the with entrycount query parameter to true, so that the entry count is included inthe response data. For readability purposes, this example omits URI encoding for the space character (%20) and % character(%25).RequestGET api/types/disk/instances?fields rpm,name&filter rpm eq15000&compact true&with entrycount trueResponse{"@base": lter rpm eq15000&fields rpm,name,id&per page 2000&compact true","updated": "2015-12-02T21:03:14.446Z","links": [{"rel": "self","href": "&page 1"}],"entryCount": 20,"entries": [{"content": {"id": "dpe disk 0","name": "DPE Disk 0","rpm": 15000}},{"content": {"id": "dpe disk 1","name": "DPE Disk 1","rpm": 15000}},{"content": {"id": "dpe disk 2","name": "DPE Disk 2","rpm": 15000}},.Example 2The following request uses the per page and page query parameters to group returned disk instances into chunks oftwo instances per page and to return only the instances on page three. It also uses fields query parameter to return theJSON request components13
name, pool and tierType attributes, and the compact query parameter to omit metadata from each instance in the queryresponse:RequestGET api/types/disk/instances?per page 3&page 2&fields name,pool,tierType&compact trueResponse{"@base": elds name,tierType,id,pool.id&per page 3&compact true","updated": "2015-11-19T22:47:53.424Z","links": [{"rel": "self","href": "&page 2"}],"entries": [{"content": {"id": "dae 0 1 disk 3","tierType": 20,"name": "DAE 0 1 Disk 3","pool": {"id": "pool 1"}}},{"content": {"id": "dae 0 1 disk 4","tierType": 20,"name": "DAE 0 1 Disk 4","pool": {"id": "pool 1"}}},{"content": {"id": "dae 0 1 disk 5","tierType": 20,"name": "DAE 0 1 Disk 5","pool": {"id": "pool 1"}}}]}Related referencesHTTP request headersURI patternsRequest bodyURI patternsIn a REST API, the client sends Uniform Resource Identifiers (URIs) to the server. Each URI acts as a template for which youspecify a resource type, ID, and desired action.14JSON request components
Basic URI patternsThe following table describes the basic URI patterns that the Unisphere Management REST API supports:Table 1. Basic URI patterns in the REST APIURI patternHTTP OperationsDescriptionCollection type resource URIGETRetrieves a list of instances for the specified resource type.For more information, see Retrieving data for multipleoccurrences in a collection./api/types/ resourceType /instancesPOSTCreates a new instance of the specified resource type, usingdata specified in the request body, if allowed.For more information, see Creating a resource instance.Instance resource URIGETFor all resource types:For more information, see Retrieving data for a specifiedresource instance./api/instances/ resourceType / id NOTE: To see if a resource type can be identifiedby the user-assigned name, see the individual resourcetype topics in the Unisphere Management API ReferenceGuide.For applicable resource types:/api/instances/ resourceType /name: assignedName Retrieves the specified resource instance.DELETEDeletes the specified resource instance, if allowed.For more information, see Deleting a resource instance.NOTE: To see if a resource type can be identifiedby the user-assigned name, see the individual resourcetype topics in the Unisphere Management API ReferenceGuide.Instance action URIPOSTFor all resource types:/api/instances/ resourceType / id /action/ actionName For more information, see Performing an instance-levelresource-specific action.For applicable resource types:NOTE: To see the supported actions for a resourcetype and whether the resource type can be identifiedby the user-assigned name, see the individual resourcetype topics in the Unisphere Management API ReferenceGuide./api/instances/ resourceType /name: assignedName /action/ actionName Class-level action URI/api/types/ resourceType /action/ actionName Performs the action specified in /action/ actionname for the specified resource instance. For example, a URIpattern containing /action/modify directs the system tomodify the specified resource instance.POSTPerforms the action specified in action/ actionName for the specified non-singleton resource type. For example, aURI pattern containing action/RecommendForInterfacefor the ipPort resource type recommends ports on the SPspecified in the body of the request to use for creating iSCSINAS servers.For more information, see Performing a class-level resourcespecific action.For a list of supported class-level actions for a resourcetype, see the individual resource type topics in the UnisphereManagement API Reference Guide.JSON request components15
URI patterns for downloading and uploading filesThe following table describes the URI patterns for downloading and uploading files that the Unisphere Management REST APIsupports:URI patternHTTP OperationsDescriptionURI for downloading a NAS serverconfiguration fileGETDownloads a NAS server configuration file from thespecified NAS server to the local host.For more information, see Downloading and uploading NASserver configuration files./download/ protocolType /nasServer/ nasServerId URI for uploading a NAS serverconfiguration filePOST/upload/ protocolType /nasServer/ nasServerId Uploads a NAS server configuration file to the specifiedNAS server. You must POST the NAS server configurationfile using a multipart/form-data format, as if from a simpleweb page.For more information, see Downloading and uploading NASserver configuration files.URI for downloading an x.509 certificatefileGETDownloads the specified x.509 certificate file from thestorage system to the local host./download/x509Certificate/ cert id For more information, see Downloading and uploading x.509certificates.URI for uploading an x.509 certificate file POSTUpload
you can use the rest api to do all of the following: configure system settings for the storage system. manage the connections to remote systems, including manage host configurations, iscsi initiators, and iscsi chap accounts. configure network communication, including manage nas servers and set up isns for iscsi storage. manage storage,
