Rook Ceph Object Storage API

openapi: 3.1.0
info:
  title: Rook Ceph Object Storage API
  description: >-
    Rook provisions Ceph Object Storage gateways (Ceph RADOS Gateway / RGW)
    that expose an S3-compatible REST API for object storage operations. The
    gateway is managed through Rook CephObjectStore and CephObjectStoreUser
    Kubernetes CRDs. Applications interact with the object storage using
    standard S3 API semantics including bucket operations, object CRUD,
    multipart uploads, access control lists, and presigned URLs. User
    credentials are provisioned via CephObjectStoreUser CRDs and accessed
    through Kubernetes Secrets.
  version: '1.0.0'
  contact:
    name: Rook Community
    url: https://rook.io/community/
  termsOfService: https://rook.io/
externalDocs:
  description: Rook Ceph Object Storage Documentation
  url: https://rook.io/docs/rook/latest/CRDs/Object-Storage/ceph-object-store-crd/
servers:
  - url: http://{rgw-host}:{port}
    description: Ceph RADOS Gateway endpoint as provisioned by Rook CephObjectStore
    variables:
      rgw-host:
        default: rook-ceph-rgw-my-store.rook-ceph.svc
        description: >-
          Kubernetes Service hostname for the RGW endpoint as created by
          the CephObjectStore CRD. Format is
          rook-ceph-rgw-{store-name}.{namespace}.svc
      port:
        default: '80'
        description: >-
          Port for the RGW service, typically 80 for HTTP or 443 for HTTPS
          as configured in the CephObjectStore gateway spec
tags:
  - name: Buckets
    description: >-
      S3-compatible bucket creation, listing, deletion, and configuration
      operations on Ceph Object Storage provisioned by Rook
  - name: Multipart Uploads
    description: >-
      S3-compatible multipart upload operations for large objects,
      including initiation, part upload, completion, and abort
  - name: Objects
    description: >-
      S3-compatible object upload, download, listing, deletion, and
      metadata operations within Ceph Object Storage buckets
security:
  - s3Auth: []
