ESU REST API Guide.book - EMC Community Network

EMC STORAGE UTILITY 

REST API Guide 

Version 1.0 

Revision A 

EMC CORPORATION 

Corporate Headquarters: 

Hopkinton, MA 01748-9103 

1-508-435-1000 

www.EMC.com

© 2009 EMC Corporation. All rights reserved. 

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 is a registered trademark. All other trademarks used herein are the property of their respective owners. 

2

Contents 

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 

Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 

Typographic Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 

1 REST Web Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 

Service Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 

Common Rest Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 

Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 

Managing Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 

Enabling Object Access Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 

Object Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 

User-defined Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 

System-defined Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 

2 REST API Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 

POST Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 

CreateObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 

SetACL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 

SetUserMetadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 

VersionObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 

GET Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 

GetACL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 

GetListableTags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 

GetSystemMetadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 

GetUserMetadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 

ListObjects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 

ListUserMetadataTags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 

ListVersions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 

ReadObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 

HEAD Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 

PUT Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 

UpdateObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 

DELETE Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 

DeleteObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 

DeleteUserMetadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 

3

A REST Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 

Contents 4

Preface 

This document explains how to use the EMC ® Storage Utility (ESU) web service to create objects and 

manage their related metadata. 

Documentation 

The following documents comprise the EMC Storage Utility documentation set. 

Document Description Intended Audience 

EMC Storage Utility User 

Guide 

Describes aspects of the portal 

including how to register for the 

service, and how to use the 

authentication keys: 

Any customer preparing to use 

the EMC Storage Utility portal. 

EMC Storage Utility Quick 

Start Guide 

http://preview.emccis.com/downloads/esu_ug.pdf 

Explains a fast track approach to 

using the web service: 

Any developer preparing to use 

the EMC Storage Utility portal. 

http://preview.emccis.com/downloads/esu_qs.pdf 

Typographic Conventions 

The following conventions are used in this guide: 

Conventions 

Blue text 

FixedWidth 

FixedWidthBold 

FixedWidthItalics 

Meaning 

Hyperlinked cross reference or URL. 

Commands, filenames, and code examples 

Emphasis within code examples 

Variable names in text 

5

1 REST Web Service 

EMC ® Storage Utility is an object-storage system with enormous scalability and extensibility. It uses 

metadata-driven policies to manage data placement and data services. 

This guide describes the programmatic interfaces to store, retrieve, and edit objects, which can be any 

content type. 

Object creation and management can be done through REST-based Web services. The object interface 

supports metadata tagging, collection creation, version creation, and other advanced metadata 

operations. The APIs described in this guide are used to manage objects and their metadata. 

There are two types of metadata: 

 

 

User metadata is a collection of text name-value pairs, which are not validated by the system. User 

metadata allows application developers the flexibility to create custom tags for data specific to the 

application they are developing. 

System metadata is automatically generated and is updated by the system based on a predefined 

schema. 

Features that are accessible using the web service include: 

 

 

Creating, reading, updating, and deleting objects. 

Managing object metadata defined in the data store. 

This chapter describes the principles on which the web service operates. 

Service Overview 

Use the web service for applications in which object data or metadata is passed to the system for storage 

management and retrieval. 

The service is based on a standard request and response model, as shown in the following diagram. 

You use HTTP methods like POST, DELETE, PUT, and GET to create, delete, update, and read objects and 

metadata. 

Web Client Interface 

Service Request 

Refresh 

Service Response 

Web Service 

6

Common Rest Headers 

The following table shows the common headers passed between the client and the server. Most 

object-service operations share common headers. For a list of the headers related to request and 

response transmissions, refer to each operation. 

Header 

x-emc-uid: subtenantid/userid 

x-emc-signature: signature 

Description 

The subtenantid and userid (UID) of an application 

that is consuming the API. Only one UID is allowed 

per request. The shared secret associated with this 

UID is used for signature generation. See “Managing 

Authentication.” 

The signature provides a means to authenticate the 

UID making the request. See “Algorithm for Securing 

REST Messages” for details on constructing this 

header. 

x-emc-date : Date_in_UTC_format Date format specified as Thu, 31 Jan 2009 19:37:28 

GMT, as defined in RFC 2616, section 3.3.1. 

Date : Date_in_UTC_format Date format specified as Thu, 31 Jan 2008 19:37:28 

GMT, as defined in RFC 2616, section 3.3.1. 

x-emc-useracl: uid1=Permission 

[,uid2=Permission...] 

x-emc-groupacl:groupname=Permission 

[,groupname=Permission...] 

x-emc-meta: name1=value1 

[,name2=value2...] 

x-emc-tags: tag1 [,tag2...] 

x-emc-listable-tags: tag1 [,tag2...] 

x-emc-listable-meta: name1=value1 

[,name2=value2...] 

Range: Bytes=beginOffset-endOffset 

A set of rights assigned to the object ID for the 

specified UID. This accepts multiple entries using the 

