From a2e0b925752029869edb615aaa55ab659d891ac2 Mon Sep 17 00:00:00 2001
From: Marina Biryukova <m.biryukova@yadro.com>
Date: Wed, 21 Aug 2024 17:06:32 +0300
Subject: [PATCH] [#473] Add PATCH to extensions doc

Signed-off-by: Marina Biryukova <m.biryukova@yadro.com>
---
 docs/extensions.md | 169 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 169 insertions(+)

diff --git a/docs/extensions.md b/docs/extensions.md
index 72cc93aa..fa8cf1db 100644
--- a/docs/extensions.md
+++ b/docs/extensions.md
@@ -50,3 +50,172 @@ HTTP/1.1 204 No Content
         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. 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>
+```