paths:
  /:
    get:
      operationId: listBuckets
      summary: List All Buckets
      description: >-
        Returns a list of all S3 buckets owned by the authenticated user in
        the Ceph Object Storage gateway. The response includes bucket names
        and creation dates. Credentials are provided via AWS Signature
        Version 4 or Version 2 authentication using access keys provisioned
        by CephObjectStoreUser CRDs.
      tags:
        - Buckets
      responses:
        '200':
          description: List of buckets owned by the authenticated user
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/ListAllMyBucketsResult'
        '401':
          description: Authentication credentials are missing or invalid
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /{bucket}:
    parameters:
      - $ref: '#/components/parameters/BucketParam'
    put:
      operationId: createBucket
      summary: Create a Bucket
      description: >-
        Creates a new S3 bucket in the Ceph Object Storage gateway with the
        specified name. The bucket is created in the object store backing
        pool configured in the CephObjectStore CRD. Optional location
        constraint and ACL headers can be specified in the request.
      tags:
        - Buckets
      responses:
        '200':
          description: Bucket created successfully
        '400':
          description: >-
            Bad request. The bucket name is invalid or a required parameter
            is missing.
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: >-
            Conflict. A bucket with the specified name already exists and
            is owned by a different account.
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    head:
      operationId: headBucket
      summary: Check Bucket Existence and Access
      description: >-
        Checks whether a bucket exists and whether the caller has
        permission to access it. Returns HTTP 200 if the bucket exists and
        is accessible, HTTP 403 if the bucket exists but access is denied,
        or HTTP 404 if the bucket does not exist.
      tags:
        - Buckets
      responses:
        '200':
          description: Bucket exists and is accessible
        '403':
          description: Bucket exists but access is denied
        '404':
          description: Bucket does not exist
    delete:
      operationId: deleteBucket
      summary: Delete a Bucket
      description: >-
        Deletes an empty S3 bucket from the Ceph Object Storage gateway.
        The bucket must be empty before it can be deleted. Returns HTTP 409
        if the bucket is not empty.
      tags:
        - Buckets
      responses:
        '204':
          description: Bucket deleted successfully
        '404':
          description: Bucket not found
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Bucket is not empty and cannot be deleted
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    get:
      operationId: listObjects
      summary: List Objects in a Bucket
      description: >-
        Returns a list of objects stored in the specified S3 bucket. Supports
        filtering by prefix, delimiter for hierarchical listings, and
        pagination through continuation tokens. Returns up to 1000 objects
        per request by default.
      tags:
        - Objects
      parameters:
        - name: list-type
          in: query
          description: >-
            Set to 2 to use the newer List Objects V2 API which uses
            continuation tokens instead of markers for pagination.
          schema:
            type: integer
            enum: [2]
        - name: prefix
          in: query
          description: >-
            Limits the response to keys beginning with the specified prefix.
            Used to organize objects into virtual directories.
          schema:
            type: string
        - name: delimiter
          in: query
          description: >-
            Character used to group keys. All keys that contain the
            delimiter between the prefix and the first occurrence of the
            delimiter are grouped into a single CommonPrefix entry.
          schema:
            type: string
        - name: max-keys
          in: query
          description: >-
            Maximum number of keys to return in a single response.
            Defaults to 1000, maximum is 1000.
          schema:
            type: integer
            minimum: 1
            maximum: 1000
            default: 1000
        - name: continuation-token
          in: query
          description: >-
            Token from a previous List Objects V2 response used to
            continue listing from where the previous call left off.
          schema:
            type: string
        - name: marker
          in: query
          description: >-
            Key after which listing should begin, used for pagination in
            List Objects V1 API.
          schema:
            type: string
      responses:
        '200':
          description: List of objects in the bucket
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/ListBucketResult'
        '404':
          description: Bucket not found
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /{bucket}/{key}:
    parameters:
      - $ref: '#/components/parameters/BucketParam'
      - $ref: '#/components/parameters/KeyParam'
    put:
      operationId: putObject
      summary: Upload an Object
      description: >-
        Uploads an object to the specified key in the S3 bucket. The object
        data is included in the request body. Optional request headers allow
        specifying content type, content encoding, server-side encryption,
        storage class, and custom metadata prefixed with x-amz-meta-.
      tags:
        - Objects
      requestBody:
        required: true
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
      responses:
        '200':
          description: Object uploaded successfully
        '400':
          description: Bad request due to invalid parameters or malformed request
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Bucket not found
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    get:
      operationId: getObject
      summary: Download an Object
      description: >-
        Downloads the data and metadata of an object from the specified key
        in the S3 bucket. Supports range requests for partial content
        retrieval and conditional requests using ETag or Last-Modified
        headers. Returns the object data in the response body.
      tags:
        - Objects
      parameters:
        - name: Range
          in: header
          description: >-
            HTTP range header for partial content requests, e.g.
            bytes=0-1023 to retrieve the first 1024 bytes.
          schema:
            type: string
        - name: If-Match
          in: header
          description: >-
            Returns the object only if the ETag matches the specified value,
            otherwise returns HTTP 412.
          schema:
            type: string
        - name: If-None-Match
          in: header
          description: >-
            Returns the object only if the ETag does not match the specified
            value, used for cache validation.
          schema:
            type: string
      responses:
        '200':
          description: Object data retrieved successfully
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '206':
          description: Partial content returned for range request
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '304':
          description: Not modified, returned for conditional requests
        '404':
          description: Object or bucket not found
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    head:
      operationId: headObject
      summary: Get Object Metadata
      description: >-
        Retrieves the metadata of an object without downloading the object
        data. Returns HTTP headers containing content type, content length,
        ETag, last modified date, and any custom metadata associated with
        the object.
      tags:
        - Objects
      responses:
        '200':
          description: Object metadata retrieved successfully
        '404':
          description: Object or bucket not found
    delete:
      operationId: deleteObject
      summary: Delete an Object
      description: >-
        Deletes the specified object from the S3 bucket. If versioning is
        enabled, this creates a delete marker rather than permanently
        removing the object. The operation is idempotent and returns
        HTTP 204 even if the object does not exist.
      tags:
        - Objects
      responses:
        '204':
          description: Object deleted successfully
        '404':
          description: Bucket not found
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /{bucket}?uploads:
    parameters:
      - $ref: '#/components/parameters/BucketParam'
    get:
      operationId: listMultipartUploads
      summary: List In-Progress Multipart Uploads
      description: >-
        Returns a list of in-progress multipart uploads for the specified
        bucket. Useful for identifying and cleaning up incomplete multipart
        uploads that may be consuming storage quota.
      tags:
        - Multipart Uploads
      parameters:
        - name: uploads
          in: query
          required: true
          schema:
            type: string
            enum: ['']
      responses:
        '200':
          description: List of in-progress multipart uploads
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/ListMultipartUploadsResult'
        '404':
          description: Bucket not found
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /{bucket}/{key}?uploads:
    parameters:
      - $ref: '#/components/parameters/BucketParam'
      - $ref: '#/components/parameters/KeyParam'
    post:
      operationId: createMultipartUpload
      summary: Initiate a Multipart Upload
      description: >-
        Initiates a multipart upload for a large object and returns an
        upload ID that must be used in subsequent part upload and complete
        requests. Parts can then be uploaded in parallel using the upload ID.
        The multipart upload is not visible in the bucket until it is
        completed with a CompleteMultipartUpload request.
      tags:
        - Multipart Uploads
      parameters:
        - name: uploads
          in: query
          required: true
          schema:
            type: string
            enum: ['']
      responses:
        '200':
          description: Multipart upload initiated with upload ID returned
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/InitiateMultipartUploadResult'
        '404':
          description: Bucket not found
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  securitySchemes:
    s3Auth:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        AWS Signature Version 4 (SigV4) or AWS Signature Version 2
        authentication using access key and secret key pairs provisioned
        by CephObjectStoreUser Kubernetes CRDs. Credentials are available
        in the Kubernetes Secret created by Rook for each CephObjectStoreUser.
  parameters:
    BucketParam:
      name: bucket
      in: path
      required: true
      description: >-
        Name of the S3 bucket in the Ceph Object Storage gateway. Must be
        globally unique within the object store and follow DNS naming
        conventions.
      schema:
        type: string
        minLength: 3
        maxLength: 63
        pattern: '^[a-z0-9][a-z0-9\-]*[a-z0-9]$'
    KeyParam:
      name: key
      in: path
      required: true
      description: >-
        Object key (path) within the bucket. Can include forward slashes
        to simulate a directory hierarchy, with a maximum length of 1024
        bytes.
      schema:
        type: string
        minLength: 1
        maxLength: 1024
  schemas:
    ListAllMyBucketsResult:
      type: object
      description: >-
        Response to a list buckets request containing all buckets owned by
        the authenticated user
      properties:
        Owner:
          type: object
          description: Identity of the bucket owner
          properties:
            ID:
              type: string
              description: Ceph user ID of the bucket owner
            DisplayName:
              type: string
              description: Display name of the bucket owner
        Buckets:
          type: object
          description: Container for the list of bucket entries
          properties:
            Bucket:
              type: array
              description: List of bucket entries
              items:
                $ref: '#/components/schemas/Bucket'
    Bucket:
      type: object
      description: An S3 bucket in the Ceph Object Storage gateway
      properties:
        Name:
          type: string
          description: Name of the bucket
        CreationDate:
          type: string
          format: date-time
          description: Date and time the bucket was created in ISO 8601 format
    ListBucketResult:
      type: object
      description: Response to a list objects request for a bucket
      properties:
        Name:
          type: string
          description: Name of the bucket containing the listed objects
        Prefix:
          type: string
          description: Prefix used to filter the listed objects
        Delimiter:
          type: string
          description: Delimiter used for hierarchical grouping of keys
        MaxKeys:
          type: integer
          description: Maximum number of keys returned in this response
        IsTruncated:
          type: boolean
          description: >-
            True if the response was truncated and more objects are
            available via pagination
        NextContinuationToken:
          type: string
          description: >-
            Token for retrieving the next page of results in List Objects V2
        Contents:
          type: array
          description: List of object entries matching the listing criteria
          items:
            $ref: '#/components/schemas/Object'
        CommonPrefixes:
          type: array
          description: >-
            Virtual directory prefixes grouped by the delimiter character
          items:
            type: object
            properties:
              Prefix:
                type: string
                description: Common prefix string for grouped keys
    Object:
      type: object
      description: An S3 object stored in a Ceph Object Storage bucket
      properties:
        Key:
          type: string
          description: Object key within the bucket
        LastModified:
          type: string
          format: date-time
          description: Date and time the object was last modified
        ETag:
          type: string
          description: >-
            MD5 hash of the object data enclosed in double quotes, used for
            data integrity verification
        Size:
          type: integer
          description: Size of the object in bytes
        StorageClass:
          type: string
          description: Storage class of the object
          enum:
            - STANDARD
            - REDUCED_REDUNDANCY
        Owner:
          type: object
          description: Owner of the object
          properties:
            ID:
              type: string
            DisplayName:
              type: string
    ListMultipartUploadsResult:
      type: object
      description: Response listing in-progress multipart uploads for a bucket
      properties:
        Bucket:
          type: string
          description: Name of the bucket
        Upload:
          type: array
          description: List of in-progress multipart upload entries
          items:
            type: object
            properties:
              Key:
                type: string
                description: Object key for the multipart upload
              UploadId:
                type: string
                description: Unique identifier for the multipart upload
              Initiated:
                type: string
                format: date-time
                description: Date and time the multipart upload was initiated
              Initiator:
                type: object
                properties:
                  ID:
                    type: string
                  DisplayName:
                    type: string
    InitiateMultipartUploadResult:
      type: object
      description: >-
        Response to a multipart upload initiation request containing the
        upload ID needed for subsequent part uploads
      properties:
        Bucket:
          type: string
          description: Name of the bucket where the object will be stored
        Key:
          type: string
          description: Object key for the multipart upload
        UploadId:
          type: string
          description: >-
            Unique identifier for this multipart upload, required in all
            subsequent part upload and complete/abort requests
    ErrorResponse:
      type: object
      description: S3-compatible error response returned when an operation fails
      properties:
        Code:
          type: string
          description: >-
            S3 error code string identifying the type of error, e.g.
            NoSuchBucket, AccessDenied, InvalidBucketName
        Message:
          type: string
          description: Human-readable description of the error
        Resource:
          type: string
          description: The bucket or object key that caused the error
        RequestId:
          type: string
          description: Unique identifier for the failed request for debugging