Dell Storage REST API Getting Started Guide
All Dell Storage API URI endpoints begin with https://{datacollector or Storage Center}:3033/api/rest
where "{datacollector or Storage Center}" is the hostname or IP address of your DSM Data Collector or
Storage Center. Only secure (https) sessions are allowed. To connect to the Dell Storage REST API
service, use the APIConnection/Login endpoint.
Revision History
Document number: 680-126-001
Revision Date Description
A April 2016 Initial release
Getting Started with the RESTful API
Every request to the REST API service requires two HTTP headers.
• Cookie: The cookie that is provided in the Set-Cookie header of the response from the Login request.
NOTE: Login requests use the Authorization header and must not have a cookie.
• x-dell-api-version: The version of the Dell Storage API to use. The API service verifies that this version
is supported.
Any PUT, POST, or DELETE request requires an additional HTTP header.
• Content-Type: Specifies the format of the body, must be "application/json" or "application/xml"
Optional headers:
• Accept: Specifies the format of the response body (JSON by default), must be "application/json" or
"application/xml".
• Accept-Encoding: Specifies if the response body should be compressed, must be "gzip".
• async: This header value must be "true" to execute the request method asynchronously. For more
information, refer to the Asynchronous Requests section in this document.
Response Error Codes
The common error codes are listed here. Additional error information is provided in the body of the
response.
• 400: Bad Request - Invalid body format, missing required attributes, invalid method name, invalid
attribute name, invalid attribute value format, or other error
• 401: Unauthorized - Invalid credentials were provided. Verify that a valid cookie was provided with the
request.
• 403: Forbidden - The user does not have the necessary privileges to access the requested resource.
• 404: Not Found - The object or method specified in the URI does not exist.
Document Number: 680-126-001
Rev. A
2016 - 04
• 405: Method Not Allowed - The HTTP method is not valid for the URI.
• 500: Internal Server Error - An unexpected error occurred on the server.
• 501: Not Implemented - The API provider has not implemented the method.
Asynchronous Requests
When a method is requested with the "async" header, the API service does not wait for the task to
complete before the response is sent. A 202 status code indicates a successful response. The response
body is an AsyncTask (refer to the following examples) object that contains information about the state of
the task and also a URI to retrieve updated state information. This URI is located in the "ReturnValue" field
and should be requested with the GET method. This URI will provide the latest information as long as the
task has not completed. Once the task is completed, the value of the original request is returned. This
value is returned one time only. Refer to the documentation for each endpoint to discover if it supports
asynchronous execution.
NOTE: Certain methods, including Get and GetList, do not support asynchronous requests.
JSON
{
"state": "Running",
"methodName": "GetScUserPreferencesDefaults",
"error": "",
"started": true,
"userName": "",
"localizedError": "",
"returnValue": "https://{datacollector or Storage Center}:3033/api/rest/
ApiConnection/AsyncTask/1418394170395",
"storageCenter": 0,
"errorState": "None",
"successful": false,
"stepMessage": "Running Method [Object: ScUserPreferences] [Method:
GetScUserPreferencesDefaults]",
"localizedStepMessage": "",
"warningList":[],
"totalSteps": 2,
"timeFinished": "1969-12-31T18:00:00-06:00",
"timeStarted": "2015-01-07T14:07:10-06:00",
"currentStep": 1,
"objectTypeName": "ScUserPreferences",
"objectType": "AsyncTask",
"instanceName": "1418394170395",
"instanceId": "1418394170395"
}
XML
<AsyncTask>
<instanceId>1418394170398</instanceId>
<instanceName>1418394170398</instanceName>
<objectType>AsyncTask</objectType>
<currentStep>1</currentStep>
<error/>
<errorState>None</errorState>
<localizedError/>
<localizedStepMessage/>
<methodName>GetScUserPreferencesDefaults</methodName>
<objectTypeName>ScUserPreferences</objectTypeName>
<returnValue>https://{datacollector or Storage Center}:3033/api/rest/
ApiConnection/AsyncTask/1418394170398</returnValue>
2
<started>true</started>
<state>Running</state>
<stepMessage>Running Method [Object: ScUserPreferences] [Method:
GetScUserPreferencesDefaults]</stepMessage>
<storageCenter>0</storageCenter>
<successful>false</successful>
<timeFinished>1969-12-31T18:00:00-06:00</timeFinished>
<timeStarted>2015-01-07T14:08:33-06:00</timeStarted>
<totalSteps>2</totalSteps>
<userName/>
<warningList/>
</AsyncTask
Filtering, Sorting, and Paginating GetList Results
Some objects have a "GetList" method to retrieve objects of the specific type. Each GetList method has
optional Filter, Sort, and Pagination attributes that can be used individually or combined.
Use a GetList filter to specify which results are returned in the response. The GetList filter has a filterType
and a list of attribute filters. Each attribute filter ("filters" array) also has a filterType.
The GetList filter filterType can be one of two values: "AND" or "OR":
• "AND" - The object must be in all of the attribute filters
• "OR" - The object must be in at least one of the attribute filters
Attribute filter filterType can include "Equals", "EqualsCaseSensitive", "NotEquals",
"NotEqualsCaseSensitive", "GreaterThan", "GreaterThanEquals", "LessThan", "LessThanEquals",
"IncludedInStr", "IncludesStr", "Regex", "StartsWith", or "StartsWithCaseSensitive". An attribute filter can be
used on any attribute on the object (attributes support some or all of these filter types).
The GetList method can be executed with either a GET or POST request. For the GET version (GET rest/
{ObjectType}/{ObjectName}), the GetList filter is specified with query parameters in the URI. By default
the GetList filter filterType is AND. An OR filter can be specified with the filterType parameter. Method
object and array attribute filters are not supported with URI filtering. Only "equals" is supported as the
filterType for the attribute filters. For the POST version (POST rest/{ObjectType}/{ObjectName}/GetList),
the GetList filter filterType must be specified and all attribute filterType values are supported.
The filtered results can be sorted by any attribute on the object in ascending or descending order using
the Sort attribute on the GetList method. If only SortOrder is specified, the results will be sorted by the
InstanceName attribute. If only SortBy is specified, the default order is ascending. If the Sort attribute is
not used, the results are unsorted. The SortBy and SortOrder attributes can be specified as query
parameters in the URI.
To limit the number of results in the response, the Pagination attribute can be set. The Offset is the zero-
based index of the first object to return. The Limit is the maximum number of results that will be in the
response. If not specified, all results will be returned. Note that if the state of the system changes in
between requests, an object is not guaranteed to be at the same index in the result.
URI query example:
rest/StorageCenter/ScVolume?
sortBy=Name&sortOrder=Descending&offset=10&limit=10&filterType=OR&mapped=False&a
ctive=True
3
JSON example (this also appears in all the GetList Request examples):
{
"Filter": {
"filterType":"OR",
"filters":[
{
"attributeName":"AttrName",
"attributeValue":"TheName",
"filterType":"Equals"
},
{
"attributeName":"AttrName2",
"attributeValue":"10GB",
"filterType":"GreaterThan"
}
]
},
"Sort": {
"sortBy":"AttrName3",
"sortOrder":"Ascending"
},
"Pagination": {
"offset": 10,
"limit": 10
}
}
Passing Objects into a Request
Some methods have object, method object, or interface attributes. If the type of the attribute is an object,
only the instance ID of the object or object list should be provided and not the all of the object's
attributes. For interface attributes, both the instance ID and object type must be provided (SourceVolume
below). All attributes must be provided for method objects (DirectoryUserGroup below).
{
"StorageCenter":"12345",
"ReleasedDisks":["12345.67", "201.4"],
"DirectoryUserGroup":{
"DirectoryEntity": "StringValue",
"GroupContext": "StringValue",
"GroupSid": "StringValue"
}
}
Null Attribute Values
It may be necessary to pass a null value for an attribute in a request. Null attribute values are not included
in responses.
JSON
{
"Folder":null
}
4
XML
<attributes xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<Folder xsi:nil="true"/>
</attributes>
Multiple Values for a Request Attribute
Although there is no use case for specifying an attribute value multiple times, the last value that is
specified will be used. In the example requests below, "Name2" will be the value sent to the API provider
for the Name attribute. Note that this practice is discouraged and may cause unexpected results.
JSON
{
"Name":"Name",
"Name":"Name2", DO NOT REPEAT ATTRIBUTES
"StorageCenter": "1234",
"Size": "10 GB"
}
XML
<attributes>
<Name>Name1</Name>
<Name>Name2</Name> DO NOT REPEAT ATTRIBUTES
<StorageCenter>1234</StorageCenter>
<Size>10 GB</Size>
</attributes>
Dell Storage REST API Support for Deprecated Objects
Dell follows the standard of supporting deprecated entities in the API through the next major version. For
example, if an object is marked as deprecated in version 3.x, the object will still be present and functional
through all the 3.x and 4.x versions. However, that object may be removed from the API starting with
version 5.x.
Copyright © 2016 Dell Inc. All rights reserved. This product is protected by U.S. and international copyright and
intellectual property laws. Dell™ and the Dell logo are trademarks of Dell Inc. in the United States and/or other
jurisdictions. All other marks and names mentioned herein may be trademarks of their respective companies.