format described. UIDs must belong to the same 

subtenantid. 

Sets the rights assigned to the object ID for the user 

group. Only the group OTHER is supported; the Web 

server ignores all other groups. 

The name-value pairs that describe an object. The 

service permits up to 128 of these pairs in one 

request. 

This header can occur in the request and the response 

and can include up to 128 comma-separated values. 

See “ListObjects.” 

Specifies the name-value pairs that are listable for a 

given object. Listable refers to the context of a tag and 

whether an object is indexed by that tag. This header 

occurs only in response output. 

Specifies the name=value pair to be assigned to this 

listable tag. This tag is common to CreateObject, 

UpdateObject, and SetUserMetadata. It also occurs 

in the response output of GetUserMetadata. 

The beginning and ending offsets of an object on the 

server. This header appears only in the request 

payload of UpdateObject and ReadObject. 

1: REST Web Service Common Rest Headers 7

Content-Length: 

Content-Type: 

x-emc-delta: 

The length of the request/response body, in bytes. 

Used to get and set the content type of the object. If 

this is not specified, it defaults to 

application/octet-stream. 

Present only in the response from the server. The 

value of this header specifies the number of bytes by 

which the total disk space used by the user went up 

(positive number) or down (negative number) as a 

result of the operation. 

1: REST Web Service Common Rest Headers 8

Security 

Security for Web services consists of authentication using an encrypted signature model, and 

authorization through Access Control Lists (ACLs) at the user (UID) level. 

Managing Authentication 

The Web service uses a combination of the Token ID, and other request headers to produce a signature 

that authenticates the user accessing the web service. It uses a combination of various pieces of the 

message to validate the identity of the sender, integrity of the message, and non-repudiation of the 

action. 

The Token ID that you received via e-mail from the portal agent administrator consists of the subtenant 

ID, and the UID separated by a slash (/). The sub-tenant ID is a randomly generated, 32 character 

alphanumeric string, which is unique to each customer. The UID, however, is unique to a web-based 

application. The UID, which appears after the slash, is comprised of a portion of the customer name, 

and a randomly generated string. For example, if the customer name is 'ACME', then the UID string 

appends the additional random characters as shown below. The whole Token ID contains 53 uppercase 

characters including the slash, as shown in the following example: 

5f8442b515ec402fb4f39ffab8c8179a/ACME03GF52E8D8E581B5 

To complete the authentication operation, you must generate a signature using the shared secret, which 

is associated with the UID. The shared secret is a value generated by the EMC Storage Utility Agent 

responsible for managing this application. The shared secret appears in the same e-mail message that 

contains the Token ID. The following sample represents a typical shared secret: 

MBqhzSzhZJCQHE9U4RBK9ze3K7U= 

Without this information, your Web-service application cannot be authenticated by the server. Contact 

your EMC Storage Utility Agent, and request the UID and shared secret corresponding to your 

application. Note that the shared secret is in base64-encoded form. It needs to be base64 decoded before 

it can be used; see “Algorithm for Securing REST Messages” for additional information. 

The server retrieves the UID from the request and retrieves the shared secret associated with the UID 

stored on the server. The server then regenerates the signature using the same algorithm as the client. If 

this signature matches the one in the request, the web service processes the request and returns the 

response payload. 

ACLs further specify authorization of an action that may be taken on one or more objects. Specify the 

UID within the ACL header to establish access control. Note that a UID is restricted to the subtenantid 

established for the primary customer web service account. 

Algorithm for Securing REST Messages 

A client wanting to talk to the REST API composes the request and computes a hash of the request 

using the algorithm for securing REST messages. The UID is stored in a custom HTTP header, which is 

x-emc-uid and is a part of the request. Then, a signature is computed by applying HMAC-SHA1 on the 

hash and using the shared secret that maps to the UID in the request. This signature is appended to the 

request and sent to the web service for comparison. 

The header has the following format: 

1: REST Web Service Security 9

x-emc-signature : signature 

The signature is defined as: 

signature = Base64(HMACSHA1(HashString)) 

where Base64 is the base64 encoding of the argument and HMACSHA1 is the keyed hash of the argument. 

The shared secret is used for computing the HMAC-SHA1. The actual shared secret is in binary format. 

This binary array of bytes is converted to a human-readable format by base64-encoding it, and this 

encoded format is what a user receives from the EMC Storage Utility portal agent. Make sure the 

shared secret is base64-decoded before using it as an input to the HMAC-SHA1 algorithm to generate 

the signature. 

For example, here is some Ruby code: 

digest = HMAC.digest(Digest.new(SHA1), Base64.decode64(key), HashString) 

return Base64.encode64(digest.to_s()).chomp() 

SHA1 is defined above. key is the base64-encoded shared secret that the user receives. When you 

base64-encode a string, the resulting string may look like this: xxxxxxxxxxx\n. You must call the 

chomp() function to remove the \n character at the end of the result string. 

HashString is computed as follows: 

