openapi: 3.0.0
info:
  title: Object Storage API
  description: API for managing objects in an object storage service.
  version: 1.0.0
  contact:
    name: API Support
    email: support@example.com

servers:
  - url: https://api.example.com/v1

paths:
  /buckets:
    get:
      summary: List all buckets
      description: Retrieve a paginated list of all buckets in the object storage.
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 100
          description: The maximum number of items to return
        - name: offset
          in: query
          schema:
            type: integer
            default: 0
          description: The number of items to skip before starting to collect the result set
      responses:
        '200':
          description: A paginated list of buckets.
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: integer
                    description: Total number of buckets available
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Bucket'

    post:
      summary: Create a new bucket
      description: Create a new bucket to store objects.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Name of the bucket to be created
                  example: my-new-bucket
      responses:
        '201':
          description: Bucket created successfully
        '400':
          description: Bad request
        '409':
          description: Bucket already exists

  /buckets/{bucketName}:
    delete:
      summary: Delete a bucket
      description: Delete a bucket and all its objects.
      parameters:
        - name: bucketName
          in: path
          required: true
          schema:
            type: string
          description: The name of the bucket to delete
      responses:
        '204':
          description: Bucket deleted successfully
        '404':
          description: Bucket not found

  /buckets/{bucketName}/objects:
    get:
      summary: List objects in a bucket
      description: Retrieve a paginated list of objects within a specified bucket.
      parameters:
        - name: bucketName
          in: path
          required: true
          schema:
            type: string
          description: The name of the bucket
        - name: limit
          in: query
          schema:
            type: integer
            default: 10
          description: The maximum number of items to return
        - name: offset
          in: query
          schema:
            type: integer
            default: 0
          description: The number of items to skip before starting to collect the result set
      responses:
        '200':
          description: A paginated list of objects in the bucket.
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: integer
                    description: Total number of objects available in the bucket
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Object'
        '404':
          description: Bucket not found

  /buckets/{bucketName}/objects/{objectKey}:
    get:
      summary: Get object
      description: Retrieve an object from the specified bucket.
      parameters:
        - name: bucketName
          in: path
          required: true
          schema:
            type: string
          description: The name of the bucket
        - name: objectKey
          in: path
          required: true
          schema:
            type: string
          description: The key (identifier) of the object
      responses:
        '200':
          description: The requested object data
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '404':
          description: Bucket or object not found

    put:
      summary: Upload an object
      description: Upload a new object or overwrite an existing one in the specified bucket.
      parameters:
        - name: bucketName
          in: path
          required: true
          schema:
            type: string
          description: The name of the bucket
        - name: objectKey
          in: path
          required: true
          schema:
            type: string
          description: The key (identifier) for the object
      requestBody:
        required: true
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
      responses:
        '201':
          description: Object uploaded successfully
        '400':
          description: Invalid object data

    delete:
      summary: Delete an object
      description: Delete an object from the specified bucket.
      parameters:
        - name: bucketName
          in: path
          required: true
          schema:
            type: string
          description: The name of the bucket
        - name: objectKey
          in: path
          required: true
          schema:
            type: string
          description: The key (identifier) of the object
      responses:
        '204':
          description: Object deleted successfully
        '404':
          description: Bucket or object not found

components:
  schemas:
    Bucket:
      type: object
      properties:
        name:
          type: string
          description: The name of the bucket
        created_at:
          type: string
          format: date-time
          description: Creation timestamp of the bucket
    Object:
      type: object
      properties:
        key:
          type: string
          description: The key (identifier) of the object
        size:
          type: integer
          description: The size of the object in bytes
        last_modified:
          type: string
          format: date-time
          description: The last modified timestamp of the object