s3
Manage S3 access.
get /s3/users
List of S3 users.
Parameters
uid array query
Array of string items
pagination object query
Pagination request. When supplied, the result will be filtered, sorted and limited according to this request object.
Responses
default response
default response
oneOf A response that can be either paginated or a raw list (depending on the presence of the pagination query parameter).
object
A paginated result.
Examples
No request body required
get /s3/buckets
List of all buckets.
Parameters
pagination object query
Pagination request. When supplied, the result will be filtered, sorted and limited according to this request object.
Responses
default response
default response
oneOf A response that can be either paginated or a raw list (depending on the presence of the pagination query parameter).
object
A paginated result.
Examples
No request body required
get /s3/placements
List all available placement policies in all zones.
Parameters
pagination object query
Pagination request. When supplied, the result will be filtered, sorted and limited according to this request object.
Responses
default response
default response
object
Examples
No request body required
put /s3/default-placement
Set the default placement rule. This API does not support multi-site setups.
Parameters
body object
Examples
Request Body
{
"storageClass": "string",
"placementRule": "string"
}put /s3/placements/{name}
Create a new placement policy in the default zonegroup in the default zone. This API does not support multi-site setups.
Parameters
name string path Required
The name for the policy, each zone within a zonegroup must have a policy with the same name.
body object
Examples
Request Body
{
"dataPool": "string",
"indexPool": "string",
"dataExtraPool": "string"
}put /s3/users/{uid}/quota
Set a quota for this user.
Parameters
uid string path Required
body object
Examples
Request Body
{
"enabled": true,
"maxSize": 42,
"maxObjects": 42,
"maxSizeNew": 42,
"max_objects": 42,
"max_size_kb": 42,
"maxObjectsNew": 42,
"maxObjectsOld": 42,
"maxSizeKiBOld": 42
}get /s3/usage/by-user/{uid}
Retrieve usage statistics for a given S3 user.
Return results aggregated into 1 hour intervals for all buckets the user accessed. Caution: this cannot be used for the anonymous user This can be an expensive call in term of IOPS, do not poll this unnecessarily. The idea is to store the results in an accounting system. Calling this will also trim the S3 usage log if enabled in /config/config.yml, see trimS3Usage in /config/config.yml.default This requires enabling the Ceph option "rgw enable usage log", see https://docs.ceph.com/docs/master/man/8/radosgw/#usage-logging
Parameters
uid string path Required
hours integer query
How many hours to go back.
Responses
default response
default response
object
Usage data for a user, split by bucket.
Examples
No request body required
get /s3/users/{uid}/buckets
List all buckets owner by the user.
Parameters
uid string path Required
Responses
default response
default response
array
Array of RgwBucketResponse objects
Examples
No request body required
put /s3/buckets/{bucketName}
Create a new S3 bucket.
Parameters
bucketName string path Required
body object
Create an S3 bucket.
Responses
default response
default response
object
A long-running task that goes on in the background after this task is completed. See tasks endpoints for details
Examples
Request Body
{
"acl": [
{
"userId": "string",
"grantee": "ALL_USERS",
"permission": "FULL_CONTROL",
"displayName": "string"
}
],
"owner": "string",
"endpoint": "string",
"placement": "string",
"versioning": "OFF",
"expectedNumberOfObjects": 42
}put /s3/users/{uid}/bucket-quota
Set a quota for all buckets owned by this user.
Parameters
uid string path Required
body object
Examples
Request Body
{
"enabled": true,
"maxSize": 42,
"maxObjects": 42,
"maxSizeNew": 42,
"max_objects": 42,
"max_size_kb": 42,
"maxObjectsNew": 42,
"maxObjectsOld": 42,
"maxSizeKiBOld": 42
}put /s3/buckets/{bucketName}/quota
Set a quota for this bucket.
Parameters
bucketName string path Required
body object
Examples
Request Body
{
"enabled": true,
"maxSize": 42,
"maxObjects": 42,
"maxSizeNew": 42,
"max_objects": 42,
"max_size_kb": 42,
"maxObjectsNew": 42,
"maxObjectsOld": 42,
"maxSizeKiBOld": 42
}get /s3/buckets/{bucketName}/policy
Get a bucket policy.
Parameters
bucketName string path Required
owner string query
Responses
default response
default response
object
Examples
No request body required
post /s3/buckets/{bucketName}/policy
Create or update a bucket policy. See the ceph documentation for the list of currently supported actions.
Parameters
bucketName string path Required
owner string query
body object
Bucket policy in JSON format.
Examples
Request Body
{}delete /s3/buckets/{bucketName}/policy
Delete a bucket policy.
Parameters
bucketName string path Required
owner string query
Examples
No request body required
put /s3/buckets/{bucketName}/upload
Upload an object.
Parameters
bucketName string path Required
owner string query
body object
Examples
Request Body
{
"key": "string",
"file": {},
"size": 42
}get /s3/buckets/{bucketName}/objects
List objects in a bucket. Refer to S3 documentation for listing details
Parameters
bucketName string path Required
owner string query
max integer query
prefix string query
continuationToken string query
flatView boolean query
Responses
default response
default response
object
Examples
No request body required
delete /s3/buckets/{bucketName}/objects
Delete an object by name.
Parameters
bucketName string path Required
owner string query
key string query
Examples
No request body required
get /s3/usage/by-bucket/{bucketName}
Retrieve latest usage statistics for a given S3 bucket.
Return results aggregated into 1 hour intervals for all users that accessed the bucket. This can be an expensive call in term of IOPS, do not poll this unnecessarily. The idea is to store the results in an accounting system. Calling this will also trim the S3 usage log if enabled in /config/config.yml, see trimS3Usage in /config/config.yml.default This requires enabling the Ceph option "rgw enable usage log", see https://docs.ceph.com/docs/master/man/8/radosgw/#usage-logging
Parameters
bucketName string path Required
hours integer query
How many hours to go back.
Responses
default response
default response
object
Usage data for a bucket, split by user performing the operation.
Examples
No request body required
get /s3/buckets/{bucketName}/download
Download an object.
Parameters
bucketName string path Required
owner string query
key string query
Responses
default response
default response
object
Examples
No request body required
get /s3/buckets/{bucketName}/objects/acl
Get the current ACL of an object.
Parameters
bucketName string path Required
owner string query
key string query
Responses
default response
default response
array
Array of AclEntry objects - An ACL entry for a bucket, see S3 documentation for details.
Examples
No request body required
put /s3/buckets/{bucketName}/objects/acl
Override an object's ACL.
Parameters
bucketName string path Required
owner string query
key string query
body array
Array of AclEntry objects - An ACL entry for a bucket, see S3 documentation for details.
Examples
Request Body
[
{
"userId": "string",
"grantee": "ALL_USERS",
"permission": "FULL_CONTROL",
"displayName": "string"
}
]put /s3/buckets/{bucketName}/objects/copy
Copy an object.
Parameters
bucketName string path Required
owner string query
key string query
dstBucketName string query
dstKey string query
Examples
No request body required
put /s3/buckets/{bucketName}/objects/move
Move an object.
Parameters
bucketName string path Required
owner string query
key string query
dstBucketName string query
dstKey string query
Examples
No request body required
get /s3/buckets/{bucketName}/objects/metadata
Get metadata of an object.
Parameters
bucketName string path Required
owner string query
key string query
Responses
default response
default response
object
Examples
No request body required
put /s3/buckets/{bucketName}/objects/metadata
Override object metadata.
Parameters
bucketName string path Required
owner string query
key string query
body object
Examples
Request Body
{
"raw": {},
"etag": "string",
"size": 42,
"versionId": "string",
"contentMD5": "string",
"contentType": "string",
"cacheControl": "string",
"lastModified": "2023-12-01T10:00:00Z",
"userMetadata": {},
"expirationTime": "2023-12-01T10:00:00Z",
"contentEncoding": "string",
"contentLanguage": "string",
"httpExpiresDate": "2023-12-01T10:00:00Z",
"contentDisposition": "string",
"expirationTimeRuleId": "string"
}get /s3/buckets/{bucketName}/multipart-uploads
List active and abandoned multi-part uploads. API params are identical to object listing.
Parameters
bucketName string path Required
owner string query
max integer query
prefix string query
continuationToken string query
flatView boolean query
Responses
default response
default response
object
Examples
No request body required
delete /s3/buckets/{bucketName}/multipart-uploads
Cancel an active or abandoned multi-part upload.
Parameters
bucketName string path Required
owner string query
key string query
uploadId string query
Examples
No request body required
get /s3/buckets/{bucketName}/objects-paginated
List objects and prefixes in a bucket. Uses croit's pagination.
Parameters
bucketName string path Required
owner string query
prefix string query
flatView boolean query
pagination object query
Pagination request. When supplied, the result will be filtered, sorted and limited according to this request object.
maxQueried integer query
Maximum number of S3 objects queried for filtering.
Responses
default response
default response
object
Examples
No request body required
get /s3/buckets/{bucketName}/multipart-uploads-paginated
List active and abandoned multi-part uploads. Uses croit's pagination.
Parameters
bucketName string path Required
owner string query
prefix string query
flatView boolean query
pagination object query
Pagination request. When supplied, the result will be filtered, sorted and limited according to this request object.
maxQueried integer query
Responses
default response
default response
object
Examples
No request body required
put /s3/placements/{placementRule}/storage-classes/{storageClass}
Set storage classes on placement rules. This API does not support multi-site setups.
Parameters
placementRule string path Required
The name of an (existing) placement rule.
storageClass string path Required
The name for storage class to add or edit.
body object
Examples
Request Body
{
"dataPool": "string"
}delete /s3/placements/{placementRule}/storage-classes/{storageClass}
Delete a storage class on a placement rule. Deletes the entire placement rule when specifying the STANDARD storage class. This API does not support multi-site setups.
Parameters
placementRule string path Required
The name of an (existing) placement rule.
storageClass string path Required
The name for storage class to remove, or STANDARD to remove the entire placement rule.
Examples
No request body required