Skip to content

Rest API

sopguo edited this page Sep 27, 2022 · 25 revisions

At a high level, Ambry supports POST, GET, DELETE and HEAD. This document describes all the APIs related to blob operations and health check in detail.


POST

Description

This API uploads a blob to Ambry. The call should also include some necessary blob properties and can include optional user metadata. The API returns a resource ID that can be used to access the blob.

API

POST /
Request Header Type Required? Description
x-ambry-target-account-name String Yes The account to which the blob belongs
x-ambry-target-container-name String Yes The container within the account to which the blob belongs
x-ambry-service-id String Yes The ID of the service that is uploading the blob
x-ambry-content-type String Yes The type of content in the blob
x-ambry-blob-size Long No The size of the blob being uploaded
x-ambry-ttl Long No The time in seconds for which the blob is valid. Defaults to -1 (infinite validity)
x-ambry-private Boolean No Makes the blob private if set to true. Defaults to false (blob is public)
x-ambry-owner-id String No The owner of the blob.
x-ambry-um- String No User metadata headers prefix. Any number of headers with this prefix are allowed.

The actual content of the blob is to be sent in the body as a stream of bytes (without any encoding).

Returns

The location of the created blob on success.

Success response

The status code 201 Created indicates that the blob was successfully uploaded. The response also contains the "Location" header that contains the ID of the blob.

Failure response

See standard error codes.

Sample Response

HTTP/1.1 201 Created
Date: Sun, 01 May 2016 05:35:21 GMT
Location: /AAEAAQAAAAAAAAAAAAAAJDk3NDI2MmQ1LTU0YzktNDk5OC1iM2Q5LTE1ZTQ5NDYwNjI0Mw
Content-Length: 0
x-ambry-creation-time: Sun, 01 May 2016 05:35:21 GMT

GET

Description

This API gets the content of the blob represented by the blob ID. When used with sub-resources, it gets user metadata (and optionally blob properties) instead of the actual content of the blob. The API also supports advanced user operations like getting the server replica list for a blob and getting expired/deleted blobs if they are still available in storage.

API

