Blobstore API Reference | Predix Platform

Supported Operations

BLOB Store allows specific operations on stores and objects, along with a the ability to create an object specific signature.

Supported Operations on Stores

This section describes operations you can perform on stores.

GET Bucket (list objects)
GET Bucket Website
GET Bucket ACL
List Bucket Multi-part Uploads

Supported Operations on Objects

This section describes operations you can perform on objects.

PUT Object
GET Object
Abort Multi-part Upload
DELETE Object
GET Object ACL

Signature Creation

To sign a request, create a signature by calculating a hash of the request, then using the hash value and a secret access key to create a signed hash. You can add the signature to a request by using the HTTP Authorization header. All requests require the Authorization header.

Note: Blobstore supports the standard S3 V4 signature creation method.

PUT Object

Use the PUT Object operation to add an object to a store. Success responses are returned only after an entire object is added to the store. Partial addition of an object causes a rollback. The PUT Object operation requires WRITE permissions for the store.

Note: To upload large objects of greater than 100 MB, you should first split the object file into multiple parts and then perform separate uploads on each of the parts.

The Blobstore does not have a directory hierarchy, but you can name objects so that they imply a hierarchy. For example, instead of naming the object photo.jpg, you can name it, 2015/vacation/spain/photo.jpg.

The endpoint URL and credentials are in the VCAP environment variables for your application. To view the environment variables, on a command line, enter:

cf env <application_name>

Request Syntax

The following shows the syntax for the request header:

PUT /ObjectName HTTP/1.1
Host: <blobstore_url>
Date: <Date>
Authorization: <signatureValue>

Request Headers

You can use the following request headers for the PUT Object operation:

(Required) Authorization (or Content-MD5)
(Required) Date
(Required) Host
User-Agent
Content-MD5
Content-Type
Expect
Query_string
Url_path
Method

Response Headers

The PUT Object operation may include the following response headers:

Content-length
x-amz-id-2
Server
x-amz-request-id
ETag
Date

Note: The success response is received only after the entire object has been added.

GET Object

Use the GET Object operation to retrieve objects from the store. Authorization headers are required unless you grant READ access to an anonymous user.

Note: You must have READ access to the object you are retrieving.

Request Syntax

GET /ObjectName HTTP/1.1
Host: <blobstore_url>
Date: <Date>
Authorization: <signatureValue>
Range: bytes=byte_range

Request Headers

You can use the following request headers for the GET Object operation:

(Required) Authorization (or Content-MD5)
(Required) Date
(Required) Host
User-Agent
Query_string
Url_path
Method

Response Headers

The GET Object operation may include the following response headers:

Content-length
x-amz-id-2
Accept-ranges
Bytes, server
Last-modified
x-amz-request-id
ETag
Date
Content-type

GET Object ACL

Request Syntax

GET /ObjectName?acl HTTP/1.1
Host: <blobstore_url>
Date: <Date>
Authorization: <signatureValue>
Range:bytes=byte_range

Request Headers

You can use the following request headers for the GET Object ACL operation:

(Required) Authorization (or Content-MD5)
(Required) Date
(Required) Host
User-Agent
Url_path
Query_string

Response Headers

The GET Object ACL operation may include the following response headers:

x-amz-requestid
Date
Content-length
Content-type

GET Bucket (List Objects)

Use the GET Bucket operation to list the objects in the specified store.

Request Syntax

GET / HTTP/1.1
Host: <blobstore_url>
Date: <Date>
Authorization: <signatureValue>

Request Headers

You can use the following request headers for the GET Bucket operation:

(Required) Authorization (or Content-MD5)
(Required) Date
(Required) Host
User-Agent
Query_string
Url_path

Response Headers

The GET Bucket operation may include the following response headers:

x-amz-bucket-region
x-amz-id-2
Server
Transfer-encoding
x-amz-request-id
Date
Content-type

GET Bucket Website

The GET Bucket Website operation returns the web site configuration of a store, and requires GetBucketWebsite permission.

Request Syntax

GET /?website HTTP/1.1
Host: <store_name>.<host>
Date: <Date>
Authorization: <signatureValue>

