HOST EUROPE CLOUD STORAGE REST API DEVELOPER REFERENCE

Transcription

1 HOST EUROPE CLOUD STORAGE REST API DEVELOPER REFERENCE

2 REST API REFERENCE REST OVERVIEW Host Europe REST Storage Service uses HTTP protocol as defned by RFC REST operations consist in sending HTTP request to Host Europe REST Storage Service, which will return HTTP responses. REST HTTP Request contain a request method, a URI, headers and a query string and body. The responses contain status codes, headers, and may contain a response body. REST requests include headers which contain the following information: Content-Length Message Length (without headers), as specifed by RFC This header of type string is required for PUT and operations that load XML, such as logging and ACLs. Content-Type Content Type of the resource (e.g. text/plain). Date Date and Time of the request (default format is Mon, 06 Apr :00:00 GMT which conforms to RFC 2616 Section ). Host The Host should display the standard Storage Service. If the host contains anything else than the standard BRS2 Storage Server, this information will be used as a bucket for the request, as explained in Virtual Hosting of Buckets. This header is required for HTTP1.1. Contains either: Service Hostname Virtual Host (bucket.cs.hosteurope.de) Bucket. Authorization Contains the information required for authentication. Please refer to Authenticating REST Requests for more information on authorization formats. x-amz parts Divided into 2 types: x-amz- : contain system metadata. x-amz-meta-: contain user defned metadata V1 sb 2

3 SERVICE OPERATIONEN GET Service The GET operation on a service returns a list of all the buckets owned by the authenticated sender of the request. You must authenticate with a valid Access Key ID. Anonymous requests cannot list buckets. GET / HTTP/1.1 Host: cs.hosteurope.de Date: Mon, 10 Aug :55:19 GMT Content-length: 317 <?xml version="1.0" encoding="utf-8"?> <ListAllMyBucketsResult xmlns=" <Owner> <ID>14B5C45B8E359BC1601B7C682D83EB50648AE420</ID> <DisplayName>Test </DisplayName> </Owner> <Buckets> <Bucket> <Name>polo</Name> <CreationDate> T16:31:04.000Z</CreationDate> </Bucket> </Buckets> </ListAllMyBucketsResult> In this sample syntax, the Owner feld lists information about the bucket owner. The Buckets feld lists buckets and their metadata V1 sb 3

4 BUCKET OPERATIONS PUT Bucket Using PUT operation on a bucket has a diferent efect than the PUT operation on objects. If the bucket does not exist, the PUT operation will create the Bucket. Each user may create up to 100 buckets. PUT / HTTP/1.1 Host: polo2.cs.hosteurope.de Content-Length: 0 Date: Mon, 10 Aug :59:05 GMT GET Bucket Using GET operation on a bucket has a diferent efect than the GET operation on objects. The GET operation on a bucket lists the content of the whole Bucket. GET Bucket Parameters It is possible to pass on several arguments to the GET Bucket request, using URL scheme like? prefx=prefx;marker=marker;etc. prefx This argument of type string limits the response to keys that begin with the specifed prefx. You may use prefxes to separate a bucket into diferent sets of keys. marker This argument of type string indicates the listing start point of the bucket. The list will include only the keys that occur after the specifed marker. For pagination purposes, it is possible to get the next page of results using the last key of the current page as a marker for instance. max-keys This Integer argument determines the maximum number of results the body response should contain. delimiter This string argument causes keys that contain the same string between the prefx and the frst occurrence of the delimiter to be rolled up into a single result element in the CommonPrefxes collection V1 sb 4

5 GET / HTTP/1.1 Date: Mon, 10 Aug :55:53 GMT Content-length: 853 <?xml version="1.0" encoding="utf-8"?> <ListBucketResult xmlns=" <Name>polo</Name> <Prefix></Prefix> <Marker></Marker> <MaxKeys>1000</MaxKeys> <IsTruncated>false</IsTruncated> <Contents> <Key>chunk</Key> <LastModified> T09:11:58.000Z</LastModified> <ETag>"f436d2e0ed02b7b73bd10c6693e95ac3"</ETag> <Size>18274</Size> <Owner> <ID>14B5C45B8E359BC1601B7C682D83EB50648AE420</ID> <DisplayName>Test</DisplayName> </Owner> <StorageClass>STANDARD</StorageClass> </Contents> <Contents> <Key>ls</Key> <LastModified> T16:28:04.000Z</LastModified> <ETag>"f58860f27dd c "</ETag> <Size>92376</Size> <Owner> <ID>14B5C45B8E359BC1601B7C682D83EB50648AE420</ID> <DisplayName>Test</DisplayName> </Owner> <StorageClass>STANDARD</StorageClass> </Contents> </ListBucketResult> In the example response above, we can see: The <name> tag contains the bucket name. The two <Contents> tags contain 2 object descriptions, each defned by the <Key> tag. The <Owner> tag contain information about the owner of the object V1 sb 5