HTTPRequestMethod + '\n' + 

ContentType + '\n' + 

Range + '\n' + 

Date + '\n' + 

CanonicalizedResource + '\n' + 

CanonicalizedEMCHeaders 

where + is the concatenation operator. 

Components of HashString are described in the following table. 

Field 

HTTPRequestMethod 

Content-Type 

Range 

Date 

CanonicalizedResource 

CanonicalizedEMCHeaders 

Description 

One of the five HTTP method types, in uppercase: GET, POST, PUT, 

DELETE, HEAD. 

Content type, in lowercase. Only the value is used, not the header 

name. If a request does not include an HTTP body, this is an empty 

string. 

Range header, in lowercase. Only the value is used, not the header 

name. If a request does not include the range header, this is an empty 

string. 

Standard HTTP header, in UTC format. Only the date value is used, 

not the header name. 

Path portion of the HTTP request URI, in lowercase. 

Refer to the process below for canonicalizing EMC headers. 


Canonicalization 

Canonicalization of EMC headers is done as follows: 

1 Remove any white space before and after the colon and at the end of the metadata value. Multiple 

white spaces embedded within a metadata value are replaced by a single white space. For example: 

Before canonicalization: 

After canonicalization: 

x-emc-meta: title=Mountain Dew 

x-emc-meta:title=Mountain Dew 

2 Convert all header names to lowercase. 

3 Sort the headers alphabetically. 

4 For headers with values that span multiple lines, convert them into one line by replacing any 

newline characters and extra embedded white spaces in the value. 

5 Concatenate all headers together, using newlines (\n) separating each header from the next one. 

There should be no terminating newline character at the end of the last header. 

Example 

input 

POST /rest/objects HTTP/1.1 

x-emc-listable-meta: part4/part7/part8=quick 

x-emc-meta: part1=buy 

accept: */* 

x-emc-useracl: UID1=FULL_CONTROL,UID2=WRITE 

date: Thu, 05 Jun 2008 16:38:19 GMT 

content-type: application/octet-stream 

x-emc-date: Thu, 05 Jun 2008 16:38:19 GMT 

x-emc-groupacl: other=NONE 

host: 10.5.115.118 

content-length: 4286 

x-emc-uid: 6039ac182f194e15b9261d73ce044939/user1 

Example 

HashString 

POST 

application/octet-stream 

Thu, 05 Jun 2008 16:38:19 GMT 

/rest/objects 

x-emc-date:Thu, 05 Jun 2008 16:38:19 GMT 

x-emc-groupacl:other=NONE 

x-emc-listable-meta:part4/part7/part8=quick 

x-emc-meta:part1=buy 


x-emc-useracl:UID1=FULL_CONTROL,UID2=WRITE 

Note that there is a blank line included in the above example to account for the missing Range header. 

The resulting signature, which you add back into the request before sending, is: 

p/ram6MewqVWP8R64wT4bBy7Zmw= 

Enabling Object Access Control 

User-level authorization is achieved by using the x-emc-groupacl or x-emc-useracl custom headers 

to set the access control for objects. For the x-emc-useracl header, enter one or more of the UIDs that 

are defined for your system. UIDs serve a dual purpose with regard to security. The UID, by itself, also 


is used to further extend access control and management of objects. In the case of user ACLs, the UID 

must belong to the same subtenant to which the requesting UID belongs. A UID created under a 

different subtenant will have no access to objects owned by the authenticating tenant. 

The following example shows the structure of a request for the SetACL method, which includes the 

header x-emc-useracl: UID1=FULL_CONTROL to specify full access control for the users in UID1. The 

example also includes group read attributes using x-emc-groupacl: other=READ for a given object. 

POST /rest/objects/5ca1ab1e0a05737604847ff1f7a26d04848167b63d9f?acl HTTP/1.1 

accept: */* 

x-emc-useracl: UID1=FULL_CONTROL 




x-emc-groupacl: other=READ 

host: 10.5.115.118 


x-emc-signature: MDaCy5+1t7ZYdglRxpIOrF4K1hU= 

Response 

HTTP/1.1 200 OK 

Date: Thu, 05 Jun 2008 16:38:23 GMT 

Server: Apache/2.0.61 (rPath) 

Content-Length: 0 

Connection: close 

Content-Type: text/plain; charset=UTF-8 

Object Management 

Objects are the basis of the system. They include a variety of binary types that may be stored on the 

system. 

The following table lists the operations and related HTTP methods that act on objects. For deleting, 

updating, reading, and versioning, you must include the object ID if you use the object URL or the 

filename if you use the file-system namespace URL. The table below indicates the operations that can be 

performed with either an object ID or a filename. 

In the table, the entries in the URI column are prefixed by http://dns_name_or_ip_address/rest 

Operation HTTP Method URI 

CreateObject POST /objects 

— OR — 

/namespace/filename 

DeleteObject DELETE /objects/objectID 

— OR — 


ListVersions GET /objects/objectID?versions 

