1653 lines
44 KiB
YAML
1653 lines
44 KiB
YAML
openapi: 3.0.0
|
|
info:
|
|
version: 1.0.0
|
|
title: vStash S3 Compatible API
|
|
description: |
|
|
A high-performance S3-compatible object storage API with management console.
|
|
|
|
## Features
|
|
- Full S3 API compatibility for basic operations
|
|
- Multipart upload support
|
|
- Presigned URLs
|
|
- Management console API
|
|
- Enterprise storage backend
|
|
|
|
## Authentication
|
|
Uses AWS Signature Version 4 for S3 API endpoints and API keys for management endpoints.
|
|
contact:
|
|
email: support@vultr.com
|
|
name: vStash Support
|
|
url: https://www.vultr.com
|
|
x-logo:
|
|
url: https://www.vultr.com/dist/img/brand/vultr-logo-onwhite.svg
|
|
backgroundColor: '#fafafa'
|
|
altText: vStash - S3 Compatible API and Management
|
|
servers:
|
|
- url: https://vstash.vultr.com
|
|
description: Production server
|
|
- url: https://vstash-staging.vultr.com
|
|
description: Staging server
|
|
- url: http://localhost:8000
|
|
description: Development server
|
|
tags:
|
|
- name: S3 Buckets
|
|
description: S3 bucket operations
|
|
- name: S3 Objects
|
|
description: S3 object operations
|
|
- name: S3 Multipart
|
|
description: S3 multipart upload operations
|
|
- name: Management - Stats
|
|
description: System statistics and monitoring
|
|
- name: Management - Credentials
|
|
description: Access key and credential management
|
|
- name: Management - Buckets
|
|
description: Bucket management via console
|
|
- name: Management - Objects
|
|
description: Object management via console
|
|
- name: Management - Presigned URLs
|
|
description: Presigned URL management
|
|
paths:
|
|
/s3/:
|
|
get:
|
|
operationId: listBuckets
|
|
tags:
|
|
- S3 Buckets
|
|
summary: List buckets
|
|
description: Returns a list of all buckets owned by the authenticated sender of the request
|
|
security:
|
|
- AWS4-HMAC-SHA256: []
|
|
responses:
|
|
'200':
|
|
description: Success
|
|
content:
|
|
application/xml:
|
|
schema:
|
|
$ref: '#/components/schemas/CreatePresignedUrlResponse'
|
|
'401':
|
|
description: Unauthorized
|
|
/s3/{bucket}:
|
|
parameters:
|
|
- $ref: '#/components/parameters/BucketName'
|
|
head:
|
|
operationId: headBucket
|
|
tags:
|
|
- S3 Buckets
|
|
summary: Check if bucket exists
|
|
description: Determines if a bucket exists and you have permission to access it
|
|
security:
|
|
- AWS4-HMAC-SHA256: []
|
|
responses:
|
|
'200':
|
|
description: Bucket exists and you have access
|
|
put:
|
|
operationId: createBucket
|
|
tags:
|
|
- S3 Buckets
|
|
summary: Create bucket
|
|
description: Creates a new S3 bucket
|
|
security:
|
|
- AWS4-HMAC-SHA256: []
|
|
responses:
|
|
'200':
|
|
description: Bucket created successfully
|
|
headers:
|
|
Location:
|
|
description: Location of the created bucket
|
|
schema:
|
|
type: string
|
|
'409':
|
|
description: Bucket already exists
|
|
delete:
|
|
operationId: deleteBucket
|
|
tags:
|
|
- S3 Buckets
|
|
summary: Delete bucket
|
|
description: Deletes the S3 bucket. The bucket must be empty before it can be deleted
|
|
security:
|
|
- AWS4-HMAC-SHA256: []
|
|
responses:
|
|
'204':
|
|
description: Bucket deleted successfully
|
|
'409':
|
|
description: Bucket not empty
|
|
get:
|
|
operationId: listObjects
|
|
tags:
|
|
- S3 Buckets
|
|
summary: List objects in bucket
|
|
description: Returns some or all of the objects in a bucket
|
|
security:
|
|
- AWS4-HMAC-SHA256: []
|
|
parameters:
|
|
- $ref: '#/components/parameters/Prefix'
|
|
- $ref: '#/components/parameters/Marker'
|
|
- $ref: '#/components/parameters/MaxKeys'
|
|
- $ref: '#/components/parameters/Delimiter'
|
|
- name: uploads
|
|
in: query
|
|
description: List multipart uploads when present
|
|
schema:
|
|
type: string
|
|
enum:
|
|
- ''
|
|
responses:
|
|
'200':
|
|
description: Success
|
|
content:
|
|
application/xml:
|
|
schema:
|
|
oneOf:
|
|
- $ref: '#/components/schemas/ListBucketResult'
|
|
- $ref: '#/components/schemas/ListMultipartUploadsResult'
|
|
/s3/{bucket}/{key}:
|
|
parameters:
|
|
- $ref: '#/components/parameters/BucketName'
|
|
- $ref: '#/components/parameters/ObjectKey'
|
|
head:
|
|
operationId: headObject
|
|
tags:
|
|
- S3 Objects
|
|
summary: Get object metadata
|
|
description: Retrieves metadata from an object without returning the object itself
|
|
security:
|
|
- AWS4-HMAC-SHA256: []
|
|
responses:
|
|
'200':
|
|
description: Success
|
|
headers:
|
|
Content-Length:
|
|
schema:
|
|
type: integer
|
|
Content-Type:
|
|
schema:
|
|
type: string
|
|
ETag:
|
|
schema:
|
|
type: string
|
|
Last-Modified:
|
|
schema:
|
|
type: string
|
|
get:
|
|
operationId: getObject
|
|
tags:
|
|
- S3 Objects
|
|
summary: Get object
|
|
description: Retrieves objects from Amazon S3
|
|
security:
|
|
- AWS4-HMAC-SHA256: []
|
|
parameters:
|
|
- name: uploadId
|
|
in: query
|
|
description: List parts when present with upload ID
|
|
schema:
|
|
type: string
|
|
responses:
|
|
'200':
|
|
description: Success
|
|
content:
|
|
application/octet-stream:
|
|
schema:
|
|
type: string
|
|
format: binary
|
|
application/xml:
|
|
schema:
|
|
$ref: '#/components/schemas/ListPartsResult'
|
|
'404':
|
|
description: Object not found
|
|
put:
|
|
operationId: putObject
|
|
tags:
|
|
- S3 Objects
|
|
summary: Put object
|
|
description: Adds an object to a bucket
|
|
security:
|
|
- AWS4-HMAC-SHA256: []
|
|
parameters:
|
|
- name: partNumber
|
|
in: query
|
|
description: Part number for multipart upload
|
|
schema:
|
|
type: integer
|
|
minimum: 1
|
|
maximum: 10000
|
|
- name: uploadId
|
|
in: query
|
|
description: Upload ID for multipart upload part
|
|
schema:
|
|
type: string
|
|
requestBody:
|
|
description: Object data
|
|
content:
|
|
application/octet-stream:
|
|
schema:
|
|
type: string
|
|
format: binary
|
|
responses:
|
|
'200':
|
|
description: Success
|
|
headers:
|
|
ETag:
|
|
schema:
|
|
type: string
|
|
delete:
|
|
operationId: deleteObject
|
|
tags:
|
|
- S3 Objects
|
|
summary: Delete object
|
|
description: Removes the null version of an object and inserts a delete marker
|
|
security:
|
|
- AWS4-HMAC-SHA256: []
|
|
parameters:
|
|
- name: uploadId
|
|
in: query
|
|
description: Abort multipart upload when present
|
|
schema:
|
|
type: string
|
|
responses:
|
|
'204':
|
|
description: Object deleted successfully
|
|
post:
|
|
operationId: multipartUpload
|
|
tags:
|
|
- S3 Multipart
|
|
summary: Initiate or complete multipart upload
|
|
description: Initiates a multipart upload or completes a multipart upload by assembling uploaded parts
|
|
security:
|
|
- AWS4-HMAC-SHA256: []
|
|
parameters:
|
|
- name: uploads
|
|
in: query
|
|
description: Initiate multipart upload when present
|
|
schema:
|
|
type: string
|
|
enum:
|
|
- ''
|
|
- name: uploadId
|
|
in: query
|
|
description: Complete multipart upload with this upload ID
|
|
schema:
|
|
type: string
|
|
requestBody:
|
|
description: Complete multipart upload request
|
|
content:
|
|
application/xml:
|
|
schema:
|
|
$ref: '#/components/schemas/CompleteMultipartUpload'
|
|
responses:
|
|
'200':
|
|
description: Success
|
|
content:
|
|
application/xml:
|
|
schema:
|
|
oneOf:
|
|
- $ref: '#/components/schemas/InitiateMultipartUploadResult'
|
|
- $ref: '#/components/schemas/CompleteMultipartUploadResult'
|
|
/api/stats:
|
|
get:
|
|
operationId: getSystemStats
|
|
tags:
|
|
- Management - Stats
|
|
summary: Get system statistics
|
|
description: Returns overall system statistics including storage usage, object counts, etc.
|
|
security:
|
|
- ApiKey: []
|
|
responses:
|
|
'200':
|
|
description: Success
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/SystemStats'
|
|
/api/credentials:
|
|
get:
|
|
operationId: listCredentials
|
|
tags:
|
|
- Management - Credentials
|
|
summary: List credentials
|
|
description: Returns a list of all access credentials
|
|
security:
|
|
- ApiKey: []
|
|
responses:
|
|
'200':
|
|
description: Success
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/CredentialsList'
|
|
post:
|
|
operationId: createCredential
|
|
tags:
|
|
- Management - Credentials
|
|
summary: Create credential
|
|
description: Creates a new access credential
|
|
security:
|
|
- ApiKey: []
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/CreateCredentialRequest'
|
|
responses:
|
|
'201':
|
|
description: Credential created
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Credential'
|
|
/api/credentials/{id}:
|
|
parameters:
|
|
- $ref: '#/components/parameters/CredentialId'
|
|
get:
|
|
operationId: getCredential
|
|
tags:
|
|
- Management - Credentials
|
|
summary: Get credential details
|
|
description: Returns detailed information about a specific credential
|
|
security:
|
|
- ApiKey: []
|
|
responses:
|
|
'200':
|
|
description: Success
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/CredentialDetail'
|
|
put:
|
|
operationId: updateCredential
|
|
tags:
|
|
- Management - Credentials
|
|
summary: Update credential
|
|
description: Updates an existing credential
|
|
security:
|
|
- ApiKey: []
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/UpdateCredentialRequest'
|
|
responses:
|
|
'200':
|
|
description: Credential updated
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ApiResponse'
|
|
delete:
|
|
operationId: deleteCredential
|
|
tags:
|
|
- Management - Credentials
|
|
summary: Delete credential
|
|
description: Deletes an access credential
|
|
security:
|
|
- ApiKey: []
|
|
responses:
|
|
'200':
|
|
description: Credential deleted
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ApiResponse'
|
|
/api/buckets:
|
|
get:
|
|
operationId: listBucketsManagement
|
|
tags:
|
|
- Management - Buckets
|
|
summary: List all buckets
|
|
description: Returns a list of all buckets with detailed information
|
|
security:
|
|
- ApiKey: []
|
|
responses:
|
|
'200':
|
|
description: Success
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/BucketsList'
|
|
post:
|
|
operationId: createBucketManagement
|
|
tags:
|
|
- Management - Buckets
|
|
summary: Create bucket
|
|
description: Creates a new bucket via management API
|
|
security:
|
|
- ApiKey: []
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/CreateBucketRequest'
|
|
responses:
|
|
'201':
|
|
description: Bucket created
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/BucketDetail'
|
|
/api/buckets/{bucketName}:
|
|
parameters:
|
|
- $ref: '#/components/parameters/BucketName'
|
|
get:
|
|
operationId: getBucketDetails
|
|
tags:
|
|
- Management - Buckets
|
|
summary: Get bucket details
|
|
description: Returns detailed information about a specific bucket including objects
|
|
security:
|
|
- ApiKey: []
|
|
responses:
|
|
'200':
|
|
description: Success
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/BucketDetail'
|
|
delete:
|
|
operationId: deleteBucketManagement
|
|
tags:
|
|
- Management - Buckets
|
|
summary: Delete bucket
|
|
description: Deletes a bucket via management API
|
|
security:
|
|
- ApiKey: []
|
|
responses:
|
|
'200':
|
|
description: Bucket deleted
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ApiResponse'
|
|
/api/buckets/{bucketName}/objects:
|
|
parameters:
|
|
- $ref: '#/components/parameters/BucketName'
|
|
get:
|
|
operationId: listObjectsManagement
|
|
tags:
|
|
- Management - Objects
|
|
summary: List objects in bucket
|
|
description: Returns a list of objects in the specified bucket
|
|
security:
|
|
- ApiKey: []
|
|
parameters:
|
|
- $ref: '#/components/parameters/Prefix'
|
|
responses:
|
|
'200':
|
|
description: Success
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ObjectsList'
|
|
delete:
|
|
operationId: deleteMultipleObjects
|
|
tags:
|
|
- Management - Objects
|
|
summary: Delete multiple objects
|
|
description: Deletes multiple objects from a bucket
|
|
security:
|
|
- ApiKey: []
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/DeleteObjectsRequest'
|
|
responses:
|
|
'200':
|
|
description: Objects deleted
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/DeleteObjectsResponse'
|
|
/api/buckets/{bucketName}/objects/{objectKey}:
|
|
parameters:
|
|
- $ref: '#/components/parameters/BucketName'
|
|
- $ref: '#/components/parameters/ObjectKey'
|
|
get:
|
|
operationId: getObjectDetails
|
|
tags:
|
|
- Management - Objects
|
|
summary: Get object details
|
|
description: Returns detailed information about a specific object
|
|
security:
|
|
- ApiKey: []
|
|
responses:
|
|
'200':
|
|
description: Success
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ObjectDetail'
|
|
delete:
|
|
operationId: deleteObjectManagement
|
|
tags:
|
|
- Management - Objects
|
|
summary: Delete object
|
|
description: Deletes a specific object
|
|
security:
|
|
- ApiKey: []
|
|
responses:
|
|
'200':
|
|
description: Object deleted
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ApiResponse'
|
|
/api/buckets/{bucketName}/multipart-uploads:
|
|
parameters:
|
|
- $ref: '#/components/parameters/BucketName'
|
|
get:
|
|
operationId: listMultipartUploads
|
|
tags:
|
|
- Management - Objects
|
|
summary: List multipart uploads
|
|
description: Returns active multipart uploads for a bucket
|
|
security:
|
|
- ApiKey: []
|
|
responses:
|
|
'200':
|
|
description: Success
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/MultipartUploadsList'
|
|
/api/presigned-urls:
|
|
get:
|
|
operationId: listPresignedUrls
|
|
tags:
|
|
- Management - Presigned URLs
|
|
summary: List presigned URLs
|
|
description: Returns active presigned URLs
|
|
security:
|
|
- ApiKey: []
|
|
responses:
|
|
'200':
|
|
description: Success
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/PresignedUrlsList'
|
|
post:
|
|
operationId: createPresignedUrl
|
|
tags:
|
|
- Management - Presigned URLs
|
|
summary: Create presigned URL
|
|
description: Generates a new presigned URL
|
|
security:
|
|
- ApiKey: []
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/CreatePresignedUrlRequest'
|
|
responses:
|
|
'201':
|
|
description: Presigned URL created
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/CreatePresignedUrlResponse'
|
|
|
|
/api/buckets/{bucketName}/objects/{objectKey}/presigned-upload:
|
|
parameters:
|
|
- $ref: '#/components/parameters/BucketName'
|
|
- $ref: '#/components/parameters/ObjectKey'
|
|
post:
|
|
operationId: createPresignedUpload
|
|
tags:
|
|
- Management - Presigned URLs
|
|
summary: Create presigned upload URL
|
|
description: Creates an empty object and returns a presigned URL for uploading content
|
|
security:
|
|
- ApiKey: []
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/CreatePresignedUploadRequest'
|
|
responses:
|
|
'201':
|
|
description: Presigned URL created
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/CreatePresignedUrlResponse'
|
|
components:
|
|
schemas:
|
|
CreatePresignedUrlResponse:
|
|
type: object
|
|
properties:
|
|
url:
|
|
type: string
|
|
example: /my-bucket/file.txt?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAIOSFODNN7EXAMPLE%2F20230115%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20230115T103000Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=abc123&hash=def456
|
|
CreatePresignedUploadRequest:
|
|
type: object
|
|
required:
|
|
- access_key
|
|
properties:
|
|
access_key:
|
|
type: string
|
|
example: "AKIAIOSFODNN7EXAMPLE"
|
|
expires_in:
|
|
type: integer
|
|
minimum: 1
|
|
maximum: 604800
|
|
default: 3600
|
|
example: 3600
|
|
content_type:
|
|
type: string
|
|
default: "application/octet-stream"
|
|
example: "image/jpeg"
|
|
ObjectSummary:
|
|
type: object
|
|
properties:
|
|
Key:
|
|
type: string
|
|
example: photos/2023/vacation.jpg
|
|
LastModified:
|
|
type: string
|
|
format: date-time
|
|
example: '2023-01-15T10:30:00.000Z'
|
|
ETag:
|
|
type: string
|
|
example: '"9bb58f26192e4ba00f01e2e7b136bbd8"'
|
|
Size:
|
|
type: integer
|
|
example: 1024000
|
|
StorageClass:
|
|
type: string
|
|
example: STANDARD
|
|
ListBucketResult:
|
|
type: object
|
|
xml:
|
|
name: ListBucketResult
|
|
namespace: http://s3.amazonaws.com/doc/2006-03-01/
|
|
properties:
|
|
Name:
|
|
type: string
|
|
example: my-bucket
|
|
Prefix:
|
|
type: string
|
|
example: photos/
|
|
Marker:
|
|
type: string
|
|
example: photos/2023/
|
|
MaxKeys:
|
|
type: integer
|
|
example: 1000
|
|
IsTruncated:
|
|
type: boolean
|
|
example: false
|
|
Contents:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/ObjectSummary'
|
|
ListMultipartUploadsResult:
|
|
type: object
|
|
xml:
|
|
name: ListMultipartUploadsResult
|
|
namespace: http://s3.amazonaws.com/doc/2006-03-01/
|
|
properties:
|
|
Bucket:
|
|
type: string
|
|
example: my-bucket
|
|
KeyMarker:
|
|
type: string
|
|
example: ''
|
|
UploadIdMarker:
|
|
type: string
|
|
example: ''
|
|
NextKeyMarker:
|
|
type: string
|
|
example: ''
|
|
NextUploadIdMarker:
|
|
type: string
|
|
example: ''
|
|
MaxUploads:
|
|
type: integer
|
|
example: 1000
|
|
IsTruncated:
|
|
type: boolean
|
|
example: false
|
|
Upload:
|
|
type: array
|
|
Part:
|
|
type: object
|
|
properties:
|
|
PartNumber:
|
|
type: integer
|
|
example: 1
|
|
LastModified:
|
|
type: string
|
|
format: date-time
|
|
example: '2023-01-15T10:30:00.000Z'
|
|
ETag:
|
|
type: string
|
|
example: '"9bb58f26192e4ba00f01e2e7b136bbd8"'
|
|
Size:
|
|
type: integer
|
|
example: 5242880
|
|
ListPartsResult:
|
|
type: object
|
|
xml:
|
|
name: ListPartsResult
|
|
namespace: http://s3.amazonaws.com/doc/2006-03-01/
|
|
properties:
|
|
Bucket:
|
|
type: string
|
|
example: my-bucket
|
|
Key:
|
|
type: string
|
|
example: large-file.zip
|
|
UploadId:
|
|
type: string
|
|
example: upload_12345_abcdef
|
|
StorageClass:
|
|
type: string
|
|
example: STANDARD
|
|
PartNumberMarker:
|
|
type: integer
|
|
example: 0
|
|
NextPartNumberMarker:
|
|
type: integer
|
|
example: 5
|
|
MaxParts:
|
|
type: integer
|
|
example: 1000
|
|
IsTruncated:
|
|
type: boolean
|
|
example: false
|
|
Part:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/Part'
|
|
CompleteMultipartUpload:
|
|
type: object
|
|
xml:
|
|
name: CompleteMultipartUpload
|
|
properties:
|
|
Part:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
PartNumber:
|
|
type: integer
|
|
example: 1
|
|
ETag:
|
|
type: string
|
|
example: '"9bb58f26192e4ba00f01e2e7b136bbd8"'
|
|
InitiateMultipartUploadResult:
|
|
type: object
|
|
xml:
|
|
name: InitiateMultipartUploadResult
|
|
namespace: http://s3.amazonaws.com/doc/2006-03-01/
|
|
properties:
|
|
Bucket:
|
|
type: string
|
|
example: my-bucket
|
|
Key:
|
|
type: string
|
|
example: large-file.zip
|
|
UploadId:
|
|
type: string
|
|
example: upload_12345_abcdef
|
|
CompleteMultipartUploadResult:
|
|
type: object
|
|
xml:
|
|
name: CompleteMultipartUploadResult
|
|
namespace: http://s3.amazonaws.com/doc/2006-03-01/
|
|
properties:
|
|
Location:
|
|
type: string
|
|
example: /my-bucket/large-file.zip
|
|
Bucket:
|
|
type: string
|
|
example: my-bucket
|
|
Key:
|
|
type: string
|
|
example: large-file.zip
|
|
ETag:
|
|
type: string
|
|
example: '"9bb58f26192e4ba00f01e2e7b136bbd8-5"'
|
|
SystemStats:
|
|
type: object
|
|
properties:
|
|
credentials:
|
|
type: integer
|
|
example: 5
|
|
description: Total number of access credentials
|
|
buckets:
|
|
type: integer
|
|
example: 12
|
|
description: Total number of buckets
|
|
objects:
|
|
type: integer
|
|
example: 1250
|
|
description: Total number of objects
|
|
total_storage:
|
|
type: integer
|
|
example: 1073741824
|
|
description: Total storage used in bytes
|
|
total_storage_human:
|
|
type: string
|
|
example: 1.0 GB
|
|
description: Human-readable storage size
|
|
active_multipart_uploads:
|
|
type: integer
|
|
example: 3
|
|
description: Number of active multipart uploads
|
|
active_presigned_urls:
|
|
type: integer
|
|
example: 15
|
|
description: Number of active presigned URLs
|
|
CredentialSummary:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: integer
|
|
example: 1
|
|
access_key:
|
|
type: string
|
|
example: AKIAIOSFODNN7EXAMPLE
|
|
user_name:
|
|
type: string
|
|
example: john-doe
|
|
nullable: true
|
|
is_active:
|
|
type: boolean
|
|
example: true
|
|
created_at:
|
|
type: string
|
|
format: date-time
|
|
example: '2023-01-15T10:30:00Z'
|
|
bucket_count:
|
|
type: integer
|
|
example: 3
|
|
CredentialsList:
|
|
type: object
|
|
properties:
|
|
credentials:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/CredentialSummary'
|
|
CreateCredentialRequest:
|
|
type: object
|
|
properties:
|
|
user_name:
|
|
type: string
|
|
example: john-doe
|
|
description: Optional user name
|
|
access_key:
|
|
type: string
|
|
example: AKIAIOSFODNN7EXAMPLE
|
|
description: Optional custom access key (auto-generated if not provided)
|
|
secret_key:
|
|
type: string
|
|
example: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
|
|
description: Optional custom secret key (auto-generated if not provided)
|
|
Credential:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: integer
|
|
example: 1
|
|
access_key:
|
|
type: string
|
|
example: AKIAIOSFODNN7EXAMPLE
|
|
secret_key:
|
|
type: string
|
|
example: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
|
|
description: Only returned when creating credential
|
|
user_name:
|
|
type: string
|
|
example: john-doe
|
|
nullable: true
|
|
is_active:
|
|
type: boolean
|
|
example: true
|
|
created_at:
|
|
type: string
|
|
format: date-time
|
|
example: '2023-01-15T10:30:00Z'
|
|
BucketSummary:
|
|
type: object
|
|
properties:
|
|
name:
|
|
type: string
|
|
example: my-bucket
|
|
region:
|
|
type: string
|
|
example: us-east-1
|
|
owner:
|
|
type: string
|
|
example: john-doe
|
|
created_at:
|
|
type: string
|
|
format: date-time
|
|
example: '2023-01-15T10:30:00Z'
|
|
object_count:
|
|
type: integer
|
|
example: 150
|
|
total_size:
|
|
type: integer
|
|
example: 1073741824
|
|
total_size_human:
|
|
type: string
|
|
example: 1.0 GB
|
|
CredentialDetail:
|
|
allOf:
|
|
- $ref: '#/components/schemas/CredentialSummary'
|
|
- type: object
|
|
properties:
|
|
buckets:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/BucketSummary'
|
|
UpdateCredentialRequest:
|
|
type: object
|
|
properties:
|
|
user_name:
|
|
type: string
|
|
example: john-doe
|
|
is_active:
|
|
type: boolean
|
|
example: true
|
|
ApiResponse:
|
|
type: object
|
|
properties:
|
|
message:
|
|
type: string
|
|
example: Operation completed successfully
|
|
BucketsList:
|
|
type: object
|
|
properties:
|
|
buckets:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/BucketSummary'
|
|
CreateBucketRequest:
|
|
type: object
|
|
required:
|
|
- name
|
|
- owner_id
|
|
properties:
|
|
name:
|
|
type: string
|
|
example: my-new-bucket
|
|
pattern: ^[a-z0-9\-\.]+$
|
|
owner_id:
|
|
type: integer
|
|
example: 1
|
|
region:
|
|
type: string
|
|
example: us-east-1
|
|
default: us-east-1
|
|
ObjectInfo:
|
|
type: object
|
|
properties:
|
|
key:
|
|
type: string
|
|
example: photos/vacation.jpg
|
|
size:
|
|
type: integer
|
|
example: 1024000
|
|
size_human:
|
|
type: string
|
|
example: 1.0 MB
|
|
content_type:
|
|
type: string
|
|
example: image/jpeg
|
|
etag:
|
|
type: string
|
|
example: 9bb58f26192e4ba00f01e2e7b136bbd8
|
|
is_multipart:
|
|
type: boolean
|
|
example: false
|
|
created_at:
|
|
type: string
|
|
format: date-time
|
|
example: '2023-01-15T10:30:00Z'
|
|
BucketDetail:
|
|
allOf:
|
|
- $ref: '#/components/schemas/BucketSummary'
|
|
- type: object
|
|
properties:
|
|
objects:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/ObjectInfo'
|
|
ObjectsList:
|
|
type: object
|
|
properties:
|
|
objects:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/ObjectInfo'
|
|
DeleteObjectsRequest:
|
|
type: object
|
|
required:
|
|
- keys
|
|
properties:
|
|
keys:
|
|
type: array
|
|
items:
|
|
type: string
|
|
example:
|
|
- file1.txt
|
|
- file2.txt
|
|
- folder/file3.txt
|
|
DeleteObjectsResponse:
|
|
type: object
|
|
properties:
|
|
deleted:
|
|
type: array
|
|
items:
|
|
type: string
|
|
example:
|
|
- file1.txt
|
|
- file2.txt
|
|
ObjectDetail:
|
|
allOf:
|
|
- $ref: '#/components/schemas/ObjectInfo'
|
|
- type: object
|
|
properties:
|
|
part_count:
|
|
type: integer
|
|
example: 0
|
|
metadata:
|
|
type: object
|
|
additionalProperties:
|
|
type: string
|
|
example:
|
|
user-id: '12345'
|
|
category: photos
|
|
storage_path:
|
|
type: string
|
|
example: my-bucket/objects/ab/cd/abcdef123456...
|
|
updated_at:
|
|
type: string
|
|
format: date-time
|
|
example: '2023-01-15T10:30:00Z'
|
|
MultipartUploadInfo:
|
|
type: object
|
|
properties:
|
|
upload_id:
|
|
type: string
|
|
example: upload_12345_abcdef
|
|
object_key:
|
|
type: string
|
|
example: large-file.zip
|
|
initiated_by:
|
|
type: string
|
|
example: john-doe
|
|
content_type:
|
|
type: string
|
|
example: application/zip
|
|
initiated_at:
|
|
type: string
|
|
format: date-time
|
|
example: '2023-01-15T10:30:00Z'
|
|
part_count:
|
|
type: integer
|
|
example: 5
|
|
total_size:
|
|
type: integer
|
|
example: 26214400
|
|
total_size_human:
|
|
type: string
|
|
example: 25.0 MB
|
|
MultipartUploadsList:
|
|
type: object
|
|
properties:
|
|
uploads:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/MultipartUploadInfo'
|
|
PresignedUrlInfo:
|
|
type: object
|
|
properties:
|
|
bucket_name:
|
|
type: string
|
|
example: my-bucket
|
|
object_key:
|
|
type: string
|
|
example: file.txt
|
|
method:
|
|
type: string
|
|
enum:
|
|
- GET
|
|
- PUT
|
|
- POST
|
|
- DELETE
|
|
example: GET
|
|
access_key:
|
|
type: string
|
|
example: AKIAIOSFODNN7EXAMPLE
|
|
expires_at:
|
|
type: string
|
|
format: date-time
|
|
example: '2023-01-15T11:30:00Z'
|
|
created_at:
|
|
type: string
|
|
format: date-time
|
|
example: '2023-01-15T10:30:00Z'
|
|
url:
|
|
type: string
|
|
example: "/my-bucket/file.txt?X-Amz-Algorithm=AWS4-HMAC-SHA256&..."
|
|
PresignedUrlsList:
|
|
type: object
|
|
properties:
|
|
urls:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/PresignedUrlInfo'
|
|
CreatePresignedUrlRequest:
|
|
type: object
|
|
required:
|
|
- bucket_name
|
|
- object_key
|
|
- access_key
|
|
properties:
|
|
bucket_name:
|
|
type: string
|
|
example: my-bucket
|
|
object_key:
|
|
type: string
|
|
example: file.txt
|
|
method:
|
|
type: string
|
|
enum:
|
|
- GET
|
|
- PUT
|
|
- POST
|
|
- DELETE
|
|
default: GET
|
|
example: GET
|
|
expires_in:
|
|
type: integer
|
|
minimum: 1
|
|
maximum: 604800
|
|
default: 3600
|
|
example: 3600
|
|
description: Expiration time in seconds (max 7 days)
|
|
access_key:
|
|
type: string
|
|
example: AKIAIOSFODNN7EXAMPLE
|
|
Bucket:
|
|
type: object
|
|
properties:
|
|
Name:
|
|
type: string
|
|
example: my-bucket
|
|
CreationDate:
|
|
type: string
|
|
format: date-time
|
|
example: '2023-01-15T10:30:00.000Z'
|
|
S3Error:
|
|
type: object
|
|
xml:
|
|
name: Error
|
|
properties:
|
|
Code:
|
|
type: string
|
|
example: NoSuchBucket
|
|
Message:
|
|
type: string
|
|
example: The specified bucket does not exist
|
|
Resource:
|
|
type: string
|
|
example: /mybucket
|
|
RequestId:
|
|
type: string
|
|
example: 4442587FB7D0A2F9
|
|
ListAllMyBucketsResult:
|
|
type: object
|
|
xml:
|
|
name: ListAllMyBucketsResult
|
|
namespace: http://s3.amazonaws.com/doc/2006-03-01/
|
|
properties:
|
|
Buckets:
|
|
type: object
|
|
properties:
|
|
Bucket:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/Bucket'
|
|
MultipartUpload:
|
|
type: object
|
|
properties:
|
|
Key:
|
|
type: string
|
|
example: large-file.zip
|
|
UploadId:
|
|
type: string
|
|
example: upload_12345_abcdef
|
|
Initiated:
|
|
type: string
|
|
format: date-time
|
|
example: '2023-01-15T10:30:00.000Z'
|
|
StorageClass:
|
|
type: string
|
|
example: STANDARD
|
|
ApiError:
|
|
type: object
|
|
properties:
|
|
error:
|
|
type: string
|
|
example: Resource not found
|
|
code:
|
|
type: string
|
|
example: NOT_FOUND
|
|
message:
|
|
type: string
|
|
example: The requested resource could not be found
|
|
parameters:
|
|
BucketName:
|
|
name: bucket
|
|
in: path
|
|
required: true
|
|
description: Name of the S3 bucket
|
|
schema:
|
|
type: string
|
|
pattern: ^[a-z0-9\-\.]+$
|
|
minLength: 3
|
|
maxLength: 63
|
|
example: my-bucket
|
|
Prefix:
|
|
name: prefix
|
|
in: query
|
|
description: Limits the response to keys that begin with the specified prefix
|
|
schema:
|
|
type: string
|
|
maxLength: 255
|
|
example: photos/
|
|
Marker:
|
|
name: marker
|
|
in: query
|
|
description: Specifies the key to start with when listing objects
|
|
schema:
|
|
type: string
|
|
maxLength: 255
|
|
example: photos/2023/
|
|
MaxKeys:
|
|
name: max-keys
|
|
in: query
|
|
description: Maximum number of keys to return
|
|
schema:
|
|
type: integer
|
|
minimum: 1
|
|
maximum: 1000
|
|
default: 1000
|
|
example: 100
|
|
Delimiter:
|
|
name: delimiter
|
|
in: query
|
|
description: Character used to group keys
|
|
schema:
|
|
type: string
|
|
maxLength: 1
|
|
example: /
|
|
ObjectKey:
|
|
name: key
|
|
in: path
|
|
required: true
|
|
description: Object key (file path) within the bucket
|
|
schema:
|
|
type: string
|
|
maxLength: 255
|
|
example: folder/file.txt
|
|
style: simple
|
|
explode: false
|
|
CredentialId:
|
|
name: id
|
|
in: path
|
|
required: true
|
|
description: Unique identifier for the credential
|
|
schema:
|
|
type: integer
|
|
minimum: 1
|
|
example: 1
|
|
PartNumber:
|
|
name: partNumber
|
|
in: query
|
|
description: Part number for multipart upload (1-10,000)
|
|
schema:
|
|
type: integer
|
|
minimum: 1
|
|
maximum: 10000
|
|
example: 1
|
|
UploadId:
|
|
name: uploadId
|
|
in: query
|
|
description: Upload ID for multipart upload operations
|
|
schema:
|
|
type: string
|
|
maxLength: 64
|
|
example: upload_12345_abcdef
|
|
VersionId:
|
|
name: versionId
|
|
in: query
|
|
description: Version ID of the object (if versioning is enabled)
|
|
schema:
|
|
type: string
|
|
maxLength: 64
|
|
example: version_123
|
|
ContentMD5:
|
|
name: Content-MD5
|
|
in: header
|
|
description: MD5 digest of the request body
|
|
schema:
|
|
type: string
|
|
pattern: ^[A-Za-z0-9+/]+=*$
|
|
example: n4bQgYhMfWWaL+qgxVrQFaO/TxsrC4Is0V1sFbDwCgg=
|
|
ContentType:
|
|
name: Content-Type
|
|
in: header
|
|
description: MIME type of the object
|
|
schema:
|
|
type: string
|
|
maxLength: 255
|
|
default: application/octet-stream
|
|
example: image/jpeg
|
|
ContentLength:
|
|
name: Content-Length
|
|
in: header
|
|
description: Size of the object in bytes
|
|
schema:
|
|
type: integer
|
|
minimum: 0
|
|
example: 1024000
|
|
Range:
|
|
name: Range
|
|
in: header
|
|
description: Downloads the specified range bytes of an object
|
|
schema:
|
|
type: string
|
|
pattern: ^bytes=\d+-\d*$
|
|
example: bytes=0-1023
|
|
IfMatch:
|
|
name: If-Match
|
|
in: header
|
|
description: Return the object only if its ETag matches the specified value
|
|
schema:
|
|
type: string
|
|
example: '"9bb58f26192e4ba00f01e2e7b136bbd8"'
|
|
IfNoneMatch:
|
|
name: If-None-Match
|
|
in: header
|
|
description: Return the object only if its ETag does not match the specified value
|
|
schema:
|
|
type: string
|
|
example: '"9bb58f26192e4ba00f01e2e7b136bbd8"'
|
|
IfModifiedSince:
|
|
name: If-Modified-Since
|
|
in: header
|
|
description: Return the object only if it has been modified since the specified time
|
|
schema:
|
|
type: string
|
|
format: date-time
|
|
example: Wed, 15 Jan 2023 10:30:00 GMT
|
|
IfUnmodifiedSince:
|
|
name: If-Unmodified-Since
|
|
in: header
|
|
description: Return the object only if it has not been modified since the specified time
|
|
schema:
|
|
type: string
|
|
format: date-time
|
|
example: Wed, 15 Jan 2023 10:30:00 GMT
|
|
CacheControl:
|
|
name: Cache-Control
|
|
in: header
|
|
description: Specifies caching behavior for the object
|
|
schema:
|
|
type: string
|
|
example: max-age=3600
|
|
ContentDisposition:
|
|
name: Content-Disposition
|
|
in: header
|
|
description: Specifies presentational information for the object
|
|
schema:
|
|
type: string
|
|
example: attachment; filename="file.txt"
|
|
ContentEncoding:
|
|
name: Content-Encoding
|
|
in: header
|
|
description: Specifies what content encodings have been applied to the object
|
|
schema:
|
|
type: string
|
|
example: gzip
|
|
ContentLanguage:
|
|
name: Content-Language
|
|
in: header
|
|
description: Language the content is in
|
|
schema:
|
|
type: string
|
|
example: en-US
|
|
Expires:
|
|
name: Expires
|
|
in: header
|
|
description: Date and time when the object expires
|
|
schema:
|
|
type: string
|
|
format: date-time
|
|
example: Wed, 15 Jan 2024 10:30:00 GMT
|
|
ServerSideEncryption:
|
|
name: x-amz-server-side-encryption
|
|
in: header
|
|
description: Server-side encryption algorithm to use
|
|
schema:
|
|
type: string
|
|
enum:
|
|
- AES256
|
|
- aws:kms
|
|
example: AES256
|
|
StorageClass:
|
|
name: x-amz-storage-class
|
|
in: header
|
|
description: Storage class for the object
|
|
schema:
|
|
type: string
|
|
enum:
|
|
- STANDARD
|
|
- REDUCED_REDUNDANCY
|
|
- GLACIER
|
|
- DEEP_ARCHIVE
|
|
default: STANDARD
|
|
example: STANDARD
|
|
Tagging:
|
|
name: x-amz-tagging
|
|
in: header
|
|
description: Object tag set as a query string
|
|
schema:
|
|
type: string
|
|
example: key1=value1&key2=value2
|
|
MetadataDirective:
|
|
name: x-amz-metadata-directive
|
|
in: header
|
|
description: Specifies whether metadata is copied from the source object or replaced
|
|
schema:
|
|
type: string
|
|
enum:
|
|
- COPY
|
|
- REPLACE
|
|
default: COPY
|
|
example: REPLACE
|
|
CopySource:
|
|
name: x-amz-copy-source
|
|
in: header
|
|
description: Source bucket and object for copy operations
|
|
schema:
|
|
type: string
|
|
example: /source-bucket/source-object
|
|
ACL:
|
|
name: x-amz-acl
|
|
in: header
|
|
description: Canned ACL to apply to the object
|
|
schema:
|
|
type: string
|
|
enum:
|
|
- private
|
|
- public-read
|
|
- public-read-write
|
|
- authenticated-read
|
|
default: private
|
|
example: public-read
|
|
securitySchemes:
|
|
AWS4-HMAC-SHA256:
|
|
type: apiKey
|
|
description: |
|
|
AWS Signature Version 4 authentication for S3 API endpoints.
|
|
|
|
## Authentication Process
|
|
1. Create a canonical request
|
|
2. Create a string to sign
|
|
3. Calculate the signature using HMAC-SHA256
|
|
4. Add the authorization header or query parameters
|
|
|
|
## Authorization Header Format
|
|
```
|
|
Authorization: AWS4-HMAC-SHA256 Credential=<AccessKey>/<Date>/<Region>/s3/aws4_request,SignedHeaders=<SignedHeaders>,Signature=<Signature>
|
|
```
|
|
|
|
## Query String Format (for presigned URLs)
|
|
```
|
|
?X-Amz-Algorithm=AWS4-HMAC-SHA256
|
|
&X-Amz-Credential=<AccessKey>/<Date>/<Region>/s3/aws4_request
|
|
&X-Amz-Date=<Timestamp>
|
|
&X-Amz-Expires=<ExpirationTime>
|
|
&X-Amz-SignedHeaders=<SignedHeaders>
|
|
&X-Amz-Signature=<Signature>
|
|
```
|
|
|
|
## Required Headers
|
|
- `Authorization`: The calculated authorization value
|
|
- `x-amz-date`: Timestamp in ISO 8601 format (YYYYMMDDTHHMMSSZ)
|
|
- `x-amz-content-sha256`: SHA256 hash of the request payload
|
|
|
|
## Example
|
|
```
|
|
Authorization: AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE/20230115/us-east-1/s3/aws4_request,SignedHeaders=host;x-amz-date,Signature=fe5f80f77d5fa3beca038a248ff027d0445342fe2855ddc963176630326f1024
|
|
x-amz-date: 20230115T103000Z
|
|
x-amz-content-sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
|
|
```
|
|
name: Authorization
|
|
in: header
|
|
ApiKey:
|
|
type: apiKey
|
|
description: |
|
|
API key authentication for management console endpoints.
|
|
|
|
## Usage
|
|
Include your API key in the `X-API-Key` header for all management API requests.
|
|
|
|
## Example
|
|
```
|
|
X-API-Key: your-api-key-here
|
|
```
|
|
|
|
## Obtaining an API Key
|
|
API keys can be generated through the management console or by contacting your administrator.
|
|
|
|
## Permissions
|
|
API keys have full access to the management API and should be kept secure.
|
|
name: X-API-Key
|
|
in: header
|
|
BearerAuth:
|
|
type: http
|
|
scheme: bearer
|
|
bearerFormat: JWT
|
|
description: |
|
|
JWT Bearer token authentication (optional alternative for management API).
|
|
|
|
## Usage
|
|
Include the JWT token in the Authorization header:
|
|
```
|
|
Authorization: Bearer <jwt-token>
|
|
```
|
|
|
|
## Token Structure
|
|
The JWT token contains claims about the user's permissions and expires after a set period.
|
|
|
|
## Example
|
|
```
|
|
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
|
|
```
|
|
BasicAuth:
|
|
type: http
|
|
scheme: basic
|
|
description: |
|
|
HTTP Basic authentication (for simple setups).
|
|
|
|
## Usage
|
|
Encode username:password in Base64 and include in Authorization header:
|
|
```
|
|
Authorization: Basic <base64-encoded-credentials>
|
|
```
|
|
|
|
## Example
|
|
```
|
|
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
|
|
```
|
|
|
|
## Note
|
|
Basic auth should only be used over HTTPS in production environments.
|
|
responses:
|
|
'400':
|
|
description: Bad Request
|
|
content:
|
|
application/xml:
|
|
schema:
|
|
$ref: '#/components/schemas/S3Error'
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ApiError'
|
|
'401':
|
|
description: Unauthorized
|
|
content:
|
|
application/xml:
|
|
schema:
|
|
$ref: '#/components/schemas/S3Error'
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ApiError'
|
|
'403':
|
|
description: Forbidden
|
|
content:
|
|
application/xml:
|
|
schema:
|
|
$ref: '#/components/schemas/S3Error'
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ApiError'
|
|
'404':
|
|
description: Not Found
|
|
content:
|
|
application/xml:
|
|
schema:
|
|
$ref: '#/components/schemas/S3Error'
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ApiError'
|
|
'409':
|
|
description: Conflict
|
|
content:
|
|
application/xml:
|
|
schema:
|
|
$ref: '#/components/schemas/S3Error'
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ApiError'
|
|
'500':
|
|
description: Internal Server Error
|
|
content:
|
|
application/xml:
|
|
schema:
|
|
$ref: '#/components/schemas/S3Error'
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ApiError'
|