GET /<ambry-id>/<sub-resource>
Sub-resources: BlobInfo, UserMetadata, Replicas
Parameter Type Required? Description
ambry-id String Yes The ID of the blob whose content is requested
sub-resource String No One of the listed sub-resources
Request Header Type Required? Description
Range byte range No The byte range to be returned ([[details
x-ambry-get-option String No See [[options

Returns

Without sub-resources

The content of the blob.

UserMetadata

The user metadata as response headers.

BlobInfo

The user metadata and blob properties as response headers.

Replicas

The location of the all the replicas that have the blob including hostname, port and mount path

BlobChunkIds

The chunk blob Ids for composite blob.

Success response

A successful response for non-range requests is indicated by the status code 200 OK. A successful response for range requests is indicated by the status code 206 Partial Content. In the case of a partial content response, the following response header will be populated.

Response Header Type Description
Content-Range String The range of bytes returned in this response in the form bytes {start_offset}-{end_offset}/{total object size}
Without sub-resources

The body of the response will contain the content of the blob.

UserMetadata

The response headers will contain the user metadata that was uploaded (if any). Any user metadata value that requires URL-encoding (e.g. it contain newline chars) will have a special header prefix, and the requesting client will need to perform URL-decoding to obtain the original value.

Response Header Type Description
x-ambry-um- String Zero or more headers with this prefix that represent user metadata
x-ambry-enc-um- String Zero or more headers with this prefix that represent user metadata with encoded values
BlobInfo

The response headers will contain the user metadata that was uploaded (if any) and the properties of the blob.

Response Header Type Description
x-ambry-target-account-name String The account to which the blob belongs
x-ambry-targer-container-name String The container within the account to which the blob belongs
x-ambry-blob-size Long The size of the blob
x-ambry-service-id String The ID of the service that uploaded the blob
x-ambry-content-type String The type of content in the blob
x-ambry-encrypted-in-storage Boolean true if the blob is encrypted at rest. false otherwise
x-ambry-private Boolean true if the blob is private. false if the blob is public
x-ambry-creation-time Long The time at which the blob was created
x-ambry-ttl (if supplied at upload) Long The time in seconds for which the blob is valid from its creation time
x-ambry-owner-id (if supplied at upload) String The owner of the blob.
x-ambry-um- (if supplied at upload) String Zero or more headers with this prefix that represent user metadata
x-ambry-enc-um- String Zero or more headers with this prefix that represent user metadata with encoded values.
Replicas

The body of the response will contain a JSON listing all the replicas that contain the blob

BlobChunkIds

The body of the response will contain a JSON listing all the blob chunk Ids for the composite blob.

Failure response

See standard error codes.

Sample Response

Without sub-resources
HTTP/1.1 200 OK
Date: Sun, 01 May 2016 05:36:41 GMT
Last-Modified: Sun, 01 May 2016 05:35:21 GMT
x-ambry-blob-size: 2000
Content-Type: image/gif
Expires: Mon, 01 May 2017 05:36:41 GMT
Cache-Control: max-age=31536000
Accept-Ranges: bytes
Transfer-Encoding: chunked

<file-content>
For a range request without sub-resources (for bytes 25 through 700)
HTTP/1.1 206 Partial Content
Date: Sun, 01 May 2016 05:36:41 GMT
Last-Modified: Sun, 01 May 2016 05:35:21 GMT
x-ambry-blob-size: 2000
Content-Type: image/gif
Expires: Mon, 01 May 2017 05:36:41 GMT
Cache-Control: max-age=31536000
Accept-Ranges: bytes
Content-Range: bytes 25-700/2000
Transfer-Encoding: chunked

<file-content>
BlobInfo
HTTP/1.1 200 OK
Date: Sun, 01 May 2016 05:38:47 GMT
Last-Modified: Sun, 01 May 2016 05:35:21 GMT
x-ambry-target-account-name : API-Demo
x-ambry-targer-container-name : Demo
x-ambry-blob-size: 2000
x-ambry-service-id: API-Demo
x-ambry-creation-time: Sun, 01 May 2016 05:35:21 GMT
x-ambry-private: false
x-ambry-content-type: image/gif
x-ambry-owner-id: demo-user
x-ambry-um-description: Demonstration Image
x-ambry-um-filename: Eiffel%0DTower
Content-Length: 0
UserMetadata
HTTP/1.1 200 OK
Date: Sun, 01 May 2016 05:39:51 GMT
Last-Modified: Sun, 01 May 2016 05:35:21 GMT
x-ambry-um-description: Demonstration Image
x-ambry-um-filename: Eiffel%0DTower
Content-Length: 0
Replicas
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 48
...
{"replicas":["Replica[localhost:15088:/tmp/1]"]}
BlobChunkIds
 HTTP/1.1 200 OK
 Date: Tue, 27 Sep 2022 22:53:34 GMT
 Last-Modified: Tue, 27 Sep 2022 22:52:54 GMT
 ...
 {"blobChunkIds":["AAYQAQSTAAoAAQAAAAAAAC8CB6YATdRSQxOoxawVrs---w","AAYQAQSTAAoAAQAAAAAAAEvj5ROXPHWFRtS24Fv69sYlkw"]}

Other

Not Modified

GET of blob content supports the "If-Modified-Since" header and returns 304 Not_Modified if the blob has not been modified since the time specified

Private Blobs

If the blob is private, the cache headers returned in the response will indicate that the content should not be cached or stored.


HEAD

Description

This API gets the blob properties of the blob represented by the supplied blob ID.

API

HEAD /<ambry-id>
Parameter Type Required? Description
ambry-id String Yes The ID of the blob whose properties are requested
Request Header Type Required? Description
Range byte range No The byte range requested ([[details
x-ambry-get-option String No See [[options

Returns

The blob properties of the blob as response headers.

Success response

A successful response is indicated by the status code 200 OK, or 206 Partial Content for a range request. The response will also contain headers that describe the properties of the blob.

Response Header Type Description
x-ambry-target-account-name String The account to which the blob belongs
x-ambry-targer-container-name String The container within the account to which the blob belongs
x-ambry-blob-size Long The size of the blob
x-ambry-service-id String The ID of the service that uploaded the blob
x-ambry-content-type String The type of content in the blob
x-ambry-encrypted-in-storage Boolean true if the blob is encrypted at rest. false otherwise
x-ambry-private Boolean true if the blob is private. false if the blob is public
x-ambry-creation-time Long The time at which the blob was created
x-ambry-ttl (if supplied at upload) Long The time in seconds for which the blob is valid from its creation time
x-ambry-owner-id (if supplied at upload) String The owner of the blob.
Failure response

See standard error codes.

Sample Response

Without a range specified
HTTP/1.1 200 OK
Date: Sun, 01 May 2016 05:41:12 GMT
Last-Modified: Sun, 01 May 2016 05:35:21 GMT
Accept-Ranges: bytes
Content-Length: 2000
Content-Type: image/gif
x-ambry-target-account-name : API-Demo
x-ambry-targer-container-name : Demo
x-ambry-blob-size: 2000
x-ambry-service-id: API-Demo
x-ambry-creation-time: Sun, 01 May 2016 05:35:21 GMT
x-ambry-private: false
x-ambry-content-type: image/gif
x-ambry-owner-id: demo-user
With a range specified (for bytes 25 through 700)
HTTP/1.1 206 Partial Content
Date: Sun, 01 May 2016 05:41:12 GMT
Last-Modified: Sun, 01 May 2016 05:35:21 GMT
Accept-Ranges: bytes
Content-Range: bytes 25-700/2000
Content-Length: 676
Content-Type: image/gif
x-ambry-target-account-name : API-Demo
x-ambry-targer-container-name : Demo
x-ambry-blob-size: 2000
x-ambry-service-id: API-Demo
x-ambry-creation-time: Sun, 01 May 2016 05:35:21 GMT
x-ambry-private: false
x-ambry-content-type: image/gif
x-ambry-owner-id: demo-user

DELETE

Description

This API deletes the blob represented by the supplied blob ID.

API

DELETE /<ambry-id>
Parameter Type Required? Description
ambry-id String Yes The ID of the blob that has to be deleted

Returns

Success response

Success is indicated by the status code 202 Accepted. Note that deleting blobs that are already deleted will succeed without any errors.

Failure response

See standard error codes.

Sample Response

HTTP/1.1 202 Accepted
Date: Sun, 01 May 2016 05:44:04 GMT
Content-Length: 0

UpdateTtl(PUT)

Description

This API removes a blob's TTL and makes it permanent.

API

PUT /updateTtl
Request Header Type Required? Description
x-ambry-blob-id String Yes The blob id

Returns

Sucess response

Success is indicated by the status code 200 OK. One blob can't be updateTtl-ed more than once.

Failure response

See standard error codes.

Sample Response

HTTP/1.1 200 OK
Date: Sun, 01 May 2016 05:44:04 GMT
Content-Length: 0

Undelete(PUT)

Description

This API undeletes a deleted blob represented by the supplied blob ID. Undelete is considered as an administrative operation, that shouldn't be used as client API. This document just shows the HTTP interface of Undelete operation.

API

PUT /undelete
Request Header Type Required? Description
x-ambry-blob-id String Yes The blob id

Returns

Sucess response

Success is indicated by the status code 200 OK.

Failure response

See standard error codes.

Sample Response

HTTP/1.1 200 OK
Date: Sun, 01 May 2016 05:44:04 GMT
Content-Length: 0

Health Check

Description

This API can be used to check the status of the frontend. Status here refers to the frontend's ability to answer requests.

API

GET /healthCheck

Returns

Success response

A successful response will be returned with a status code of 200 OK and the body of the response will contain the status of frontend - GOOD/BAD.

Failure response

None

Sample Response

HTTP/1.1 200 OK
Content-Length: 4

GOOD

Range Header

The Range header allows the user to specify a range of bytes within the blob to be returned. It is only valid for GET requests without sub-resources and for HEAD requests. It accepts the following syntax, described in this RFC document:

  • Range:bytes=<a>-<b> for bytes from <a> to <b>, inclusive
  • Range:bytes=-<n> for the last <n> bytes
  • Range:bytes=<a>- for all bytes including and after <a>

Get Options

Option Description
None No special options (default)
Include_Deleted_Blobs Returns the data of the blob even if it has been deleted (see note)
Include_Expired_Blobs Returns the data of the blob even if it has expired (see note)
Include_All Returns the data of the blob even if it has been deleted or has expired (see note)

Note: Deleted or expired blobs may have been cleaned up by the storage due to hard delete or compaction and the data may no longer be available. These options return the blob if it is still exists on the storage server.

Standard Error Codes

Status Code Description
400 Bad_Request The request does not contain required parameters or has incorrect parameters. The body of the response usually has a helpful error message
401 Unauthorized The request does not contain enough information to authenticate the operation
403 Forbidden The requested blob cannot be served either because the user is not authorized or the resource is dirty
404 Not_Found The requested resource was not found
407 Proxy_Authentication_Required The resource cannot be served just yet because it (or the user) needs proxy authentication
410 Gone The requested resource is either deleted or has expired
416 Range_Not_Satisfiable The requested range exceeded the size of the blob
500 Internal_Server_Error The server experienced an error while serving the request

Common Failure Headers

Response Header Type Description
x-ambry-failure-reason String If the status code was 400, contains the reason
x-ambry-error-code String On 4xx status codes, this contains the RestServiceErrorCode associated with the error
Clone this wiki locally