└── README.md


/README.md:
--------------------------------------------------------------------------------
 1 | # Undocumented S3 APIs
 2 | 
 3 | Undocumented Amazon S3 APIs and third-party extensions.  This documents
 4 | features outside the official
 5 | [Amazon S3 REST APIs](https://docs.aws.amazon.com/AmazonS3/latest/API/Welcome.html).
 6 | Note that these are not consistently supported across implementations.
 7 | 
 8 | ## Amazon APIs
 9 | 
10 | ### GET object by multipart number
11 | 
12 | Object metadata exposes the number of multipart upload parts via the
13 | `x-amz-mp-parts-count` header.  Subsequent GET object requests can retrieve
14 | individual parts via the `partNumber` parameter.  This allows retrieving
15 | individual multipart upload parts, including the original ETag.
16 | 
17 | * [AWS Java SDK partNumber](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/s3/model/GetObjectMetadataRequest.html#withPartNumber-java.lang.Integer-)
18 | * [AWS Java SDK x-amz-mp-parts-count](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/s3/model/ObjectMetadata.html#getPartCount--)
19 | 
20 | ### HEAD bucket exposes region
21 | 
22 | HEAD bucket exposes the region via `x-amz-bucket-region` even if the request
23 | lacks authentication.  This allows clients to interrogate a bucket so that they
24 | can route subsequent requests to the correct endpoint.
25 | 
26 | ### Multipart Upload ETag
27 | 
28 | Single part upload ETag are the MD5 hash of the object content.  Multipart
29 | upload ETag concatenate the MD5 of each part, MD5 this data, and append a
30 | hyphen and the number of parts.
31 | 
32 | * [Stack Overflow answer](https://stackoverflow.com/questions/12186993/what-is-the-algorithm-to-compute-the-amazon-s3-etag-for-a-file-larger-than-5gb)
33 | 
34 | ## Third-party APIs
35 | 
36 | ### GET bucket unordered
37 | 
38 | `allow-unordered=true` parameter overrides key sorting which allows higher
39 | performance with large buckets.  Cannot be used with delimiter.
40 | 
41 | * [Ceph documentation](http://docs.ceph.com/docs/master/radosgw/s3/bucketops/#get-bucket)
42 | 
43 | ### HEAD bucket extended
44 | 
45 | Returns bucket statistics via `x-rgw-bytes-used` and `x-rgw-object-count`
46 | headers.
47 | 
48 | * [Ceph feature #2313](https://tracker.ceph.com/issues/2313)
49 | 
50 | ### PUT object append
51 | 
52 | Append to an existing object at a given offset via the `append` and `position`
53 | parameters.  Responses include `x-oss-next-append-position` and
54 | `x-rgw-next-append-position` which indicate the next valid append offset.
55 | 
56 | * [Aliyun documentation](https://partners-intl.aliyun.com/help/doc-detail/31981.htm?spm=a2c63.p38356.b99.595.5783438dGk)
57 | * [Ceph documentation](http://docs.ceph.com/docs/master/radosgw/s3/objectops/#append-object)
58 | 
59 | ### PUT object conditional
60 | 
61 | `If-Match` and `If-None-Match` (Ceph) and `x-goog-if-generation-match` and
62 | `x-goog-if-metageneration-match` (Google) headers allow atomic replacement of
63 | objects.
64 | 
65 | * [Ceph feature #8562](https://tracker.ceph.com/issues/8562)
66 | * [Google Cloud Storage documentation](https://cloud.google.com/storage/docs/generations-preconditions#_XMLAPI)
67 | 
68 | ### Resumable uploads
69 | 
70 | Initiate a resumable upload with POST object with the `x-goog-resumable`
71 | header.  Use the response `Location` to issue a PUT object with given
72 | Content-Length and Content-Range headers.  Continuing issuing these requests to
73 | build larger objects.
74 | 
75 | * [Google Cloud Storage documentation](https://cloud.google.com/storage/docs/xml-api/resumable-upload)
76 | 
77 | ### Small file archives
78 | 
79 | Allows interaction with ZIP file contents as if they were objects.  HeadObject,
80 | GetObject, and ListObjectsV2 support these operations when the header
81 | `x-minio-extract` has a `true` value.
82 | 
83 | * [Minio documentation](https://blog.min.io/small-file-archives/)
84 | 
85 | ## References
86 | 
87 | * [Aliyun API documentation](https://partners-intl.aliyun.com/help/doc-detail/31947.htm?spm=a2c63.p38356.b99.563.3d3152e7qsZxhf)
88 | * [Amazon API documentation](https://docs.aws.amazon.com/AmazonS3/latest/API/Welcome.html)
89 | * [Ceph API documentation](http://docs.ceph.com/docs/master/radosgw/s3/)
90 | * [Google API documentation](https://cloud.google.com/storage/docs/xml-api/overview)
91 | 


--------------------------------------------------------------------------------