S3 API

S3 API Reference

This document provides a detailed reference for the Alluxio S3 API, which allows you to interact with Alluxio using the popular Amazon S3 protocol. The examples provided use both the AWS CLI and standard REST clients like curl.

Bucket Operations

CreateBucket

Creates a new bucket in Alluxio.

Method: PUT

Path: /{bucket}

Responses:

200 - OK: The bucket was created successfully.

Examples:

AWS CLI

$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api create-bucket \
  --bucket=testbucket

$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api list-buckets
{
    "Buckets": [
        {
            "Name": "testbucket",
            "CreationDate": "2022-05-03T11:32:34.156000+00:00"
        }
    ]
}

REST Client

$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
  -X PUT http://localhost:29998/testbucket

HTTP/1.1 200 OK
Date: Tue, 03 May 2022 21:35:05 GMT
Content-Length: 0
Server: Jetty(9.4.43.v20210629)

$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
  -X GET http://localhost:29998/
HTTP/1.1 200 OK
Date: Tue, 03 May 2022 21:35:23 GMT
Content-Type: application/xml
Content-Length: 161
Server: Jetty(9.4.43.v20210629)

<ListAllMyBucketsResult>
  <Buckets>
    <Bucket>
      <Name>testbucket</Name>
      <CreationDate>2022-05-03T14:34:56.420Z</CreationDate>
    </Bucket>
  </Buckets>
</ListAllMyBucketsResult>

DeleteBucket

Deletes an existing bucket. The bucket must be empty before it can be deleted.

Method: DELETE

Path: /{bucket}

Responses:

204 - No Content: The bucket was deleted successfully.

Examples:

AWS CLI

$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api list-buckets
{
    "Buckets": [
        {
            "Name": "tempbucket",
            "CreationDate": "2022-05-03T11:55:58.134000+00:00"
        },
        {
            "Name": "testbucket",
            "CreationDate": "2022-05-03T11:32:34.156000+00:00"
        }
    ]
}

$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api delete-bucket \
  --bucket=tempbucket

$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api list-buckets
{
    "Buckets": [
        {
            "Name": "testbucket",
            "CreationDate": "2022-05-03T11:32:34.156000+00:00"
        }
    ]
}

REST Client

$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
  -X GET http://localhost:29998/
HTTP/1.1 200 OK
Date: Tue, 03 May 2022 21:43:20 GMT
Content-Type: application/xml
Content-Length: 254
Server: Jetty(9.4.43.v20210629)

<ListAllMyBucketsResult>
  <Buckets>
    <Bucket>
      <Name>tempbucket</Name>
      <CreationDate>2022-05-03T14:43:03.651Z</CreationDate>
    </Bucket>
    <Bucket>
      <Name>testbucket</Name>
      <CreationDate>2022-05-03T14:34:56.420Z</CreationDate>
    </Bucket>
  </Buckets>
</ListAllMyBucketsResult>

$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
  -X DELETE http://localhost:29998/tempbucket
HTTP/1.1 204 No Content
Date: Tue, 03 May 2022 21:43:25 GMT
Server: Jetty(9.4.43.v20210629)

$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
  -X GET http://localhost:29998/
HTTP/1.1 200 OK
Date: Tue, 03 May 2022 21:43:28 GMT
Content-Type: application/xml
Content-Length: 161
Server: Jetty(9.4.43.v20210629)

<ListAllMyBucketsResult>
  <Buckets>
    <Bucket>
      <Name>testbucket</Name>
      <CreationDate>2022-05-03T14:34:56.420Z</CreationDate>
    </Bucket>
  </Buckets>
</ListAllMyBucketsResult>

ListBuckets

Lists all buckets owned by the sender of the request.

Method: GET

Path: /

Responses:

200 - OK: Returns an XML document containing a list of buckets.

Examples:

AWS CLI

$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api list-buckets
{
    "Buckets": [
        {
            "Name": "testbucket",
            "CreationDate": "2022-05-03T11:32:34.156000+00:00"
        }
    ]
}

REST Client

$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
  -X GET http://localhost:29998/
HTTP/1.1 200 OK
Date: Tue, 03 May 2022 21:35:23 GMT
Content-Type: application/xml
Content-Length: 161
Server: Jetty(9.4.43.v20210629)

<ListAllMyBucketsResult>
  <Buckets>
    <Bucket>
      <Name>testbucket</Name>
      <CreationDate>2022-05-03T14:34:56.420Z</CreationDate>
    </Bucket>
  </Buckets>
</ListAllMyBucketsResult>

HeadBucket

This operation is useful to determine if a bucket exists and you have permission to access it.

Method: HEAD

Path: /{bucket}

Responses:

200 - OK: The bucket exists and you have permission to access it.
404 - Not Found: The bucket does not exist.

Examples:

AWS CLI

$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api head-bucket \
  --bucket=testbucket

REST Client

$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
  --head http://localhost:29998/testbucket
HTTP/1.1 200 OK
Date: Tue, 15 Nov 2022 04:49:12 GMT
Content-Type: application/xml
Content-Length: 0
Server: Jetty(9.4.43.v20210629)

GetBucketTagging

Retrieves the tags associated with a bucket.

Method: GET

Path: /{bucket}?tagging

Responses:

200 - OK: Returns an XML document with the tag set.

Examples:

AWS CLI

$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api get-bucket-tagging \
  --bucket=testbucket
{
    "TagSet": [
        {
            "Key": "key1",
            "Value": "val1"
        },
        {
            "Key": "key2",
            "Value": "val2"
        }
    ]
}

REST Client

$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
  -X GET "http://localhost:29998/testbucket?tagging"
HTTP/1.1 200 OK
Date: Tue, 03 May 2022 23:31:07 GMT
Content-Type: application/xml
Content-Length: 124
Server: Jetty(9.4.43.v20210629)

