compaction-api.yaml

openapi: 3.0.3
info:
  title: Dataset Compaction API
  description: API for manual compaction of Smart Cache Graph datasets.
  version: 0.82.8
servers:
  - url: http://localhost:3030/
    description: Base path for compaction operations.
components:
  securitySchemes:
    BearerAuth:
      description: Generic Bearer Authentication is supported using JWTs
      type: http
      scheme: bearer
      bearerFormat: JWT
    AwsBearerAuth:
      description: |
        For AWS usage we support JWTs that are injected into requests by the ELB.
        Since these come in a non-standard HTTP header we have to declare this as
        an API Key scheme in OpenAPI spec as it doesn't have a notion of using a
        HTTP scheme in a non-standard way (yay AWS weirdness!)
      type: apiKey
      in: header
      name: X-Amzn-Oidc-Data
  schemas:
    CompactionSummaryResponse:
      type: object
      required:
        - status
        - datasets
      properties:
        status:
          type: string
          example: ok
        datasets:
          type: object
          description: Map of dataset path to compaction outcome.
          additionalProperties:
            type: string
            enum:
              - COMPACTED
              - SKIPPED_ALREADY_COMPACTED
              - SKIPPED_PREVIOUSLY_COMPACTED
              - SKIPPED_LOCK_CONTENTION
              - SKIPPED_NOT_TDB2
    AsyncCompactionSubmission:
      type: object
      required:
        - job-id
        - operation
        - status
        - status-path
        - message
      properties:
        job-id:
          type: string
        operation:
          type: string
          enum:
            - COMPACT_DATASET
            - COMPACT_ALL_DATASETS
        status:
          type: string
          enum:
            - PENDING
            - RUNNING
            - SUCCEEDED
            - FAILED
        status-path:
          type: string
        message:
          type: string
    CompactionJobStatus:
      type: object
      required:
        - job-id
        - operation
        - status
        - status-path
        - message
        - submitted-at
      properties:
        job-id:
          type: string
        operation:
          type: string
        status:
          type: string
          enum:
            - PENDING
            - RUNNING
            - SUCCEEDED
            - FAILED
        status-path:
          type: string
        message:
          type: string
        submitted-at:
          type: string
          format: date-time
        started-at:
          type: string
          format: date-time
        completed-at:
          type: string
          format: date-time
        http-status:
          type: integer
        result:
          oneOf:
            - $ref: '#/components/schemas/CompactionSummaryResponse'
            - type: object
              properties:
                error:
                  type: string
security:
  - BearerAuth: []
  - AwsBearerAuth: []
paths:
  /$/compact/{datasetName}:
    post:
      summary: Compact a single dataset
      description: |
        Attempts compaction for a single configured dataset.
        Returns a structured outcome payload when compaction succeeds or is skipped.
      parameters:
        - name: datasetName
          in: path
          required: true
          description: Dataset name (without leading slash), for example `knowledge`.
          schema:
            type: string
        - name: async
          in: query
          required: false
          description: When `true`, submit compaction as an asynchronous job and poll the returned `status-path`.
          schema:
            type: boolean
      responses:
        '200':
          description: Compaction request handled successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompactionSummaryResponse'
        '202':
          description: Compaction job accepted for asynchronous execution.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncCompactionSubmission'
        '401':
          description: Unauthorized due to missing role/permission.
        '500':
          description: Compaction failed while handling the request.
          content:
            text/plain:
              schema:
                type: string
                example: Compaction failed for dataset /knowledge: <reason>

  /$/compactall:
    post:
      summary: Compact all configured datasets
      description: |
        Attempts compaction for each configured dataset and returns per-dataset outcomes.
        If one or more dataset compactions fail with exceptions, the endpoint returns 500.
      parameters:
        - name: async
          in: query
          required: false
          description: When `true`, submit compaction as an asynchronous job and poll the returned `status-path`.
          schema:
            type: boolean
      responses:
        '200':
          description: Compaction request handled successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompactionSummaryResponse'
        '202':
          description: Compaction job accepted for asynchronous execution.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncCompactionSubmission'
        '401':
          description: Unauthorized due to missing role/permission.
        '500':
          description: One or more dataset compactions failed.
          content:
            text/plain:
              schema:
                type: string
                example: Compaction failed for one or more datasets: /knowledge=<reason>

  /$/compaction/jobs/{datasetName}:
    get:
      summary: List asynchronous jobs for a dataset compaction endpoint
      parameters:
        - name: datasetName
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Known asynchronous jobs for this dataset.
          content:
            application/json:
              schema:
                type: object
                properties:
                  jobs:
                    type: array
                    items:
                      $ref: '#/components/schemas/CompactionJobStatus'
        '401':
          description: Unauthorized due to missing role/permission.

  /$/compaction/jobs/{datasetName}/{jobId}:
    get:
      summary: Get asynchronous dataset compaction job status
      parameters:
        - name: datasetName
          in: path
          required: true
          schema:
            type: string
        - name: jobId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Current state of the asynchronous compaction job.
          content:
            application/json:
              schema:
                type: object
                properties:
                  job:
                    $ref: '#/components/schemas/CompactionJobStatus'
        '401':
          description: Unauthorized due to missing role/permission.
        '404':
          description: Unknown job id.

  /$/compaction/jobs/all:
    get:
      summary: List asynchronous jobs for compact-all requests
      responses:
        '200':
          description: Known asynchronous compact-all jobs.
          content:
            application/json:
              schema:
                type: object
                properties:
                  jobs:
                    type: array
                    items:
                      $ref: '#/components/schemas/CompactionJobStatus'
        '401':
          description: Unauthorized due to missing role/permission.

  /$/compaction/jobs/all/{jobId}:
    get:
      summary: Get asynchronous compact-all job status
      parameters:
        - name: jobId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Current state of the asynchronous compact-all job.
          content:
            application/json:
              schema:
                type: object
                properties:
                  job:
                    $ref: '#/components/schemas/CompactionJobStatus'
        '401':
          description: Unauthorized due to missing role/permission.
        '404':
          description: Unknown job id.