frostfs-s3-gw/docs/extensions.md

S3 API Extension

Bucket operations management

Action to delete bucket (DeleteBucket)

Deletes bucket with all objects in it.

Request Parameters

• Bucket

  Specifies the bucket being deleted.

Errors

• NoSuchEntity

  The request was rejected because it referenced a resource entity that does not exist.

  HTTP Status Code: 404

• ServiceFailure

  The request processing has failed because of an unknown error, exception or failure.

  HTTP Status Code: 500

Example

Sample Request

DELETE / HTTP/1.1
X-Amz-Force-Delete-Bucket: true
Host: data.s3.<Region>.frostfs-s3-gw.com
Date: Wed, 01 Mar  2024 12:00:00 GMT
Authorization: authorization string

Sample Response

HTTP/1.1 204 No Content
        x-amz-id-2: JuKZqmXuiwFeDQxhD7M8KtsKobSzWA1QEjLbTMTagkKdBX2z7Il/jGhDeJ3j6s80
        x-amz-request-id: 32FE2CEB32F5EE25
        Date: Wed, 01 Mar  2006 12:00:00 GMT
        Connection: close
        Server: AmazonS3

Object operations management

Action to patch object (PatchObject)

Allows to partially change and add data to an existing object.

Note

: patch is not supported for objects that were uploaded using SSE.

Path parameters

• Bucket

  Bucket name.

  Required: Yes

• Key

  Object name.

  Required: Yes

Query parameters

• versionId

  Version of the original object to patch.

  Required: No

Request headers

• Content-Range

  The byte range of the object (or its version) to patch.

  The value is formed as follows: bytes {start byte}-{end byte}/*.

  Range boundaries are included.

  The maximum range length is 5GB.

  To write additional data to the object, the end byte must be greater than the object size.

  The start byte cannot be greater than the object size.

  The range length must be equal to the value of the Content-Length header.

  The format corresponds to the RFC 9110 specification with the following exceptions:

  • complete-length parameter is ignored.
  • last-pos parameter is optional (if not specified, the value is assumed to be equal to the end byte of the object).

  Required: Yes

• Content-Length

  Number of bytes sent in the request body.

  Required: Yes

• If-Match

  Patch is performed if ETag of the object (or its version) is equal to specified in the header.

  Required: No

• If-Unmodified-Since

  Patch is performed if the object (or its version) has not changed since the time specified in the header.

  Required: No

• x-amz-expected-bucket-owner

  ID of the intended owner of the bucket.

  Required: No

Request body

Contains new data for the passed byte range of the object.

Response

The request returns the following data in XML format.

• PatchObjectResult

  Root level tag for parameters.

• Object

  Parent tag for patch results.

• LastModified

  Time when the object was last modified. Applying patch does not change this value.

• ETag

  Patched object tag. Always in SHA-256 format.

If the bucket is versioned, the x-amz-version-id header is returned with the version of the created object.

Errors

• MissingContentRange

  The required Content-Range header was not sent.

  HTTP Status Code: 400

• NoSuchBucket

  The specified bucket does not exist.

  HTTP Status Code: 404

• NoSuchKey

  The specified object does not exist.

  HTTP Status Code: 404

• MissingContentLength

  The required Content-Length header was not sent.

  HTTP Status Code: 411

• PreconditionFailed

  At least one of the preconditions is not satisfied.

  HTTP Status Code: 412

• InvalidRange

  Incorrect value in Content-Range header.

  HTTP Status Code: 416

Example

Sample Request

PATCH /example-bucket/example-key HTTP/1.1
Host: data.s3.<Region>.frostfs-s3-gw.com
Content-Range: bytes 0-3/*
Content-Length: 4
&AUTHPARAMS

Body

Sample Response

<PatchObjectResult>
    <Object>
        <LastModified>2024-07-24T14:54:54Z</LastModified>
        <ETag>"e8b53b75afaf3ce898f048c663b11cf4c71f5f13456673dd5b422a247c9e627f"</ETag>
    </Object>
</PatchObjectResult>