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

```text
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

```text
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](https://www.rfc-editor.org/rfc/rfc9110#name-content-range) 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. For regular objects 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

```text
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

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