— OR — 


1: REST Web Service Object Management 12


GetACL GET/HEAD /objects/objectID?acl 

— OR — 

/namespace/filename?acl 

ListObjects GET/HEAD /objects 

ReadObject GET/HEAD /objects/objectID 

— OR — 


SetACL POST /objects/objectID?acl 

— OR — 


UpdateObject PUT /objects/objectID 

— OR — 


VersionObject POST /objects/objectID 

— OR — 


Metadata Management 

The Web service manages metadata associated with objects using the operations described in the table 

below. An object ID is required for most metadata operations. You specify the type of metadata 

operation in the URI of the request. All metadata tags used in these operations are case-sensitive. 

The following table lists the operations that act on metadata, and their related HTTP methods. As 

above, you must include the object ID if you use the REST object URL or the file path if you use the 

REST namespace URL. The table indicates the operations that can be performed with either an object ID 

or a filename. 

The entries in the URI column are prefixed by http://dns_name_or_ip_address/rest. 


DeleteUserMetadata DELETE /objects/objectID?metadata/user 

— OR — 

/namespace/filename?metadata/user 

GetListableTags GET/HEAD /objects/listabletags 

— OR — 

/namespace/filename?listabletags 

GetSystemMetadata GET/HEAD /objects/objectID/metadata/system 

— OR — 

/namespace/filename?metadata/system 

GetUserMetadata GET/HEAD /objects/objectID?metadata/user 

— OR — 




ListUserMetadataTags GET/HEAD /objects/objectID?metadata/tags 

— OR — 

/namespace/filename?metadata/tags 

SetUserMetadata POST /objects/objectID?metadata/user 

— OR — 


The web service divides metadata into two categories: user defined and system defined. 

User-defined Metadata 

The REST Web service passes all metadata information as HTTP header name-value pairs. For 

metadata, only 128 tag-value pairs can be added. The total size of each individual HTTP header cannot 

exceed 8k. 

The REST Web service further specifies user-defined metadata using tag types. There are two types of 

metadata tags supported by the service: 

 

 

Metadata tags 

Listable metadata tags 

Metadata Tags 

Tags are a way of classifying an object. For example, a user who wants to assign tags that classify the 

photos he took on vacation might create tags called beach, hotel, restaurant, and so on. This section 

describes the various tag types you can use to classify object data. The x-emc-meta and x-emc-tags 

headers are used to refer to non-listable tags. 

The REST Web service uses the following object metadata tags: 

x-emc-meta: name = value — There can be only one of these headers, with up to 128 

comma-separated, name=value pairs. The name=value pair must appear to the right of the colon. 

x-emc-tags: tag1, tag2, tag3 — There can be only one of these headers, with up to 128 

comma-separated values. 

Listable Metadata Tags 

Users may choose to tag objects by one or more of the metadata names. The Listable 

x-emc-listable-meta HTTP header in the metadata struct tells the Web-service code to use the name from 

the metadata name=value pair to tag the object. This tagging can be done during either the 

CreateObject,UpdateObject, or the SetUserMetadata operations. In a sense, tags act like indices for 

an object. The same object can be tagged with multiple names; this is how tags differ from containers, 

as an object can belong to only one container. Note that these tags are private to the user who creates 

them; tags created by one user cannot be seen by another user. 

The ListObject operation can be used to retrieve a list of all objects tagged with a particular name. The 

tag name is specified using the x-emc-tags header. 

The REST Web service uses the following custom HTTP headers to refer to listable tags: 


x-emc-listable-meta: name=value (requests and responses) — Indicates that the name from the 

specified metadata name=value pair is used or should be used to tag this object. This tag is 

common to the CreateObject, UpdateObject, and SetUserMetadata operations; it also occurs in 

the response output of GetUserMetadata. 

x-emc-listable-tags: name (responses only) — Indicates that the object is tagged by the 

specified name. This header occurs only in responses. 

The listable tag header can be used to introduce a hierarchy into the tag structure. The following 

example shows how the listable-meta tag is used to specify a tag hierarchy using the slash (/), as in 

part4/part7/part8=quick. 




Users can use this functionality for easy indexing, searching, and retrieval of objects. For example, a 

user who wants to store pictures from a vacation taken in 2008 may want to tag the pictures with the 

tag vacation/2008. If he went on multiple vacations in 2008, he might want to further qualify the tags 

as, for instance, vacation/2008/paris or vacation/2008/china. Then, he can easily retrieve a list of 

all pictures from his 2008 China vacation by issuing a ListObjects operation and specifying 

vacation/2008/china as the input parameter. 

System-defined Metadata 

Most metadata service operations share common properties, which define the structure of each object. 

Refer to each method for its list of properties. System metadata, which describes attributes like change 

time and last access time, is another of these common attributes. You can retrieve the system-defined 

metadata for an object by querying the appropriate resource. This can be done by adding 

/metadata/system after the object ID in the URI. Specify the desired content to be returned using the 

