CubeFS S3-Compatible API — Objects

naftiko: 1.0.0-alpha2
info:
  label: CubeFS S3-Compatible API — Objects
  description: 'CubeFS S3-Compatible API — Objects. 5 operations. Lead operation: CubeFS List objects in a bucket. Self-contained
    Naftiko capability covering one Cubefs business surface.'
  tags:
  - Cubefs
  - Objects
  created: '2026-05-19'
  modified: '2026-05-19'
binds:
- namespace: env
  keys:
    CUBEFS_API_KEY: CUBEFS_API_KEY
capability:
  consumes:
  - type: http
    namespace: s3-objects
    baseUri: http://{objectNodeHost}:{objectNodePort}
    description: CubeFS S3-Compatible API — Objects business capability. Self-contained, no shared references.
    resources:
    - name: bucket
      path: /{bucket}
      operations:
      - name: listobjects
        method: GET
        description: CubeFS List objects in a bucket
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: prefix
          in: query
          type: string
          description: Only return objects whose keys begin with this prefix.
        - name: delimiter
          in: query
          type: string
          description: Character used to group keys. Keys with the same string between the prefix and the first occurrence
            of the delimiter are grouped under a common prefix.
        - name: max-keys
          in: query
          type: integer
          description: Maximum number of objects to return. Defaults to 1000.
        - name: continuation-token
          in: query
          type: string
          description: Continuation token for paginating through large result sets.
        - name: list-type
          in: query
          type: integer
          description: Set to 2 to use the List Objects V2 format with continuation tokens.
    - name: bucket-key
      path: /{bucket}/{key}
      operations:
      - name: putobject
        method: PUT
        description: CubeFS Upload an object
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: Content-Type
          in: header
          type: string
          description: MIME type of the object being uploaded.
        - name: Content-MD5
          in: header
          type: string
          description: Base64-encoded MD5 digest of the request body for integrity verification.
        - name: x-amz-acl
          in: header
          type: string
          description: Canned ACL to apply to the object.
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
      - name: getobject
        method: GET
        description: CubeFS Download an object
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: Range
          in: header
          type: string
          description: Byte range for partial content download, e.g. bytes=0-1023.
        - name: If-Match
          in: header
          type: string
          description: Only return the object if its ETag matches.
        - name: If-Modified-Since
          in: header
          type: string
          description: Only return the object if it was modified after this date.
      - name: headobject
        method: HEAD
        description: CubeFS Get object metadata
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: deleteobject
        method: DELETE
        description: CubeFS Delete an object
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    authentication:
      type: apikey
      key: Authorization
      value: '{{env.CUBEFS_API_KEY}}'
      placement: header
  exposes:
  - type: rest
    namespace: s3-objects-rest
    port: 8080
    description: REST adapter for CubeFS S3-Compatible API — Objects. One Spectral-compliant resource per consumed operation,
      prefixed with /v1.
    resources:
    - path: /v1/{bucket}
      name: bucket
      description: REST surface for bucket.
      operations:
      - method: GET
        name: listobjects
        description: CubeFS List objects in a bucket
        call: s3-objects.listobjects
        with:
          prefix: rest.prefix
          delimiter: rest.delimiter
          max-keys: rest.max-keys
          continuation-token: rest.continuation-token
          list-type: rest.list-type
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/{bucket}/{key}
      name: bucket-key
      description: REST surface for bucket-key.
      operations:
      - method: PUT
        name: putobject
        description: CubeFS Upload an object
        call: s3-objects.putobject
        with:
          Content-Type: rest.Content-Type
          Content-MD5: rest.Content-MD5
          x-amz-acl: rest.x-amz-acl
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
      - method: GET
        name: getobject
        description: CubeFS Download an object
        call: s3-objects.getobject
        with:
          Range: rest.Range
          If-Match: rest.If-Match
          If-Modified-Since: rest.If-Modified-Since
        outputParameters:
        - type: object
          mapping: $.
      - method: HEAD
        name: headobject
        description: CubeFS Get object metadata
        call: s3-objects.headobject
        outputParameters:
        - type: object
          mapping: $.
      - method: DELETE
        name: deleteobject
        description: CubeFS Delete an object
        call: s3-objects.deleteobject
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: s3-objects-mcp
    port: 9090
    transport: http
    description: MCP adapter for CubeFS S3-Compatible API — Objects. One tool per consumed operation, routed inline through
      this capability's consumes block.
    tools:
    - name: cubefs-list-objects-bucket
      description: CubeFS List objects in a bucket
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: s3-objects.listobjects
      with:
        prefix: tools.prefix
        delimiter: tools.delimiter
        max-keys: tools.max-keys
        continuation-token: tools.continuation-token
        list-type: tools.list-type
      outputParameters:
      - type: object
        mapping: $.
    - name: cubefs-upload-object
      description: CubeFS Upload an object
      hints:
        readOnly: false
        destructive: false
        idempotent: true
      call: s3-objects.putobject
      with:
        Content-Type: tools.Content-Type
        Content-MD5: tools.Content-MD5
        x-amz-acl: tools.x-amz-acl
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: cubefs-download-object
      description: CubeFS Download an object
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: s3-objects.getobject
      with:
        Range: tools.Range
        If-Match: tools.If-Match
        If-Modified-Since: tools.If-Modified-Since
      outputParameters:
      - type: object
        mapping: $.
    - name: cubefs-get-object-metadata
      description: CubeFS Get object metadata
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: s3-objects.headobject
      outputParameters:
      - type: object
        mapping: $.
    - name: cubefs-delete-object
      description: CubeFS Delete an object
      hints:
        readOnly: false
        destructive: true
        idempotent: true
      call: s3-objects.deleteobject
      outputParameters:
      - type: object
        mapping: $.