Request Headers

You can use the following request headers with the GET Bucket Website operation:

(Required) Authorization (or Content-MD5)
(Required) Date
(Required) Host
Content-Length
Content-MD5
Content-Type
Expect
x-amz-date

Response Headers

Response headers in a GET Bucket Website operation may include:

Content-Length
Connection
Date
ETag
Server

GET Bucket ACL

The GET Bucket ACL operation returns the access control list for the BLOB store.

Request Syntax

GET /?acl HTTP/1.1
Host: <blobstore_url>
Date: <Date>
Authorization: <signatureValue>

Request Headers

You can use the following request headers for the GET Bucket ACL operation:

(Required) Authorization (or Content-MD5)
(Required) Date
(Required) Host
User-Agent
Query_string
Url_path
Method

Response Headers

The GET Bucket ACL operation may include the following response headers:

x-amz-id-2
Server
Transfer-encoding
x-amz-request-id
Date
Content-type

List Bucket Multipart Uploads

The GET Bucket Multipart Uploads operation returns a list of multipart uploads that are in progress (Initiate Multipart Upload request is made, but a Complete or Abort Multipart Upload request has not been made). To use this operation, you must have READ permission to the blobstore you specify.

Note: There is a limit of 10,000 multipart uploads in the list.

Request Syntax

GET /ObjectName?uploadId=UploadId HTTP/1.1
Host: <blobstore_url>
Date: <Date>
Authorization: <signatureValue>

Note: Host and date are required headers. You must include an upload ID parameter in the URL query string supplied with the GET request.

Request Headers

The List Bucket Multipart Uploads operation accepts all blobstore-api-ref.html#reference_728f4229-6ea0-481a-910f-422a5aab7da3.

Response Headers

The List Bucket Multipart Uploads operation may include any of the blobstore-api-ref.html#reference_e1bd3015-1cab-40e3-9780-1ae8d852add4.

Initiate Multipart Upload

Use the Initiate Multipart Upload operation to upload large objects (greater than 100 MB). This divides the large object into multiple partial uploads and returns a unique upload ID for each part of the object you will upload with the Upload Part request.

Request Syntax

The following shows the request syntax:

POST /ObjectName?uploads HTTP/1.1
Host: <blobstore_url>
Date: <Date>
Authorization: <signatureValue>

Request Headers

You must supply metadata that you want associated with the multipart object in the headers included with the Initiate Multipart Upload request. The Initiate Multipart Upload operation accepts the following request headers:

(Required) Date
(Required) Host
Cache-Control
Content-Disposition
Content-Encoding
Content-Length
Content-Type
x-amz-meta-
x-amz-storage-class

Response Headers

The Initiate Multipart Upload operation may include any of the common response headers.

Upload Part

Note: You must issue the Initiate Multipart Upload request before you can use the Upload Part operation as the upload ID returned by the Initiate Multipart Upload operation is required for the Upload Part operation.

You must define the upload ID and a part number with each Upload Part operation. Part numbers define the order in which parts in a List Parts operation are returned.

Note: If you upload multiple parts with the same part numbers, you must choose which of these parts should be used by including the right etag value in the Complete Multipart Upload request.

Request Syntax

PUT /ObjectName?partNumber=PartNumber&uploadId=UploadId HTTP/1.1
Host: <blobstore_url>
Date: <Date>
Content-Length: <Size>
Authorization: <signatureValue>

Except for the required PartNumber and uploadId parameters, no other request parameter is used with the Upload Part operation.

Request Headers

The Upload Part operation accepts all of the common response headers.

Note: If you include a Content-MD5 header in an Upload Part request, the data content of the part you are uploading is checked against the MD5 value sent in the header. If these do not match an error is returned.

Response Headers

The Upload Part operation always returns an ETag header and also may contain any of the common response headers.

The ETag values, along with the part numbers, must be included in the request to complete a multipart upload.

Abort Multipart Upload

AbortMultipartUpload cancels the multipart upload of an object before a CompleteMultipartUpload request has been issued for the object.