following header: 

Request 

Response 

x-emc-tags: atime,uid 

x-emc-meta: atime = 2008-01-31T19:55:53Z 

x-emc-meta: uid=user1 

The following table explains the system metadata returned by the Web service. 

Name Example Description 

atime 2007-10-29T18:19:57Z Last access time 

mtime 2007-10-29T18:19:57Z Last modified time 

ctime 2007-10-29T18:19:56Z Change time 

uid Session User id (the owner) 

gid Apache Group ID 

itime 2007-10-29T18:19:56Z Inception time 


Name Example Description 

type regular Type of the object. Could be either 'regular' or 

'directory' 

nlink 0 Number of links 

size 2971 Object size in bytes 

Request 

The following example shows the request input for the GetSystemMetadata operation. The suffix 

?metadata/system is appended to the end of the object ID. 

GET /rest/objects/5ca1ab1e0a05737604847ff1f7a26d04848167b63d9f?metadata/system 

HTTP/1.1 

accept: */* 




x-emc-tags: atime,uid 

host: 10.5.115.118 


x-emc-signature: 00NL3HHhyUXiRDTdWK52xqhQxTE= 

Response 

The response in this example returns the last access time and the UID for this object. 

HTTP/1.1 200 OK 



x-emc-meta: atime=2008-06-05T16:38:21Z, uid=user1 





2 REST API Reference 

This chapter describes how the various operations that act on object and metadata are mapped to HTTP 

methods. 

The EMC Storage Utility implements a standard REST interface to the Web service. The endpoint URL 

for the REST interface is http://ip_address/rest, with a suffix URI that describes the operation path. 

POST Methods 

POST methods enable creating objects, creating versions of existing objects, and setting user metadata 

and ACLs for specified objects. The following table provides the service operations associated with 

HTTP POST methods. 

Operation 

CreateObject 

SetACL 

SetUserMetadata 

VersionObject 

URI 

/objects 

— OR — 


/objects/objectID?acl 

— OR — 

/namespace/filename /acl 

/objects/objectID?metadata/user 

— OR — 


/objects/objectID 

— OR — 


17

CreateObject 

This operation creates an object with optional ACL and user metadata. Once created, the object can be 

increased to any size; see “UpdateObject.” No validation is done on the metadata. The header content 

length is required to represent the size of the contents of the HTTP body, or the service will return an 

error. Appropriate system metadata is generated automatically. 

CreateObject also can be used to create directories. Directories can be created implicitly or explicitly: 

Implicitly — Specify the full path for an object, and the new director(y)ies is(are) are created 

automatically as needed, before creating the object itself. 

Explicitly — Use CreateObject and end the directory name with a forward slash (/). The request 

body must be empty. 

Request 

The request may include custom headers to specify metadata that assigns a tag name to the object and 

creates a listable tag with a name-value pair for indexing purposes. The example below also employs 

user and group ACL headers to specify access control for this newly created object. 




accept: */* 

x-emc-useracl: UID1=FULL_CONTROL,UID2=WRITE 

date: Thu, 13 Nov 2008 16:59:57 GMT 


x-emc-date: Thu, 13 Nov 2008 16:59:57 GMT 


host: 168.159.116.51 



x-emc-signature: 7Nm52iT8gVcHbdX8fnbCwN+0vHI= 

Response 

The response payload contains the location header, which specifies the newly created object ID 

returned as a URI. 

HTTP/1.1 201 Created 

Date: Thu, 13 Nov 2008 16:59:57 GMT 


location: /rest/objects/491abe33a105736f0491c2088492430491c5d0d67efc 

x-emc-delta: 7584 




2: REST API Reference POST Methods 18

SetACL 

Use this operation to set the access control for this object. SetACL can be used for setting or resetting 

permissions. Either x-emc-groupacl or x-emc-useracl must be included, or the server will return an 

error. Submit a UID as the input string to the x-emc-useracl. 

Request 

Response 

POST /rest/objects/491abe33a105736f0491c2088492430491c5d0d67efc?acl HTTP/1.1 

accept: */* 

x-emc-useracl: UID1=FULL_CONTROL 





host: 168.159.116.51 


x-emc-signature: GS1M+BLkkjnWyuINcPoEypl4YlE= 

HTTP/1.1 200 OK 






SetUserMetadata 

The operation writes the metadata into the object. Either x-emc-listable-meta or x-emc-meta must 

be included in the request, or the server will return an error. 

Request 

Response 

POST /rest/objects/491abe33a105736f0491c2088492430491c5d0d67efc?metadata/user 

HTTP/1.1 

x-emc-listable-meta: part3=fast 

x-emc-meta: part1=order 

accept: */* 




host: 168.159.116.51 


x-emc-signature: PMhSeF4suQKnKoXPn8LvPCmQZNM= 

HTTP/1.1 200 OK 






VersionObject 

This operation creates a fixed (immutable) version of the object. 