6 DELETE Bucket Using DELETE operation on a bucket has a diferent efect than the DELETE operation on objects. The DELETE operation on a bucket deletes it if the bucket is empty. DELETE / HTTP/1.1 Host: polo2.cs.hosteurope.dedomain.com HTTP/ No Content Date: Mon, 10 Aug :59:43 GMT OBJECT OPERATIONS PUT Object The PUT request operation adds an object to a bucket. The response returned indicates if the object has been stored successfully. The user must have WRITE access to the bucket to add an object. PUT Object Parameters Content-Type Set a standard MIME type for the content format. Default is binary/octet-stream. Content-Length Size of the object in bytes. Content-MD5 The base64 encoded 128-bit MD5 digest of the message (without the headers). x-amz-acl The canned ACP to apply to the object. Options include private, public-read, public-read-write, and authenticated-read. x-amz-meta Any header starting with the meta prefx is considered meta-data. For further information, please refer to the RFC V1 sb 6

7 PUT /newchunk HTTP/1.1 Content-Length: length Content-MD5: md5_digest Content-Type: type Expires: Date: Mon, 10 Aug :57:07 GMT Etag: "956398ac99977fa25bceb979777ebab6" Content-Length: 0 COPY Object The COPY request operation copies an object from a bucket to another bucket. The response returned indicates if the object has been copied successfully. The user must have READ access to the Source Object, WRITE access to the destination bucket to copy an object. COPY Object Parameters x-amz-copy-source This argument contains the name of the source bucket and key of the source object, separated by a slash /. This string must be URL-encoded, and the source bucket name must be valid. x-amz-metadata-directive This argument takes two possible values: COPY: specifes that the metadata from the source object should be copied with the metadata provided in the request. REPLACE: specifes that the metadata from the source object should be replaced with the metadata provided in the request. x-amz-copy-source-if-match This argument will make the request copy the object if its entity tag (Etag) matches the specifed value. x-amz-copy-source-if-none-match This argument will make the request copy the object if its entity tag (Etag) is other than the specifed value. x-amz-copy-source-if-unmodifed-since This argument will make the request copy the object if it has not been modifed since the specifed time. The value for this argument must be a valid HTTP date. See RFC for more information V1 sb 7

8 x-amz-copy-source-if-modifed-since This argument will make the request copy the object if it has been modifed since the specifed time. The value for this argument must be a valid HTTP date. See RFC for more information. COPY /newchunk HTTP/1.1 x-amz-copy-source: /polo/chunk Content-Length: length Content-Type: type Expires: Date: Mon, 10 Aug :02:21 GMT Etag: "f436d2e0ed02b7b73bd10c6693e95ac3" Content-Length: 189 <?xml version="1.0" encoding="utf-8"?> <CopyObjectResult> <LastModified> T16:02:22.000Z</LastModified> <Etag>"f436d2e0ed02b7b73bd10c6693e95ac3"</ETag> </CopyObjectResult> GET Object The GET request operation fetches objects from Host Europe REST Storage Service. GET Object Parameters If-Modifed-Since This argument will make the request return the object only if it has been modifed since the specifed time. The value for this argument must be a valid HTTP date. See RFC for more information. If-Unmodifed-Since This argument will make the request return the object only if it has not been modifed since the specifed time. The value for this argument must be a valid HTTP date. See RFC for more information. If-Match This argument will make the request return the object only if its entity tag (Etag) is identical to the specifed value. If-None-Match This argument will make the request return the object only if its entity tag (Etag) is diferent from the specifed value V1 sb 8

9 GET /Chunk HTTP/1.1 Date: Mon, 10 Aug :00:57 GMT Last-modified: Thu, 06 Aug :11:58 GMT Etag: "f436d2e0ed02b7b73bd10c6693e95ac3" Content-length: Data goes here... HEAD Object The HEAD request operation returns metadata information on an object. The user must have READ / WRITE access to the buckets to add an object. HEAD Object Parameters Etag This option returns the Etag of the Object. HEAD /Chunk HTTP/1.1 Date: Mon, 10 Aug :04:02 GMT Content-length: V1 sb 9

10 DELETE Object The DELETE action removes the given object from Host Europe REST Storage Service. The user must have WRITE access to the bucket to delete an object. Warning - It is not possible to restore a deleted object. DELETE /Chunk HTTP/1.1 You can use standard request headers for this action. HTTP/ No Content Date: Mon, 10 Aug :57:43 GMT V1 sb 10