openapi: 3.1.0 info: title: Rook Ceph Object Storage Buckets Objects 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/ 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 security: - s3Auth: [] tags: - name: Objects description: S3-compatible object upload, download, listing, deletion, and metadata operations within Ceph Object Storage buckets paths: /{bucket}: parameters: - $ref: '#/components/parameters/BucketParam' 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' components: schemas: 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 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 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 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 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. externalDocs: description: Rook Ceph Object Storage Documentation url: https://rook.io/docs/rook/latest/CRDs/Object-Storage/ceph-object-store-crd/