<Tagging>
  <TagSet>
    <Tag>
      <Key>key1</Key>
      <Value>val1</Value>
    </Tag>
    <Tag>
      <Key>key2</Key>
      <Value>val2</Value>
    </Tag>
  </TagSet>
</Tagging>

PutBucketTagging

Adds a set of tags to an existing bucket.

Method: PUT

Path: /{bucket}?tagging

Request Body: An XML document containing the tag set.

Responses:

200 - OK: The tags were added successfully.

Examples:

AWS CLI

$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api get-bucket-tagging \
  --bucket=testbucket
{
    "TagSet": []
}

$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api put-bucket-tagging \
  --bucket=testbucket --tagging='TagSet=[{Key=key1,Value=val1},{Key=key2,Value=val2}]'

$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api get-bucket-tagging \
  --bucket=testbucket
{
    "TagSet": [
        {
            "Key": "key1",
            "Value": "val1"
        },
        {
            "Key": "key2",
            "Value": "val2"
        }
    ]
}

REST Client

$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
  -X GET "http://localhost:29998/testbucket?tagging"
HTTP/1.1 200 OK
Date: Tue, 03 May 2022 23:30:25 GMT
Content-Type: application/xml
Content-Length: 28
Server: Jetty(9.4.43.v20210629)

<Tagging><TagSet/></Tagging>

$ cat tags.xml
<Tagging>
  <TagSet>
    <Tag>
      <Key>key1</Key>
      <Value>val1</Value>
    </Tag>
    <Tag>
      <Key>key2</Key>
      <Value>val2</Value>
    </Tag>
  </TagSet>
</Tagging>

$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
  -H "Content-Type: application/xml" \
  -X PUT "http://localhost:29998/testbucket?tagging" --data-binary "@tags.xml"
HTTP/1.1 200 OK
Date: Tue, 03 May 2022 23:31:05 GMT
Content-Length: 0
Server: Jetty(9.4.43.v20210629)

$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
  -X GET "http://localhost:29998/testbucket?tagging"
HTTP/1.1 200 OK
Date: Tue, 03 May 2022 23:31:07 GMT
Content-Type: application/xml
Content-Length: 124
Server: Jetty(9.4.43.v20210629)

<Tagging>
  <TagSet>
    <Tag>
      <Key>key1</Key>
      <Value>val1</Value>
    </Tag>
    <Tag>
      <Key>key2</Key>
      <Value>val2</Value>
    </Tag>
  </TagSet>
</Tagging>

DeleteBucketTagging

Deletes the tags from a bucket.

Method: DELETE

Path: /{bucket}?tagging

Responses:

204 - No Content: The tags were deleted successfully.

Examples:

AWS CLI

$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api get-bucket-tagging \
  --bucket=testbucket
{
    "TagSet": [
        {
            "Key": "key1",
            "Value": "val1"
        },
        {
            "Key": "key2",
            "Value": "val2"
        }
    ]
}

$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api delete-bucket-tagging \
  --bucket=testbucket

$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api get-bucket-tagging \
  --bucket=testbucket
{
    "TagSet": []
}

REST Client

$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
  -X GET "http://localhost:29998/testbucket?tagging"
HTTP/1.1 200 OK
Date: Tue, 03 May 2022 23:31:07 GMT
Content-Type: application/xml
Content-Length: 124
Server: Jetty(9.4.43.v20210629)

<Tagging>
  <TagSet>
    <Tag>
      <Key>key1</Key>
      <Value>val1</Value>
    </Tag>
    <Tag>
      <Key>key2</Key>
      <Value>val2</Value>
    </Tag>
  </TagSet>
</Tagging>

$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
  -X DELETE "http://localhost:29998/testbucket?tagging"
HTTP/1.1 204 No Content
Date: Tue, 03 May 2022 23:32:26 GMT
Server: Jetty(9.4.43.v20210629)

$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
  -X GET "http://localhost:29998/testbucket?tagging"
HTTP/1.1 200 OK
Date: Tue, 03 May 2022 23:32:27 GMT
Content-Type: application/xml
Content-Length: 28
Server: Jetty(9.4.43.v20210629)

<Tagging><TagSet/></Tagging>

Object Operations

GetObject

Retrieves an object from a bucket.

Method: GET

Path: /{bucket}/{key}

Responses:

200 - OK: The object data is returned in the response body.

Examples:

AWS CLI

$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api get-object \
  --bucket=testbucket --key=test.txt /tmp/test.txt
{
    "LastModified": "2022-05-03T18:55:01+00:00",
    "ContentLength": 27040,
    "ETag": "0cc175b9c0f1b6a831c399e269772661",
    "ContentType": "application/octet-stream",
    "Metadata": {}
}

$ stat /tmp/test.txt
  File: /tmp/test.txt
  Size: 27040       Blocks: 56         IO Block: 4096   regular file
  ...

REST Client

$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
  -X GET http://localhost:29998/testbucket/test.txt
HTTP/1.1 200 OK
Date: Tue, 03 May 2022 22:59:43 GMT
Last-Modified: Tue, 03 May 2022 21:47:36 GMT
ETag: 0cc175b9c0f1b6a831c399e269772661
Content-Type: application/octet-stream
Content-Length: 27040
Server: Jetty(9.4.43.v20210629)

................. file contents .................

PutObject

Adds an object to a bucket.

Method: PUT

Path: /{bucket}/{key}

Request Body: The object content.

Responses:

200 - OK: The object was uploaded successfully.

Examples:

AWS CLI

$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api put-object \
  --bucket=testbucket --key=test.txt --body="${ALLUXIO_HOME}/LICENSE"
{
    "ETag": "911df44b7ff57801ca8d74568e4ebfbe"
}

$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api list-objects \
  --bucket=testbucket
{
    "Contents": [
        {
            "Key": "test.txt",
            "LastModified": "2022-05-03T11:35:59.243000+00:00",
            "Size": 27040
        }
    ]
}

