CubeFS AC Ls API

openapi: 3.2.0
info:
  title: CubeFS S3-Compatible AC Ls API
  description: The CubeFS ObjectNode provides an S3-compatible object storage interface that allows applications using AWS S3 SDKs and tools to interact with CubeFS storage without modification.
  version: '3.3'
  contact:
    name: CubeFS Community
    url: https://cubefs.io/community/overview.html
servers:
- url: http://{objectNodeHost}:{objectNodePort}
  description: CubeFS ObjectNode S3-compatible API server
  variables:
    objectNodeHost:
      default: 127.0.0.1
      description: IP address or hostname of the CubeFS ObjectNode.
    objectNodePort:
      default: '17410'
      description: Listening port of the CubeFS ObjectNode.
security:
- awsAuth: []
tags:
- name: ACLs
  description: Access control list operations for buckets and objects. Supports getting and setting ACLs to control access at the bucket and object level.
paths:
  /{bucket}?acl:
    get:
      operationId: getBucketAcl
      summary: CubeFS Get bucket ACL
      description: Returns the access control list for the specified bucket. The ACL defines which accounts or groups have read and write access to the bucket.
      tags:
      - ACLs
      parameters:
      - $ref: '#/components/parameters/bucket'
      responses:
        '200':
          description: Bucket ACL retrieved successfully.
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/AccessControlPolicy'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: putBucketAcl
      summary: CubeFS Set bucket ACL
      description: Sets the access control list for the specified bucket. Supports canned ACLs (private, public-read) or a custom ACL with explicit grants.
      tags:
      - ACLs
      parameters:
      - $ref: '#/components/parameters/bucket'
      - name: x-amz-acl
        in: header
        required: false
        description: Canned ACL to apply. Mutually exclusive with request body ACL.
        schema:
          type: string
          enum:
          - private
          - public-read
          - public-read-write
      requestBody:
        required: false
        content:
          application/xml:
            schema:
              $ref: '#/components/schemas/AccessControlPolicy'
      responses:
        '200':
          description: Bucket ACL set successfully.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  responses:
    BadRequest:
      description: The request was malformed or contained invalid parameters.
      content:
        application/xml:
          schema:
            $ref: '#/components/schemas/S3Error'
    Unauthorized:
      description: Authentication credentials are missing, invalid, or the signature does not match.
      content:
        application/xml:
          schema:
            $ref: '#/components/schemas/S3Error'
    NotFound:
      description: The specified bucket or object does not exist.
      content:
        application/xml:
          schema:
            $ref: '#/components/schemas/S3Error'
  schemas:
    AccessControlPolicy:
      type: object
      description: Access control policy for a bucket or object.
      properties:
        Owner:
          $ref: '#/components/schemas/Owner'
        AccessControlList:
          type: object
          description: Container for grant entries.
          properties:
            Grant:
              type: array
              description: List of access control grants.
              items:
                $ref: '#/components/schemas/Grant'
    S3Error:
      type: object
      description: S3-compatible error response in XML format.
      properties:
        Code:
          type: string
          description: S3 error code such as NoSuchBucket, InvalidBucketName, or BucketNotEmpty.
        Message:
          type: string
          description: Human-readable error message.
        Resource:
          type: string
          description: The bucket or object that the error applies to.
        RequestId:
          type: string
          description: Unique identifier for the request, useful for debugging.
    Grant:
      type: object
      description: A permission grant in an ACL.
      properties:
        Grantee:
          $ref: '#/components/schemas/Grantee'
        Permission:
          type: string
          enum:
          - FULL_CONTROL
          - READ
          - WRITE
          - READ_ACP
          - WRITE_ACP
          description: Permission level granted.
    Owner:
      type: object
      description: Owner of a bucket or object.
      properties:
        ID:
          type: string
          description: CubeFS user ID of the owner.
        DisplayName:
          type: string
          description: Display name of the owner.
    Grantee:
      type: object
      description: An entity to whom access is being granted.
      properties:
        ID:
          type: string
          description: User ID or group identifier.
        DisplayName:
          type: string
          description: Display name of the grantee.
        Type:
          type: string
          description: Type of grantee, typically CanonicalUser or Group.
  parameters:
    bucket:
      name: bucket
      in: path
      required: true
      description: Name of the S3 bucket (corresponds to a CubeFS volume name).
      schema:
        type: string
        minLength: 3
        maxLength: 63
        pattern: ^[a-z0-9][a-z0-9\-]*[a-z0-9]$
  securitySchemes:
    awsAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'AWS Signature Version 4 authorization. Format: AWS4-HMAC-SHA256 Credential={accessKey}/{date}/{region}/s3/aws4_request, SignedHeaders={headers}, Signature={signature}. Access keys are managed via the CubeFS Master API user management endpoints.'
externalDocs:
  description: CubeFS ObjectNode Documentation
  url: https://cubefs.io/docs/master/user-guide/objectnode.html