Apache BookKeeper Ledgers API

openapi: 3.2.0
info:
  title: Apache BookKeeper Admin Auto Recovery Ledgers API
  description: The Apache BookKeeper HTTP Admin API provides REST endpoints for managing and monitoring BookKeeper clusters, bookies, ledgers, and auto-recovery operations. It enables programmatic cluster administration, ledger inspection, bookie health monitoring, and garbage collection management.
  version: 4.16.0
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  contact:
    name: Apache BookKeeper Community
    url: https://bookkeeper.apache.org/
  x-generated-from: documentation
  x-last-validated: '2026-04-19'
servers:
- url: http://localhost:8080
  description: Default local BookKeeper bookie HTTP admin endpoint
tags:
- name: Ledgers
  description: Ledger management and inspection operations.
paths:
  /api/v1/ledger/list:
    get:
      operationId: listLedgers
      summary: Apache BookKeeper List Ledgers
      description: List all ledgers in the BookKeeper cluster with optional metadata.
      tags:
      - Ledgers
      parameters:
      - name: print_metadata
        in: query
        required: false
        description: If true, include ledger metadata in the response.
        schema:
          type: boolean
          example: false
      responses:
        '200':
          description: List of ledger IDs with optional metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LedgerList'
              examples:
                ListLedgers200Example:
                  summary: Default listLedgers 200 response
                  x-microcks-default: true
                  value:
                    '1': 'LedgerMetadata{ensembleSize: 3, writeQuorumSize: 2, ackQuorumSize: 2}'
                    '2': 'LedgerMetadata{ensembleSize: 3, writeQuorumSize: 2, ackQuorumSize: 2}'
        '403':
          description: Permission denied.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /api/v1/ledger/metadata:
    get:
      operationId: getLedgerMetadata
      summary: Apache BookKeeper Get Ledger Metadata
      description: Retrieve metadata for a specific ledger by its ID.
      tags:
      - Ledgers
      parameters:
      - name: ledger_id
        in: query
        required: true
        description: The ledger ID (Long) to retrieve metadata for.
        schema:
          type: integer
          format: int64
          example: 12345
      responses:
        '200':
          description: Ledger metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LedgerMetadata'
              examples:
                GetLedgerMetadata200Example:
                  summary: Default getLedgerMetadata 200 response
                  x-microcks-default: true
                  value:
                    ledgerId: 12345
                    ensembleSize: 3
                    writeQuorumSize: 2
                    ackQuorumSize: 2
                    state: CLOSED
                    length: 1048576
                    lastEntryId: 1024
        '403':
          description: Permission denied.
        '404':
          description: Ledger not found.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /api/v1/ledger/delete:
    delete:
      operationId: deleteLedger
      summary: Apache BookKeeper Delete Ledger
      description: Delete a ledger and all its data from the BookKeeper cluster.
      tags:
      - Ledgers
      parameters:
      - name: ledger_id
        in: query
        required: true
        description: The ledger ID to delete.
        schema:
          type: integer
          format: int64
          example: 12345
      responses:
        '200':
          description: Ledger deleted successfully.
          content:
            text/plain:
              schema:
                type: string
              examples:
                DeleteLedger200Example:
                  summary: Default deleteLedger 200 response
                  x-microcks-default: true
                  value: OK
        '403':
          description: Permission denied.
        '404':
          description: Ledger not found.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /api/v1/ledger/read:
    get:
      operationId: readLedgerEntries
      summary: Apache BookKeeper Read Ledger Entries
      description: Read entries from a ledger within a specified entry ID range.
      tags:
      - Ledgers
      parameters:
      - name: ledger_id
        in: query
        required: true
        description: The ledger ID to read entries from.
        schema:
          type: integer
          format: int64
          example: 12345
      - name: start_entry_id
        in: query
        required: false
        description: First entry ID to read (inclusive). Defaults to 0.
        schema:
          type: integer
          format: int64
          example: 0
      - name: end_entry_id
        in: query
        required: false
        description: Last entry ID to read (inclusive). Defaults to last entry.
        schema:
          type: integer
          format: int64
          example: 100
      responses:
        '200':
          description: Ledger entries as a map of entry ID to content.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LedgerEntries'
              examples:
                ReadLedgerEntries200Example:
                  summary: Default readLedgerEntries 200 response
                  x-microcks-default: true
                  value:
                    '0': aGVsbG8gd29ybGQ=
                    '1': ZW50cnkgY29udGVudA==
        '403':
          description: Permission denied.
        '404':
          description: Ledger not found.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    LedgerEntries:
      title: LedgerEntries
      description: Map of entry IDs to base64-encoded entry content.
      type: object
      additionalProperties:
        type: string
    LedgerList:
      title: LedgerList
      description: Map of ledger IDs to ledger metadata strings.
      type: object
      additionalProperties:
        type: string
    LedgerMetadata:
      title: LedgerMetadata
      description: Metadata for a single BookKeeper ledger.
      type: object
      properties:
        ledgerId:
          type: integer
          format: int64
          description: Unique identifier of the ledger.
          example: 12345
        ensembleSize:
          type: integer
          description: Number of bookies in the ensemble.
          example: 3
        writeQuorumSize:
          type: integer
          description: Number of bookies to write to per entry.
          example: 2
        ackQuorumSize:
          type: integer
          description: Number of acks required before an entry is considered written.
          example: 2
        state:
          type: string
          description: State of the ledger (OPEN or CLOSED).
          enum:
          - OPEN
          - CLOSED
          example: CLOSED
        length:
          type: integer
          format: int64
          description: Total byte length of the ledger.
          example: 1048576
        lastEntryId:
          type: integer
          format: int64
          description: ID of the last entry in the ledger.
          example: 1024