S3 API Compatibility

This page documents S3 APIs supported by MinIO AIStor. For reference documentation on any given API, see the corresponding documentation for Amazon S3.

Object APIs

• CopyObject

• DeleteObject

• DeleteObjects

• DeleteObjectTagging

• GetObject

• GetObjectAttributes

• GetObjectTagging

• HeadObject

• ListObjects

• ListObjectsV2

• ListObjectVersions

• PutObject

• PutObjectTagging

• RestoreObject

• SelectObjectContent

Conditional headers

MinIO AIStor supports conditional operations using the following HTTP headers:

DeleteObjects supports conditional deletes using the <ETag> element in the request body.

Object locking

• GetObjectRetention

• PutObjectRetention

• GetObjectLegalHold

• PutObjectLegalHold

• GetObjectLockConfiguration

• PutObjectLockConfiguration

Unsupported object APIs

• GetObjectAcl
• PutObjectAcl

Multipart uploads

• AbortMultipartUpload

• CompleteMultipartUpload

• CreateMultipartUpload

• ListMultipartUploads

• ListParts

• UploadPart

• UploadPartCopy

Differences from S3 APIs for multipart uploads

• ListMultipartUploads requires the exact object name as a prefix.

• The AbortIncompleteMultipartUpload lifecycle action is not supported with PutBucketLifecycle.

Bucket APIs

• CreateBucket

• DeleteBucket

• DeleteBucketEncryption

• DeleteBucketTagging

• GetBucketEncryption

• GetBucketLocation

• GetBucketTagging

• GetBucketVersioning

• HeadBucket

• ListBuckets

• ListDirectoryBuckets

• PutBucketEncryption

• PutBucketTagging

• PutBucketVersioning

• PutBucketCors

• DeleteBucketCors

• CreateSession

Bucket replication

• GetBucketReplication

• PutBucketReplication

• DeleteBucketReplication

Bucket lifecycle

• GetBucketLifecycle

• GetBucketLifecycleConfiguration

• PutBucketLifecycle

• PutBucketLifecycleConfiguration

• DeleteBucketLifecycle

Bucket notifications

• GetBucketNotification

• GetBucketNotificationConfiguration

• PutBucketNotification

• PutBucketNotificationConfiguration

Bucket policies

• GetBucketPolicy

• GetBucketPolicyStatus

• PutBucketPolicy

• DeleteBucketPolicy

Unsupported bucket API operations

• GetBucketInventoryConfiguration
• PutBucketInventoryConfiguration
• DeleteBucketInventoryConfiguration
• GetBucketMetricsConfiguration
• PutBucketMetricsConfiguration
• DeleteBucketMetricsConfiguration
• PutBucketWebsite
• GetBucketLogging
• PutBucketLogging
• PutBucketAccelerateConfiguration
• DeleteBucketAccelerateConfiguration
• PutBucketRequestPayment
• DeleteBucketRequestPayment
• PutBucketAcl
• HeadBucketAcl
• GetPublicAccessBlock
• PutPublicAccessBlock
• DeletePublicAccessBlock
• GetBucketOwnershipControls
• PutBucketOwnershipControls
• DeleteBucketOwnershipControls
• GetBucketIntelligentTieringConfiguration
• PutBucketIntelligentTieringConfiguration
• ListBucketIntelligentTieringConfigurations
• DeleteBucketIntelligentTieringConfiguration
• GetBucketAnalyticsConfiguration
• PutBucketAnalyticsConfiguration
• ListBucketAnalyticsConfigurations
• DeleteBucketAnalyticsConfiguration

MinIO AIStor alternatives for unsupported bucket API operations

• For calls to BucketACL or ObjectACL operations, use Policies.
• For calls to BucketWebsite operations, use caddy or nginx.
• For calls to BucketAnalytics, BucketMetrics, or BucketLogging operations, use Bucket notifications.

S3 extensions

MinIO AIStor extends the S3 API with additional capabilities.

Object checksums

MinIO AIStor accepts a checksum on write, returns it on read, and reports it through GetObjectAttributes. Send the digest in the header for the algorithm you are using, and name that algorithm in x-amz-checksum-algorithm.

CRC32, CRC32C, CRC64NVME, SHA1, and SHA256 are the algorithms AWS S3 defines. MD5, SHA512, XXHASH64, XXHASH3, and XXHASH128 are a MinIO AIStor extension, so a client written against AWS S3 will not recognize them.

x-amz-checksum-type reports how the checksum covers the object:

• FULL_OBJECT — the digest covers the whole object.
• COMPOSITE — the digest is a hash of the individual part digests, so it changes when the part layout changes, even if the content does not.

Checksums in listings

ListObjects, ListObjectsV2, and ListObjectVersions report the checksum algorithm and type for each object, matching AWS S3.

Returning the digest itself is a MinIO AIStor extension. A listing returns digests only when it requests object metadata and the caller is permitted to read the object. A caller holding s3:ListBucket alone receives the algorithm and type, but no digest.

Checksums on objects encrypted with SSE-S3 or SSE-KMS are decrypted for the listing. An SSE-C checksum is sealed as a whole, so neither the digest nor the algorithm is readable without the client key.

S3 over RDMA

On a deployment running the RDMA build, GetObject, PutObject, and UploadPart can transfer object data directly between client memory and the server over RDMA, using the AWS S3 RDMA protocol. GetObject writes into the client’s buffer; PutObject and UploadPart read from it. That buffer is usually GPU memory, which is where RDMA pays off most, but host memory works too and needs no GPU.

The client opts in per request with a header; there is no server setting.

On a successful RDMA transfer the server sets Content-Length: 0, because the object bytes did not travel in the HTTP response.

When the server declines, it returns an S3 error response rather than serving the object over HTTP. Retrying without the x-amz-rdma-token header is the client’s responsibility. The MinIO SDKs below handle this automatically.

Reliable Connection clients first perform a handshake at POST /rdma/connect, exchanging descriptors through the same x-amz-rdma-token header. Dynamically Connected clients do not use this route.

SDK support

S3 over RDMA is supported by the MinIO SDKs for Go, C++, Rust, and Python.

Each of them uses NVIDIA cuObjClient to move the object payload between GPU memory and the network adapter.

For worked examples in each language, see Transfer Objects over RDMA.

For deployment, see RDMA acceleration.

S3 Express mode

When MinIO AIStor runs in S3 Express mode, the supported S3 API surface differs from the default S3 API mode. S3 Express mode also adds the AppendObject behavior, which lets a client append data to an existing object by issuing a PutObject request with the x-amz-write-offset-bytes header. For the list of operations supported and disabled in S3 Express mode, see S3 Express mode.

MinIO-specific error codes

In addition to the standard S3 error codes, MinIO AIStor returns the following MinIO-specific error codes:

KMS error codes

KMS-backed operations return these codes, including when the KMS itself is unreachable:

A request that the client cancels while a KMS operation is in flight returns status 499 rather than a KMS error.