N OTE: User metadata is copied from the specified object to its new version. 


Request 

Response 

POST /rest/objects/5ca1ab1e0a05737604847ff1f7a26d04848167b63d9f HTTP/1.1 

accept: */* 




host: 10.5.115.118 


x-emc-signature: LUKVxeRojK0dVvmmem2MP45+FKU= 

The response payload contains the location header, which specifies the newly created object ID 

returned as a URI. 

HTTP/1.1 201 Created 



location: /rest/objects/5ca1ab1e0a05737604847ff1f7a26d04848167ca551e 





GET Methods 

GET methods retrieve object data, including metadata, tags, and ACLs. The following table provides the 

service operations associated with HTTP GET method. 

Operation 

GetACL 

GetListableTags 

GetSystemMetadata 

GetUserMetadata 

ListObjects 

URI 

/objects/objectID?acl 

— OR — 


/objects/listabletags 

— OR — 

/namespace/filename?listabletags 

/objects/objectID?metadata/system 

— OR — 

/namespace/filename?metadata/system 


— OR — 


/objects 

ListUserMetadataTags 

ListVersions 

/objects/objectID?metadata/tags 

— OR — 

/namespace/filename?metadata/tags 

/objects/objectID?versions 

— OR — 


ReadObject 


— OR — 


2: REST API Reference GET Methods 21

GetACL 

This operation returns the ACL details associated with the specified object ID. 

Request 

Response 

GET /rest/objects/491abe33a105736f0491c2088492430491c5d0d67efc?acl HTTP/1.1 

accept: */* 




host: 168.159.116.51 


x-emc-signature: su7QB2NQqTpY1thoVeIDio6HITM= 

HTTP/1.1 200 OK 




x-emc-useracl: UID1=FULL_CONTROL, UID2=WRITE, UID3=WRITE, UID4=FULL_CONTROL 




GetListableTags 

This operation returns all listable tags under the specified input tag. For example, if an object is indexed 

by tag1 (in other words, tag1 is a listable tag for the object), tag1 is returned by this operation. If no tag 

is specified, it defaults to root, and all top-level tags are returned. Unlike all other operations, this 

operation is executed under the global namespace (not against an object). 

Request 

GET /rest/objects?listabletags HTTP/1.1 

accept: */* 




x-emc-tags: part4 

host: 168.159.116.51 


x-emc-signature: yJ96H4qKOwTG20aYbeqiL5vA/B0= 

The response payload returns all listable tags under the specified tag, as a comma-separated list. 

Response 

HTTP/1.1 200 OK 



x-emc-listable-tags: part7, part9 





GetSystemMetadata 

This operation returns the system metadata for the object. Specify the tags of the pairs to be returned as 

comma-separated entries for the x-emc-tags header. The absence of a tag returns all pairs. The Web 

service supports up to nine system metadata name-value pairs. See “System-defined Metadata.” 

Request 

Response 

GET /rest/objects/491abe33a105736f0491c2088492430491c5d0d67efc?metadata/system HTTP/1.1 

accept: */* 




host: 168.159.116.51 


x-emc-signature: 5LO2jZA5uTjB+EZlbI+0mSKLLDQ= 

The response returns each of the specified system-metadata types appended to the x-emc-meta header. 

HTTP/1.1 200 OK 



x-emc-meta: atime=2008-11-13T17:00:00Z, mtime=2008-11-13T16:59:58Z, 

ctime=2008-11-13T17:00:00Z, uid=user1, gid=apache, size=7584, nlink=0 




GetUserMetadata 

This operation returns the metadata associated with the specified object, as a comma-separated list of 

name-value pairs. Specify the tags of the pairs to be returned as comma-separated tag names. To get all 

pairs, omit the tag names. Regular metadata is returned using the x-emc-meta header; listable 

metadata, the x-emc-listable-meta header. 

Request 

Response 

GET /rest/objects/491abe33a105736f0491c2088492430491c5d0d67efc?metadata/user HTTP/1.1 

accept: */* 




host: 168.159.116.51 


x-emc-signature: AhUc3SrvaP34JMZYWOrF7mrB/oY= 

The response payload returns metadata associated with the specified object as name-value pairs for the 

tags specified in the request. 

HTTP/1.1 200 OK 



x-emc-meta: part1=buy, part2=here, part3=now 

x-emc-listable-meta: part4/part7/part8=quick, part4/part9=slow 





ListObjects 

This operation retrieves all object IDs indexed by a given tag. As mentioned earlier, listable tags are 

created in a user’s own namespace; hence, they are private to that user. Only objects belonging to the 

requesting UID are returned. 

Request 

Response 

GET /rest/objects HTTP/1.1 

accept: */* 




x-emc-tags: part4/part7/part8 

host: 168.159.116.51 


x-emc-signature: 7ZK5oO3gfG6d+u0+mYvSFsb4Spo= 

The response contains an XML payload listing the object IDs for this user. The output corresponds to 