REST Client

$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
  -X PUT http://localhost:29998/testbucket/test.txt -T "${ALLUXIO_HOME}/LICENSE"
HTTP/1.1 100 Continue

HTTP/1.1 200 OK
Date: Tue, 03 May 2022 21:47:36 GMT
ETag: 911df44b7ff57801ca8d74568e4ebfbe
Content-Length: 0
Server: Jetty(9.4.43.v20210629)

$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
  -X GET http://localhost:29998/testbucket
HTTP/1.1 200 OK
Date: Tue, 03 May 2022 21:47:44 GMT
Content-Type: application/xml
Content-Length: 318
Server: Jetty(9.4.43.v20210629)

<ListBucketResult>
  <version2>false</version2>
  <Contents>
    <Key>test.txt</Key>
    <Size>27040</Size>
    <LastModified>2022-05-03T14:47:36.600Z</LastModified>
  </Contents>
  <Marker/>
  <IsTruncated>false</IsTruncated>
  <Prefix/>
  <Name>testbucket</Name>
  <MaxKeys>1000</MaxKeys>
  <EncodingType>url</EncodingType>
</ListBucketResult>

CopyObject

Creates a copy of an object that is already stored in Alluxio.

Method: PUT

Path: /{bucket}/{key}

Request Headers:

x-amz-copy-source: The name of the source bucket and key, separated by a slash (/).

Responses:

200 - OK: Returns an XML document with the result of the copy operation.

Examples:

AWS CLI

$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api copy-object \
  --copy-source=testbucket/test.txt --bucket=testbucket --key=test_copy.txt
{
    "CopyObjectResult": {
        "ETag": "911df44b7ff57801ca8d74568e4ebfbe",
        "LastModified": "2022-05-03T11:37:16.015000+00:00"
    }
}

$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api list-objects \
  --bucket=testbucket
{
    "Contents": [
        {
            "Key": "test.txt",
            "LastModified": "2022-05-03T11:35:59.243000+00:00",
            "Size": 27040
        },
        {
            "Key": "test_copy.txt",
            "LastModified": "2022-05-03T11:37:16.185000+00:00",
            "Size": 27040
        }
    ]
}

REST Client

$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
  -H "x-amz-copy-source: testbucket/test.txt" \
  -X PUT http://localhost:29998/testbucket/test_copy.txt
HTTP/1.1 200 OK
Date: Tue, 03 May 2022 21:50:07 GMT
Content-Type: application/xml
Content-Length: 135
Server: Jetty(9.4.43.v20210629)

<CopyObjectResult>
  <ETag>911df44b7ff57801ca8d74568e4ebfbe</ETag>
  <LastModified>2022-05-03T14:50:07.781Z</LastModified>
</CopyObjectResult>

$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
  -X GET http://localhost:29998/testbucket
HTTP/1.1 200 OK
Date: Tue, 03 May 2022 21:50:26 GMT
Content-Type: application/xml
Content-Length: 434
Server: Jetty(9.4.43.v20210629)

<ListBucketResult>
  <version2>false</version2>
  <Contents>
    <Key>test.txt</Key>
    <Size>27040</Size>
    <LastModified>2022-05-03T14:47:36.600Z</LastModified>
  </Contents>
  <Contents>
    <Key>test_copy.txt</Key>
    <Size>27040</Size>
    <LastModified>2022-05-03T14:50:07.790Z</LastModified>
  </Contents>
  <Marker/>
  <IsTruncated>false</IsTruncated>
  <Prefix/>
  <Name>testbucket</Name>
  <MaxKeys>1000</MaxKeys>
  <EncodingType>url</EncodingType>
</ListBucketResult>

DeleteObject

Removes an object from a bucket.

Method: DELETE

Path: /{bucket}/{key}

Responses:

204 - No Content: The object was deleted successfully.

Examples:

AWS CLI

$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api list-objects-v2 \
  --bucket=testbucket
{
    "Contents": [
        {
            "Key": "temp.txt",
            "LastModified": "2022-05-03T11:55:01.925000+00:00",
            "Size": 27040
        },
        {
            "Key": "test.txt",
            "LastModified": "2022-05-03T11:54:19.698000+00:00",
            "Size": 27040
        }
    ]
}

$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api delete-object \
  --bucket=testbucket --key=temp.txt

$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api list-objects-v2 \
  --bucket=testbucket
{
    "Contents": [
        {
            "Key": "test.txt",
            "LastModified": "2022-05-03T11:55:01.925000+00:00",
            "Size": 27040
        }
    ]
}

REST Client

$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
  -X GET http://localhost:29998/testbucket
HTTP/1.1 200 OK
Date: Tue, 03 May 2022 21:59:27 GMT
Content-Type: application/xml
Content-Length: 540
Server: Jetty(9.4.43.v20210629)

<ListBucketResult>
  <version2>false</version2>
  <Contents>
    <Key>temp.txt</Key>
    <Size>27040</Size>
    <LastModified>2022-05-03T14:50:07.790Z</LastModified>
  </Contents>
  <Contents>
    <Key>test.txt</Key>
    <Size>27040</Size>
    <LastModified>2022-05-03T14:47:36.600Z</LastModified>
  </Contents>
  <Marker/>
  <IsTruncated>false</IsTruncated>
  <Prefix/>
  <Name>testbucket</Name>
  <MaxKeys>1000</MaxKeys>
  <EncodingType>url</EncodingType>
</ListBucketResult>

$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
  -X DELETE http://localhost:29998/testbucket/temp.txt
HTTP/1.1 204 No Content
Date: Tue, 03 May 2022 22:01:56 GMT
Server: Jetty(9.4.43.v20210629)

$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
  -X GET http://localhost:29998/testbucket
HTTP/1.1 200 OK
Date: Tue, 03 May 2022 22:01:59 GMT
Content-Type: application/xml
Content-Length: 318
Server: Jetty(9.4.43.v20210629)