You must supply the upload ID of the object for which you are terminating the upload. Once you have issued a successful Abort MultipartUpload request, you can no longer send an UploadPart request with the same upload ID. Any parts already uploaded with this upload ID are removed from storage and the storage for those parts is freed.

Request Syntax

DELETE /ObjectName?uploadId=UploadId HTTP/1.1
Host: <blobstore_url>
Date: <Date>
Authorization: <signatureValue>

Request Headers

AbortMultipartUpload accepts all common request headers in addition to the required Host, Date, and Authorization headers.

Response Headers

AbortMultipartUpload may include any of the common response headers.

Response elements are not returned with this operation.

DELETE Object

Request Syntax

DELETE /ObjectName HTTP/1.1
Host: <blobstore_url>
Date: <Date>
Content-Length: <length>
Authorization: <signatureValue>

Request Headers

You can use the following request headers for the DELETE Object operation:

(Required) Authorization (or Content-MD5)
(Required) Date
(Required) Host
User-Agent
Query_string
Url_path

Response Headers

The DELETE Object operation may include the following response headers:

x-amz-id-2
Date
x-amz-request-id
Server

Common Request Headers


Header	Description	Operations	Usage	Signature
Authorization	Authenticates the requester.	All	Required, except for operations accessible to anonymous users.	Contains the signature.
Cache-control	Specifies directives that may override existing caching mechanisms and prevent caches from interfering with the HTTP request or response.	All	Optional	Not part of the signature computation.
Content-Length	Message length (without headers)	All	Required for PUT operations that load ACLs or other XML content.	Not part of the signature computation.
Content-MD5	Integrity check specifying a base64 encoded, 128-bit MD5 hash of the message without its headers, used to determine that the original data is returned unchanged.	PUT Object PUT Object acl	Optional	Used to compute the signature. If absent, include an empty line (\n) for this header in the signature computation.
Content-Type	Resource content type, for example, text/plain. Note: For PUT operations, default is binary/octet-stream, and valid values are MIME types.	All	Optional	Used to compute the signature. If absent, include an empty line (\n) for this header in the signature computation.
Date	Requester date and time, for example, `Tues, 14 Jun 2011 08:30:00 GMT`.	All	Required unless using x-amz-date and used as an `Expires` field for query string authentication.	Used to compute the signature. If using `x-amz-date`, include an empty line `(\n)` for the Date header, but also include the `x-amz-date` header in the signature computation. If using query string authentication,include the `Expires` time in place of the Date header in the signature computation.
Expect	Requests an acknowledgment before sending the message body when the sending application issues a 100-continue message; body not sent when its headers are refused.	PUT Object PUT Object acl	Optional	Not part of the signature computation.
Host	Host URI	All	Required	Not part of the signature computation.
Range	Requests the range bytes of an object.	GET Object Head Object	Optional	Not part of the signature computation.
x-amz-date	May be used in place of the HTTP Date header. If this header is present, an empty string is used for the date header in the StringToSign. The timestamp sent by the client must be within a 15 minute range of the server System Time. Otherwise, the request fails.	All	Optional	If present, used to compute the signature.
x-amz-meta	Metadata to be stored and returned with an object. The size of the HTTP request excluding the message body cannot exceed 8KB.	PUT Object PUT Object acl	Optional	If present, used to compute the signature.

Common Response Headers


Header	Type	Description
Content-Length	String	Length of the response body in bytes.
Connection	Enum	Indicates whether there is an open connection to the server. Values include: value = open value = close
Date	String	Date and time of the response.
ETag	String	The entity tag for an object that is an MD5 hash of the object contents, but not its metadata.
Server	String	Name of server sending the response.
x-amz-request-id	String	Uniquely identifies the request.
x-amz-id-2	String	A token that can help troubleshoot issues.
Last-modified	Date	Date and time the object was last modified.
Content-type		Resource content type, for example, text/plain.
x-amz-meta-*	String	Returns user metadata entered with the x-amz-meta- (plus suffix) header. Available with HEAD Object operations only.
x-amz-meta-crc	String	Partial CRC of the object. The associated range is stored in x-amz-meta-crc-range. Available with GET Object and HEAD Object operations.