the tag supplied in the request payload. Object IDs are 44 characters long, and there is no limit to how 

many objects you can store; therefore, it is possible to reach the limit for data in the HTTP header. As a 

result, the Web service returns the object IDs from a ListObjects operation into the XML body, not the 

header. 

HTTP/1.1 200 OK 




Transfer-Encoding: chunked 


 

 

491abe33a105736f0491ac237c55a50491b1c10a23c9 

491abe33a105736f0491ac237c55a50491b1c1f14814 

491abe33a105736f0491ac237c55a50491b1cc487deb 

491abe33a105736f0491ac237c55a50491b1d616b101 

491abe33a105736f0491ac237c55a50491b1d62598d0 

491abe33a105736f0491ac237c55a50491b1d630861b 

491abe33a105736f0491ac237c55a50491c1ff8179e9 

491abe33a105736f0491c2088492430491c2100899a7 

491abe33a105736f0491c2088492430491c2105ae450 

491abe33a105736f0491c2088492430491c210646da5 

 


ListUserMetadataTags 

This operation returns the user-defined metadata tags assigned to the object. Regular metadata is 

returned using the x-emc-tags header; listable metadata, the x-emc-listable-tags header. 

Request 

Response 

GET /rest/objects/491abe33a105736f0491c2088492430491c5d0d67efc?metadata/tags HTTP/1.1 

accept: */* 




host: 168.159.116.51 


x-emc-signature: iKix57OMoUoKvb9SbHz7S58Oe2Q= 

The response payload contains user-defined tags, including the set of listable tags that apply to the 

specified object. 

HTTP/1.1 200 OK 




x-emc-listable-tags: part3, part4/part7/part8, part4/part9 




ListVersions 

This operation retrieves all objects in the versioning chain of the specified object, including itself. 

Versioned objects can also be used as the specified object to the ListVersions operation. 

Request 

Response 

GET /rest/objects/5ca1ab1e0a05737604847ff1f7a26d04848167b63d9f?versions HTTP/1.1 

accept: */* 




host: 10.5.115.118 


x-emc-signature: 2A3ybcg9UnyV6IODHY50H+BWKdI= 

This operation returns the object IDs of all versions of the specified object. Object IDs are 44 characters 

long. This list has as many object IDs as there are versions of the specified object. 

HTTP/1.1 200 OK 





Content-Type: text/xml 

 

 

5ca1ab1e0a05737604847ff1f7a26d04848167b63d9f 

5ca1ab1e0a05737604847ff1f7a26d04848167ca551e 

 


ReadObject 

This operation returns the contents of the specified object, along with the associated user metadata, 

system metadata and access-control list. An optional Range header (see “Common Rest Headers”) can 

be used to read only part of the object rather than the entire object. If the Range header is specified, data 

from offset until offset+size is read and returned to the user. The default value of size=0 and a 

non-default value of offset returns the data from offset until size. 

Request 

Response 

GET /rest/objects/491abe33a105736f0491c2088492430491c5d0d67efc HTTP/1.1 

accept: */* 




host: 168.159.116.51 


x-emc-signature: 7ZaAUVi2rPMRy4XIOVmazof7jRQ= 

HTTP/1.1 200 OK 





x-emc-useracl: UID1=FULL_CONTROL, UID2=WRITE, UID3=FULL_CONTROL 

x-emc-meta: part1=buy, atime=2008-11-13T16:59:57Z, mtime=2008-11-13T16:59:57Z, 

ctime=2008-11-13T16:59:57Z, uid=UID3, gid=apache, size=7584, nlink=0 



Content-Type: application/octet-stream 


HEAD Methods 

There is a HEAD method corresponding to each GET method. HEAD methods are very similar to GET 

methods. A HEAD request looks exactly like a GET request, except the method name is HEAD instead of 

GET. The response from the server is different with a HEAD method: there is no response body, only 

headers are returned. This is especially useful for ReadObject requests when one wants to retrieve the 

object's user metadata, system metadata, and access-control list but not the object itself. 

PUT Methods 

The following table lists the table PUT method for updating object attributes. 

Operation 

UpdateObject 

URI 


— OR — 


UpdateObject 

UpdateObject can be used for updating the contents of an object, including its metadata and ACLs. 

You can update just part of the object or the complete object. To update part of the object, use the Range 

header (see “Common Rest Headers”) to specify the offset and size. 

Use UpdateObject to change the size of an object using one of the following methods: 

 

 

To truncate an object to size=0, omit the Range header, and specify an empty request body. 

Truncating an object to size=0 leaves the objectID unchanged. 

To increase or decrease an object's size, omit the range header and attach the new 

object content to the request body. 

UpdateObject also can be used to add or modify existing metadata or ACLs; for example, metadata can 

be changed from listable to non-listable and vice versa. 

Request 

PUT /rest/objects/491abe33a105736f0491c2088492430491c5d0d67efc HTTP/1.1 

x-emc-listable-meta: part4/part9=slow 

x-emc-meta: part2=here 

accept: */* 