<ListBucketResult>
  <version2>false</version2>
  <Contents>
    <Key>test.txt</Key>
    <Size>27040</Size>
    <LastModified>2022-05-03T14:47:36.600Z</LastModified>
  </Contents>
  <Marker/>
  <IsTruncated>false</IsTruncated>
  <Prefix/>
  <Name>testbucket</Name>
  <MaxKeys>1000</MaxKeys>
  <EncodingType>url</EncodingType>
</ListBucketResult>

DeleteObjects

Removes multiple objects from a bucket in a single request.

Method: POST

Path: /{bucket}?delete

Request Body: An XML document specifying the keys of the objects to delete.

<Delete>
  <Object>
    <Key>key_1</Key>
  </Object>
  <Object>
    <Key>key_2</Key>
  </Object>
  ...
</Delete>

Responses:

200 - OK: Returns an XML document with the results of the delete operation for each object.

Examples:

AWS CLI

$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api list-objects-v2 \
  --bucket=tempbucket
{
    "Contents": [
        {
            "Key": "foo.txt",
            "LastModified": "2022-05-03T11:57:00.767000+00:00",
            "Size": 27040
        },
        {
            "Key": "temp.txt",
            "LastModified": "2022-05-03T11:56:11.245000+00:00",
            "Size": 27040
        },
        {
            "Key": "temp2.txt",
            "LastModified": "2022-05-03T11:56:31.414000+00:00",
            "Size": 27040
        }
    ]
}

$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api delete-objects \
  --bucket=tempbucket --delete="Objects=[{Key=temp.txt},{Key=temp2.txt}]"

$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api list-objects-v2 \
  --bucket=tempbucket
{
    "Contents": [
        {
            "Key": "foo.txt",
            "LastModified": "2022-05-03T11:57:00.767000+00:00",
            "Size": 27040
        }
    ]
}

REST Client

$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
  -X GET http://localhost:29998/tempbucket
HTTP/1.1 200 OK
Date: Tue, 03 May 2022 21:59:27 GMT
Content-Type: application/xml
Content-Length: 540
Server: Jetty(9.4.43.v20210629)

<ListBucketResult>
  <version2>false</version2>
  <Contents>
    <Key>foo.txt</Key>
    <Size>27040</Size>
    <LastModified>2022-05-03T14:59:05.906Z</LastModified>
  </Contents>
  <Contents>
    <Key>temp.txt</Key>
    <Size>27040</Size>
    <LastModified>2022-05-03T14:58:58.204Z</LastModified>
  </Contents>
  <Contents>
    <Key>temp2.txt</Key>
    <Size>27040</Size>
    <LastModified>2022-05-03T14:59:01.987Z</LastModified>
  </Contents>
  <Marker/>
  <IsTruncated>false</IsTruncated>
  <Prefix/>
  <Name>tempbucket</Name>
  <MaxKeys>1000</MaxKeys>
  <EncodingType>url</EncodingType>
</ListBucketResult>

$ cat delete.xml
<Delete xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <Object>
    <Key>temp.txt</Key>
  </Object>
  <Object>
    <Key>temp2.txt</Key>
  </Object>
  <Quiet>false</Quiet>
</Delete>

$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
  -H "Content-Type: application/xml" \
  -X POST --data "@delete.xml" "http://localhost:29998/testbucket?delete"
HTTP/1.1 200 OK
Date: Tue, 03 May 2022 22:56:17 GMT
Content-Type: application/xml
Content-Length: 208
Server: Jetty(9.4.43.v20210629)

<DeleteResult>
  <Deleted>
    <Key>temp2.txt</Key>
    <DeleteMarker/>
    <DeleteMarkerVersionId/>
    <VersionId/>
  </Deleted>
  <Deleted>
    <Key>temp.txt</Key>
    <DeleteMarker/>
    <DeleteMarkerVersionId/>
    <VersionId/>
  </Deleted>
</DeleteResult>

$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
  -X GET http://localhost:29998/tempbucket
HTTP/1.1 200 OK
Date: Tue, 03 May 2022 22:28:31 GMT
Content-Type: application/xml
Content-Length: 317
Server: Jetty(9.4.43.v20210629)

<ListBucketResult>
  <version2>false</version2>
  <Contents>
    <Key>foo.txt</Key>
    <Size>27040</Size>
    <LastModified>2022-05-03T14:59:05.906Z</LastModified>
  </Contents>
  <Marker/>
  <IsTruncated>false</IsTruncated>
  <Prefix/>
  <Name>tempbucket</Name>
  <MaxKeys>1000</MaxKeys>
  <EncodingType>url</EncodingType>
</ListBucketResult>

HeadObject

Retrieves metadata from an object without returning the object itself.

Method: HEAD

Path: /{bucket}/{key}

Responses:

200 - OK: The metadata is returned in the response headers.

Examples:

AWS CLI

$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api head-object \
  --bucket=testbucket --key=test.txt
{
    "LastModified": "2022-05-03T18:55:01+00:00",
    "ContentLength": 27040,
    "ETag": "0cc175b9c0f1b6a831c399e269772661",
    "ContentType": "application/octet-stream",
    "Metadata": {}
}

REST Client

$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
  --head http://localhost:29998/testbucket/test.txt
HTTP/1.1 200 OK
Date: Tue, 03 May 2022 21:54:22 GMT
Last-Modified: Tue, 03 May 2022 21:47:36 GMT
ETag: 0cc175b9c0f1b6a831c399e269772661
Content-Type: application/octet-stream
Content-Length: 27040
Server: Jetty(9.4.43.v20210629)

ListObjects

Returns some or all (up to 1,000) of the objects in a bucket.

Method: GET

Path: /{bucket}

Responses:

200 - OK: Returns an XML document with the list of objects.

Examples:

AWS CLI

