-
Notifications
You must be signed in to change notification settings - Fork 274
Rest API
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.
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.
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).
The location of the created blob on success.
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.
See standard error codes.
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
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.
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 |
The content of the blob.
The user metadata as response headers.
The user metadata and blob properties as response headers.
The location of the all the replicas that have the blob including hostname, port and mount path
The chunk blob Ids for composite blob.
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}
|
The body of the response will contain the content of the blob.
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 |
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. |
The body of the response will contain a JSON listing all the replicas that contain the blob
The body of the response will contain a JSON listing all the blob chunk Ids for the composite blob.
See standard error codes.
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>
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>
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
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
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 48
...
{"replicas":["Replica[localhost:15088:/tmp/1]"]}
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"]}
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
If the blob is private, the cache headers returned in the response will indicate that the content should not be cached or stored.
This API gets the blob properties of the blob represented by the supplied blob ID.
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 |
The blob properties of the blob as response headers.
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. |
See standard error codes.
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
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
This API deletes the blob represented by the supplied blob ID.
DELETE /<ambry-id>
| Parameter | Type | Required? | Description |
|---|---|---|---|
| ambry-id | String | Yes | The ID of the blob that has to be deleted |
Success is indicated by the status code 202 Accepted. Note that deleting blobs that are already deleted will succeed without any errors.
See standard error codes.
HTTP/1.1 202 Accepted
Date: Sun, 01 May 2016 05:44:04 GMT
Content-Length: 0
This API removes a blob's TTL and makes it permanent.
PUT /updateTtl
| Request Header | Type | Required? | Description |
|---|---|---|---|
| x-ambry-blob-id | String | Yes | The blob id |
Success is indicated by the status code 200 OK. One blob can't be updateTtl-ed more than once.
See standard error codes.
HTTP/1.1 200 OK
Date: Sun, 01 May 2016 05:44:04 GMT
Content-Length: 0
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.
PUT /undelete
| Request Header | Type | Required? | Description |
|---|---|---|---|
| x-ambry-blob-id | String | Yes | The blob id |
Success is indicated by the status code 200 OK.
See standard error codes.
HTTP/1.1 200 OK
Date: Sun, 01 May 2016 05:44:04 GMT
Content-Length: 0
This API can be used to check the status of the frontend. Status here refers to the frontend's ability to answer requests.
GET /healthCheck
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.
None
HTTP/1.1 200 OK
Content-Length: 4
GOOD
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>
| 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.
| 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 |
| 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 |
- Getting Started
- API
- Configuration
- Design
- Implementation
- Operations
- FAQ
- Project
- Future Work