x-emc-useracl: UID1=WRITE 




range: Bytes=10-29 

host: 168.159.116.51 



x-emc-signature: 4oZorU2nBQlADhq7fTMklstL1eU= 

2: REST API Reference HEAD Methods 27

Response 

HTTP/1.1 200 OK 



x-emc-delta: 0 




2: REST API Reference PUT Methods 28

DELETE Methods 

DELETE methods remove objects and metadata from the system. The following table provides the 

service operations associated with HTTP DELETEs. 

Operation 

DeleteObject 

DeleteUserMetadata 

URI 


— OR — 



— OR — 


DeleteObject 

This operation deletes the object that matches the ObjectID supplied in the URI. The operation also 

deletes associated metadata. 

Request 

Response 

DELETE /rest/objects/491abe33a105736f0491c2088492430491c5d0d67efc HTTP/1.1 

accept: */* 




host: 168.159.116.51 


x-emc-signature: 29AQTcYe428b0p0I/xI2X9oJyfM= 

HTTP/1.1 204 No Content 



x-emc-delta: -7584 




2: REST API Reference DELETE Methods 29

DeleteUserMetadata 

This operation deletes all user metadata with matching tags from the specified object. Specify the tags 

of the pairs to be deleted. System metadata can be neither deleted nor modified directly. The request 

must include the x-emc-tags, or the service returns an error. 

Request 

Response 

DELETE /rest/objects/491abe33a105736f0491c2088492430491c5d0d67efc?metadata/user HTTP/1.1 

accept: */* 





host: 168.159.116.51 


x-emc-signature: 5uuhZ+PetrdYmLWIWHFUZPWocHI= 

HTTP/1.1 204 No Content 






2: REST API Reference DELETE Methods 30

A 

REST Error Codes 

This appendix describes the error codes that are trapped and returned during Web service operations. 

When the operations are invoked using the REST interface and an exception occurs, the server returns 

an HTTP error, along with a detailed error message in the response body, which contains the error code 

and error description. 

HTTP/1.1 404 Not Found 

Date: Thu, 31 Jan 2008 20:03:24 GMT 




Content-Type: text/xml 

 

 

1003 

The requested object was not found. 

 

The following table lists the Atmos error codes and corresponding HTTP Error codes. 

Error 

Code 

Error Message 

HTTP 

Status 

Code 

HTTP Status Description 

1001 The server encountered an internal error. Please try 

again. 

500 Internal Server Error 

1002 One or more arguments in the request were invalid. 400 Bad Request 

1003 The requested object was not found. 404 Not Found 

1004 The specified range cannot be satisfied. 416 Requested Range Not 

Satisfiable 

1005 One or more metadata tags were not found for the 

requested object. 

1006 Operation aborted because of a conflicting 

operation in process against the resource. 

400 Bad Request 

409 Conflict 

1007 The server is out of memory. 500 Internal Server Error 

1008 The requested resource was not found on the server. 400 Bad Request 

1009 The method specified in the request is not allowed 

for the resource identified. 

1010 The requested object size exceeds the maximum 

allowed upload/download size. 

1011 The specified object length does not match the 

actual length of the attached object. 

405 Method Not Allowed 



31

Error 

Code 

Error Message 

HTTP 

Status 

Code 

HTTP Status Description 

1012 The requested update size was greater than the size 

of the attached object. 


1013 The server is out of disk space. 500 Internal Server Error 

1014 The maximum allowed metadata entries per object 

has been exceeded. 

1015 The request could not be finished due to insufficient 

access privileges. 


401 Unauthorized 

1016 The resource you are trying to create already exists. 400 Bad Request 

1019 The server encountered an I/O error. Please try 

again. 

1020 A requested resource is missing or could not be 

found. 



1021 A requested resource is not a directory. 400 Bad Request 

1022 A requested resource is a directory. 400 Bad Request 

1023 A requested directory is not empty. 400 Bad Request 

1024 A requested resource is in an unstable state. 500 Internal Server Error 

1025 A network resource is disconnected or could not be 

reached. 


1026 A cross device link was attempted to be created. 400 Bad Request 

1027 The client was uninitialized before the request was 

submitted. 

1028 The client was already initialized before the request 

was submitted. 



1029 The client could not be initialized. 500 Internal Server Error 

1031 The request timestamp was outside the valid time 

window. 

1032 There was a mismatch between the signature in the 

request and the signature as computed by the 

server. 

1033 Unable to retrieve the secret key for the specified 

principal. 

403 Forbidden 

403 Forbidden 

401 Unauthorized 

1034 Unable to read the contents of the HTTP body. 400 Bad Request 

1036 The specified offset was invalid. 400 Bad Request 

A: REST Error Codes 32

ESU REST API Guide.book - EMC Community Network

You also want an ePaper? Increase the reach of your titles

Delete template?

Save as template?