$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api list-objects \
  --bucket=testbucket
{
    "Contents": [
        {
            "Key": "test.txt",
            "LastModified": "2022-05-03T11:35:59.243000+00:00",
            "Size": 27040
        },
        {
            "Key": "test_copy.txt",
            "LastModified": "2022-05-03T11:37:16.185000+00:00",
            "Size": 27040
        }
    ]
}

REST Client

$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
  -X GET http://localhost:29998/testbucket
HTTP/1.1 200 OK
Date: Tue, 03 May 2022 21:50:26 GMT
Content-Type: application/xml
Content-Length: 434
Server: Jetty(9.4.43.v20210629)

<ListBucketResult>
  <version2>false</version2>
  <Contents>
    <Key>test.txt</Key>
    <Size>27040</Size>
    <LastModified>2022-05-03T14:47:36.600Z</LastModified>
  </Contents>
  <Contents>
    <Key>test_copy.txt</Key>
    <Size>27040</Size>
    <LastModified>2022-05-03T14:50:07.790Z</LastModified>
  </Contents>
  <Marker/>
  <IsTruncated>false</IsTruncated>
  <Prefix/>
  <Name>testbucket</Name>
  <MaxKeys>1000</MaxKeys>
  <EncodingType>url</EncodingType>
</ListBucketResult>

ListObjectsV2

Returns some or all (up to 1,000) of the objects in a bucket. This is the newer version of ListObjects.

Method: GET

Path: /{bucket}?list-type=2

Responses:

200 - OK: Returns an XML document with the list of objects.

Examples:

AWS CLI

$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api list-objects-v2 \
  --bucket=testbucket
{
    "Contents": [
        {
            "Key": "test.txt",
            "LastModified": "2022-05-03T11:35:59.243000+00:00",
            "Size": 27040
        },
        {
            "Key": "test_copy.txt",
            "LastModified": "2022-05-03T11:37:16.185000+00:00",
            "Size": 27040
        }
    ]
}

REST Client

$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
  -X GET "http://localhost:29998/testbucket?list-type=2"
HTTP/1.1 200 OK
Date: Tue, 03 May 2022 21:56:20 GMT
Content-Type: application/xml
Content-Length: 438
Server: Jetty(9.4.43.v20210629)

<ListBucketResult>
  <version2>true</version2>
  <Contents>
    <Key>test.txt</Key>
    <Size>27040</Size>
    <LastModified>2022-05-03T14:47:36.600Z</LastModified>
  </Contents>
  <Contents>
    <Key>test_copy.txt</Key>
    <Size>27040</Size>
    <LastModified>2022-05-03T14:50:07.790Z</LastModified>
  </Contents>
  <IsTruncated>false</IsTruncated>
  <Prefix/>
  <KeyCount>2</KeyCount>
  <Name>testbucket</Name>
  <MaxKeys>1000</MaxKeys>
  <EncodingType>url</EncodingType>
</ListBucketResult>

GetObjectTagging

Retrieves the tags associated with an object.

Method: GET

Path: /{bucket}/{key}?tagging

Responses:

200 - OK: Returns an XML document with the tag set.

Examples:

AWS CLI

$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api get-object-tagging \
  --bucket=testbucket --key=test.txt
{
    "TagSet": [
        {
            "Key": "key1",
            "Value": "val1"
        },
        {
            "Key": "key2",
            "Value": "val2"
        }
    ]
}

REST Client

$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
  -X GET "http://localhost:29998/testbucket/test.txt?tagging"
HTTP/1.1 200 OK
Date: Tue, 03 May 2022 23:35:58 GMT
Content-Type: application/octet-stream
Content-Length: 126
Server: Jetty(9.4.43.v20210629)

<Tagging>
  <TagSet>
    <Tag>
      <Key>key1</Key>
      <Value>val1</Value>
    </Tag>
    <Tag>
      <Key>key2</Key>
      <Value>val2</Value>
    </Tag>
  </TagSet>
</Tagging>

PutObjectTagging

Adds a set of tags to an existing object.

Method: PUT

Path: /{bucket}/{key}?tagging

Request Body: An XML document containing the tag set.

Responses:

200 - OK: The tags were added successfully.

Examples:

AWS CLI

$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api get-object-tagging \
  --bucket=testbucket --key=test.txt
{
    "TagSet": []
}

$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api put-object-tagging \
  --bucket=testbucket --key=test.txt --tagging='TagSet=[{Key=key1,Value=val1},{Key=key2,Value=val2}]'

$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api get-object-tagging \
  --bucket=testbucket --key=test.txt
{
    "TagSet": [
        {
            "Key": "key1",
            "Value": "val1"
        },
        {
            "Key": "key2",
            "Value": "val2"
        }
    ]
}

REST Client

$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
  -X GET "http://localhost:29998/testbucket/test.txt?tagging"
HTTP/1.1 200 OK
Date: Tue, 03 May 2022 23:30:25 GMT
Content-Type: application/xml
Content-Length: 28
Server: Jetty(9.4.43.v20210629)

<Tagging><TagSet/></Tagging>

$ cat tags.xml
<Tagging>
  <TagSet>
    <Tag>
      <Key>key1</Key>
      <Value>val1</Value>
    </Tag>
    <Tag>
      <Key>key2</Key>
      <Value>val2</Value>
    </Tag>
  </TagSet>
</Tagging>

$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
  -H "Content-Type: application/xml" \
  -X PUT "http://localhost:29998/testbucket/test.txt?tagging" --data-binary "@tags.xml"
HTTP/1.1 200 OK
Date: Tue, 03 May 2022 23:35:28 GMT
Content-Length: 0
Server: Jetty(9.4.43.v20210629)

$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
  -X GET "http://localhost:29998/testbucket/test.txt?tagging"
HTTP/1.1 200 OK
Date: Tue, 03 May 2022 23:35:58 GMT
Content-Type: application/octet-stream
Content-Length: 126
Server: Jetty(9.4.43.v20210629)

