# 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'