582 lines
14 KiB
YAML
582 lines
14 KiB
YAML
# S3 API Endpoints
|
|
|
|
# List all buckets
|
|
/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: './schemas.yaml#/CreatePresignedUrlResponse'#/ListAllMyBucketsResult'
|
|
'401':
|
|
description: Unauthorized
|
|
|
|
# Bucket operations
|
|
/s3/{bucket}:
|
|
parameters:
|
|
- $ref: './parameters.yaml#/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: './parameters.yaml#/Prefix'
|
|
- $ref: './parameters.yaml#/Marker'
|
|
- $ref: './parameters.yaml#/MaxKeys'
|
|
- $ref: './parameters.yaml#/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: './schemas.yaml#/ListBucketResult'
|
|
- $ref: './schemas.yaml#/ListMultipartUploadsResult'
|
|
|
|
|
|
# Object operations
|
|
/s3/{bucket}/{key}:
|
|
parameters:
|
|
- $ref: './parameters.yaml#/BucketName'
|
|
- $ref: './parameters.yaml#/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: './schemas.yaml#/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: './schemas.yaml#/CompleteMultipartUpload'
|
|
responses:
|
|
'200':
|
|
description: Success
|
|
content:
|
|
application/xml:
|
|
schema:
|
|
oneOf:
|
|
- $ref: './schemas.yaml#/InitiateMultipartUploadResult'
|
|
- $ref: './schemas.yaml#/CompleteMultipartUploadResult'
|
|
|
|
# Management API Endpoints
|
|
|
|
/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: './schemas.yaml#/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: './schemas.yaml#/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: './schemas.yaml#/CreateCredentialRequest'
|
|
responses:
|
|
'201':
|
|
description: Credential created
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: './schemas.yaml#/Credential'
|
|
|
|
/api/credentials/{id}:
|
|
parameters:
|
|
- $ref: './parameters.yaml#/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: './schemas.yaml#/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: './schemas.yaml#/UpdateCredentialRequest'
|
|
responses:
|
|
'200':
|
|
description: Credential updated
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: './schemas.yaml#/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: './schemas.yaml#/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: './schemas.yaml#/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: './schemas.yaml#/CreateBucketRequest'
|
|
responses:
|
|
'201':
|
|
description: Bucket created
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: './schemas.yaml#/BucketDetail'
|
|
|
|
/api/buckets/{bucketName}:
|
|
parameters:
|
|
- $ref: './parameters.yaml#/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: './schemas.yaml#/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: './schemas.yaml#/ApiResponse'
|
|
|
|
/api/buckets/{bucketName}/objects:
|
|
parameters:
|
|
- $ref: './parameters.yaml#/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: './parameters.yaml#/Prefix'
|
|
responses:
|
|
'200':
|
|
description: Success
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: './schemas.yaml#/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: './schemas.yaml#/DeleteObjectsRequest'
|
|
responses:
|
|
'200':
|
|
description: Objects deleted
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: './schemas.yaml#/DeleteObjectsResponse'
|
|
|
|
/api/buckets/{bucketName}/objects/{objectKey}:
|
|
parameters:
|
|
- $ref: './parameters.yaml#/BucketName'
|
|
- $ref: './parameters.yaml#/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: './schemas.yaml#/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: './schemas.yaml#/ApiResponse'
|
|
|
|
/api/buckets/{bucketName}/multipart-uploads:
|
|
parameters:
|
|
- $ref: './parameters.yaml#/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: './schemas.yaml#/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: './schemas.yaml#/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: './schemas.yaml#/CreatePresignedUrlRequest'
|
|
responses:
|
|
'201':
|
|
description: Presigned URL created
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: './schemas.yaml#/CreatePresignedUrlResponse' |