<Tagging>
  <TagSet>
    <Tag>
      <Key>key1</Key>
      <Value>val1</Value>
    </Tag>
    <Tag>
      <Key>key2</Key>
      <Value>val2</Value>
    </Tag>
  </TagSet>
</Tagging>

DeleteObjectTagging

Deletes the tags from an object.

Method: DELETE

Path: /{bucket}/{key}?tagging

Responses:

204 - No Content: The tags were deleted successfully.

Examples:

AWS CLI

$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api get-object-tagging \
  --bucket=testbucket --key=test.txt
{
    "TagSet": [
        {
            "Key": "key1",
            "Value": "val1"
        },
        {
            "Key": "key2",
            "Value": "val2"
        }
    ]
}

$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api delete-object-tagging \
  --bucket=testbucket --key=test.txt

$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api get-object-tagging \
  --bucket=testbucket --key=test.txt
{
    "TagSet": []
}

REST Client

$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
  -X GET "http://localhost:29998/testbucket/test.txt?tagging"
HTTP/1.1 200 OK
Date: Tue, 03 May 2022 23:35:58 GMT
Content-Type: application/octet-stream
Content-Length: 126
Server: Jetty(9.4.43.v20210629)

<Tagging>
  <TagSet>
    <Tag>
      <Key>key1</Key>
      <Value>val1</Value>
    </Tag>
    <Tag>
      <Key>key2</Key>
      <Value>val2</Value>
    </Tag>
  </TagSet>
</Tagging>

$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
  -X DELETE "http://localhost:29998/testbucket/test.txt?tagging"
HTTP/1.1 204 No Content
Date: Tue, 03 May 2022 23:37:46 GMT
Server: Jetty(9.4.43.v20210629)

$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
  -X GET "http://localhost:29998/testbucket/test.txt?tagging"
HTTP/1.1 200 OK
Date: Tue, 03 May 2022 23:37:47 GMT
Content-Type: application/octet-stream
Content-Length: 28
Server: Jetty(9.4.43.v20210629)

<Tagging><TagSet/></Tagging>

Multipart Upload Operations

CreateMultipartUpload

Initiates a multipart upload and returns an upload ID.

Method: POST

Path: /{bucket}/{key}?uploads

Responses:

200 - OK: Returns an XML document with the UploadId.

Examples:

AWS CLI

$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api create-multipart-upload \
  --bucket=testbucket --key=multipart.txt
{
    "Bucket": "testbucket",
    "Key": "multipart.txt",
    "UploadId": "6367cf96-ea4e-4447-b931-c5bc91200375"
}

REST Client

$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
  -X POST "http://localhost:29998/testbucket/multipart.txt?uploads"
HTTP/1.1 200 OK
Date: Tue, 03 May 2022 23:41:26 GMT
Content-Type: application/xml
Content-Length: 147
Server: Jetty(9.4.43.v20210629)

<InitiateMultipartUploadResult>
  <Bucket>testbucket</Bucket>
  <Key>multipart.txt</Key>
  <UploadId>6367cf96-ea4e-4447-b931-c5bc91200375</UploadId>
</InitiateMultipartUploadResult>

UploadPart

Uploads a part in a multipart upload.

Method: PUT

Path: /{bucket}/{key}

Query Parameters:

partNumber: Part number of the part being uploaded. This is a positive integer between 1 and 10,000.
uploadId: Upload ID of the multipart upload.

Request Body: The content of the part.

Responses:

200 - OK: The part was uploaded successfully.

Examples:

AWS CLI

$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api upload-part \
  --bucket=testbucket --key=multipart.txt --upload-id=6367cf96-ea4e-4447-b931-c5bc91200375 --part-number=1 --body="${ALLUXIO_HOME}/LICENSE"
{
    "ETag": "911df44b7ff57801ca8d74568e4ebfbe"
}

$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api list-parts \
  --bucket=testbucket --key=multipart.txt --upload-id=6367cf96-ea4e-4447-b931-c5bc91200375
{
    "Parts": [
        {
            "PartNumber": 1,
            "LastModified": "2022-05-03T12:56:27.775000+00:00",
            "ETag": "",
            "Size": 27040
        }
    ],
    "ChecksumAlgorithm": null,
    "Initiator": null,
    "Owner": null,
    "StorageClass": "STANDARD"
}

REST Client

$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
  -X PUT -T "${ALLUXIO_HOME}/LICENSE" "http://localhost:29998/testbucket/multipart.txt?uploadId=6367cf96-ea4e-4447-b931-c5bc91200375&partNumber=1"
HTTP/1.1 100 Continue

HTTP/1.1 200 OK
Date: Tue, 03 May 2022 23:51:19 GMT
ETag: "911df44b7ff57801ca8d74568e4ebfbe"
Content-Length: 0
Server: Jetty(9.4.43.v20210629)

$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api list-parts \
  --bucket=testbucket --key=multipart_copy.txt --upload-id=6367cf96-ea4e-4447-b931-c5bc91200375
{
    "Parts": [
        {
            "PartNumber": 1,
            "LastModified": "2022-05-03T13:00:13.584000+00:00",
            "ETag": "",
            "Size": 27040
        }
    ],
    "ChecksumAlgorithm": null,
    "Initiator": null,
    "Owner": null,
    "StorageClass": "STANDARD"
}

UploadPartCopy

Uploads a part by copying data from an existing object as a data source.

Method: PUT

Path: /{bucket}/{key}

Query Parameters:

partNumber: Part number of the part being uploaded.
uploadId: Upload ID of the multipart upload.

Request Headers:

x-amz-copy-source: The name of the source bucket and key.

Responses:

200 - OK: The part was copied successfully.

Examples:

AWS CLI

$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api upload-part-copy \
  --bucket=testbucket --key=object --upload-id=6367cf96-ea4e-4447-b931-c5bc91200375 --part-number=1 --copy-source=testbucket/object
{
    "CopyPartResult": {
        "ETag": "0cc175b9c0f1b6a831c399e269772661"
    }
}

$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api list-parts \
  --bucket=testbucket --key=object --upload-id=6367cf96-ea4e-4447-b931-c5bc91200375
{
    "Parts": [
        {
            "PartNumber": 1,
            "LastModified": "2022-07-01T11:27:48.942000+00:00",
            "ETag": "",
            "Size": 1
        }
    ],
    "ChecksumAlgorithm": null,
    "Initiator": null,
    "Owner": null,
    "StorageClass": "STANDARD"
}

REST Client

$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
  -H "x-amz-copy-source: testbucket/object" \
  -X PUT 'http://localhost:29998/testbucket/object?uploadId=6367cf96-ea4e-4447-b931-c5bc91200375&partNumber=1'
HTTP/1.1 200 OK
Date: Fri, 01 Jul 2022 18:31:34 GMT
Content-Type: application/xml
Content-Length: 78
Server: Jetty(9.4.46.v20220331)

<CopyPartResult><ETag>0cc175b9c0f1b6a831c399e269772661</ETag></CopyPartResult>

ListParts

Lists the parts that have been uploaded for a specific multipart upload.

Method: GET

Path: /{bucket}/{key}

Query Parameters:

uploadId: Upload ID of the multipart upload.

Responses:

200 - OK: Returns an XML document with the list of parts.

Examples:

AWS CLI

$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api list-parts \
  --bucket=testbucket --key=multipart.txt --upload-id=6367cf96-ea4e-4447-b931-c5bc91200375
{
    "Parts": [
        {
            "PartNumber": 1,
            "LastModified": "2022-05-03T12:56:27.775000+00:00",
            "ETag": "",
            "Size": 27040
        }
    ],
    "ChecksumAlgorithm": null,
    "Initiator": null,
    "Owner": null,
    "StorageClass": "STANDARD"
}

REST Client

$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
  -X GET "http://localhost:29998/testbucket/multipart.txt?uploadId=6367cf96-ea4e-4447-b931-c5bc91200375"
HTTP/1.1 200 OK
Date: Tue, 03 May 2022 23:49:05 GMT
Content-Type: application/octet-stream
Content-Length: 314
Server: Jetty(9.4.43.v20210629)

<ListPartsResult>
  <Bucket>/testbucket</Bucket>
  <Key>multipart.txt</Key>
  <UploadId>6367cf96-ea4e-4447-b931-c5bc91200375</UploadId>
  <StorageClass>STANDARD</StorageClass>
  <IsTruncated>false</IsTruncated>
  <Part>
    <PartNumber>1</PartNumber>
    <LastModified>2022-05-03T16:48:56.602Z</LastModified>
    <ETag></ETag>
    <Size>27040</Size>
  </Part>
</ListPartsResult>

ListMultipartUploads

This operation lists in-progress multipart uploads.

Method: GET

Path: /{bucket}?uploads

Responses:

200 - OK: Returns an XML document with a list of in-progress multipart uploads.

Examples:

AWS CLI

$ aws --profile alluxio-s3 --endpoint="http://localhost:39999/api/v1/s3" s3api list-multipart-uploads --bucket "testbucket"
{
    "Uploads": [
        {
            "UploadId": "c4cddf71-914a-4cee-b2af-8cfb7def7d04",
            "Key": "object",
            "Initiated": "2022-07-01T11:21:14.738000+00:00"
        },
        {
            "UploadId": "6367cf96-ea4e-4447-b931-c5bc91200375",
            "Key": "object",
            "Initiated": "2022-07-01T11:18:25.290000+00:00"
        },
        {
            "UploadId": "e111c33b-5c18-4ecd-b543-2849cdbbf22b",
            "Key": "object2",
            "Initiated": "2022-07-01T11:21:25.182000+00:00"
        }
    ]
}

REST Client

$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
  -X GET "http://localhost:29998/testbucket?uploads"
HTTP/1.1 200 OK
Date: Fri, 01 Jul 2022 18:23:43 GMT
Content-Type: application/xml
Content-Length: 499
Server: Jetty(9.4.46.v20220331)

<ListMultipartUploadsResult>
  <Bucket>testbucket</Bucket>
  <Upload>
    <Key>object</Key>
    <UploadId>c4cddf71-914a-4cee-b2af-8cfb7def7d04</UploadId>
    <Initiated>2022-07-01T11:21:14.738Z</Initiated>
  </Upload>
  <Upload>
    <Key>object</Key>
    <UploadId>6367cf96-ea4e-4447-b931-c5bc91200375</UploadId>
    <Initiated>2022-07-01T11:18:25.290Z</Initiated>
  </Upload>
  <Upload>
    <Key>object2</Key>
    <UploadId>e111c33b-5c18-4ecd-b543-2849cdbbf22b</UploadId>
    <Initiated>2022-07-01T11:21:25.182Z</Initiated>
  </Upload>
</ListMultipartUploadsResult>

AbortMultipartUpload

Aborts a multipart upload. After a multipart upload is aborted, no more parts can be uploaded using that upload ID.

Method: DELETE

Path: /{bucket}/{key}

Query Parameters:

uploadId: The ID of the multipart upload to abort.

Responses:

204 - No Content: The multipart upload was aborted successfully.

Examples:

AWS CLI

$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api list-objects-v2 \
  --bucket=testbucket
{
    "Contents": [
        {
            "Key": "multipart_copy.txt_6367cf96-ea4e-4447-b931-c5bc91200375/",
            "LastModified": "2022-05-03T13:00:13.429000+00:00",
            "Size": 0
        },
        {
            "Key": "multipart_copy.txt_6367cf96-ea4e-4447-b931-c5bc91200375/1",
            "LastModified": "2022-05-03T13:00:13.584000+00:00",
            "Size": 27040
        },
        {
            "Key": "test.txt",
            "LastModified": "2022-05-03T11:55:01.925000+00:00",
            "Size": 27040
        }
    ]
}

$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api abort-multipart-upload \
  --bucket=testbucket --key=multipart_copy.txt --upload-id=6367cf96-ea4e-4447-b931-c5bc91200375

$ % aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api list-objects-v2 \
  --bucket=testbucket
{
    "Contents": [
        {
            "Key": "test.txt",
            "LastModified": "2022-05-03T11:55:01.925000+00:00",
            "Size": 27040
        }
    ]
}

REST Client

$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
  -X GET "http://localhost:29998/testbucket"
HTTP/1.1 200 OK
Date: Tue, 03 May 2022 23:45:17 GMT
Content-Type: application/xml
Content-Length: 583
Server: Jetty(9.4.43.v20210629)

<ListBucketResult>
  <version2>false</version2>
  <Marker/>
  <Prefix/>
  <IsTruncated>false</IsTruncated>
  <Name>testbucket</Name>
  <Contents>
    <Key>multipart.txt_6367cf96-ea4e-4447-b931-c5bc91200375/</Key>
    <Size>0</Size>
    <LastModified>2022-05-03T16:44:17.490Z</LastModified>
  </Contents>
  <Contents>
    <Key>multipart.txt_6367cf96-ea4e-4447-b931-c5bc91200375/1</Key>
    <Size>27040</Size>
    <LastModified>2022-05-03T16:44:17.715Z</LastModified>
  </Contents>
  <Contents>
    <Key>test.txt</Key>
    <Size>27040</Size>
    <LastModified>2022-05-03T14:47:36.600Z</LastModified>
  </Contents>
  <MaxKeys>1000</MaxKeys>
  <EncodingType>url</EncodingType>
</ListBucketResult>

$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
  -X DELETE "http://localhost:29998/testbucket/multipart.txt?uploadId=6367cf96-ea4e-4447-b931-c5bc91200375"
HTTP/1.1 204 No Content
Date: Tue, 03 May 2022 23:45:30 GMT
Server: Jetty(9.4.43.v20210629)

$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
  -X GET "http://localhost:29998/testbucket"
HTTP/1.1 200 OK
Date: Tue, 03 May 2022 23:45:36 GMT
Content-Type: application/xml
Content-Length: 318
Server: Jetty(9.4.43.v20210629)

<ListBucketResult>
  <version2>false</version2>
  <Marker/>
  <Prefix/>
  <IsTruncated>false</IsTruncated>
  <Name>testbucket</Name>
  <Contents>
    <Key>test.txt</Key>
    <Size>27040</Size>
    <LastModified>2022-05-03T14:47:36.600Z</LastModified>
  </Contents>
  <MaxKeys>1000</MaxKeys>
  <EncodingType>url</EncodingType>
</ListBucketResult>

CompleteMultipartUpload

Completes a multipart upload by assembling previously uploaded parts.

Method: POST

Path: /{bucket}/{key}

Query Parameters:

uploadId: The ID of the multipart upload to complete.

Request Body: An XML document listing the parts to be assembled.

<CompleteMultipartUpload>
   <Part>
      <PartNumber>1</PartNumber>
   </Part>
   <Part>
      <PartNumber>2</PartNumber>
   </Part>
   ...
</CompleteMultipartUpload>

Responses:

200 - OK: Returns an XML document with information about the completed object.

Examples:

AWS CLI

$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api complete-multipart-upload \
  --bucket=testbucket --key=multipart.txt --upload-id=6367cf96-ea4e-4447-b931-c5bc91200375 \
  --multipart-upload="Parts=[{PartNumber=1},{PartNumber=2}]"
{
    "Location": "/testbucket/multipart.txt",
    "Bucket": "testbucket",
    "Key": "multipart.txt",
    "ETag": "911df44b7ff57801ca8d74568e4ebfbe"
}

$ aws --profile alluxio-s3 --endpoint "http://localhost:29998/" s3api head-object \
  --bucket=testbucket --key=multipart.txt
{
    "LastModified": "2022-05-03T20:01:43+00:00",
    "ContentLength": 27040,
    "ETag": "0cc175b9c0f1b6a831c399e269772661",
    "ContentType": "application/octet-stream",
    "Metadata": {}
}

REST Client

$ cat complete_upload.xml

<CompleteMultipartUpload xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
   <Part>
      <PartNumber>1</PartNumber>
   </Part>
   <Part>
      <PartNumber>2</PartNumber>
   </Part>
</CompleteMultipartUpload>

$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
  -H "Content-Type: application/xml" -d "@complete_upload.xml" \
  -X POST "http://localhost:29998/testbucket/multipart.txt?uploadId=6367cf96-ea4e-4447-b931-c5bc91200375"

Date: Tue, 03 May 2022 23:59:17 GMT
Content-Type: text/xml;charset=utf-8
Transfer-Encoding: chunked
Server: Jetty(9.4.43.v20210629)

<CompleteMultipartUploadResult>
  <Location>/testbucket/multipart.txt</Location>
  <Bucket>testbucket</Bucket>
  <Key>multipart.txt</Key>
  <ETag>911df44b7ff57801ca8d74568e4ebfbe</ETag>
  <Code/>
  <Message/>
</CompleteMultipartUploadResult>

$ curl -i -H "Authorization: AWS4-HMAC-SHA256 Credential=testuser/..." \
  --head "http://localhost:29998/testbucket/multipart.txt"
HTTP/1.1 200 OK
Date: Wed, 04 May 2022 00:00:40 GMT
Last-Modified: Tue, 03 May 2022 23:59:18 GMT
ETag: 0cc175b9c0f1b6a831c399e269772661
Content-Type: application/octet-stream
Content-Length: 27040
Server: Jetty(9.4.43.v20210629)

Last updated 17 days ago