bulk-operations.yaml

openapi: 3.0.0
info:
  title: Bulk operations API
  version: v1
  description: Bulk operations API

paths:
  /bulk-operations/upload:
    post:
      description: Upload csv file with identifiers list (barcodes, UUIDs, HRIDs, etc.) or csv-file with already updated entities
      operationId: uploadCsvFile
      parameters:
        - name: entityType
          in: query
          required: true
          description: Entity type (USER, ITEM, HOLDINGS_RECORD)
          schema:
            $ref: "#/components/schemas/entityType"
        - name: identifierType
          in: query
          required: true
          description: Identifier type (ID, BARCODE, etc.)
          schema:
            $ref: "#/components/schemas/identifierType"
        - name: manual
          in: query
          required: false
          description: Key if manual approach is used
          schema:
            default: false
            type: boolean
        - name: operationId
          in: query
          required: false
          description: UUID of the Bulk Operation (applicable for (manual = true) case)
          schema:
            $ref: "#/components/schemas/UUID"
        - name: X-Okapi-User-Id
          in: header
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
      responses:
        "201":
          description: File uploaded
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/bulkOperationDto"
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/errors"
        "500":
          description: Internal server errors, e.g. due to misconfiguration
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/queryRequest"
  /bulk-operations/query:
    post:
      description: Trigger bulk edit by query
      operationId: triggerBulkEditByQuery
      parameters:
        - name: X-Okapi-User-Id
          in: header
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/queryRequest"
      responses:
        "201":
          description: Accepted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/bulkOperationDto"
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/errors"
        "422":
          description: Unprocessable entity
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/errors"
        "500":
          description: Internal server errors, e.g. due to misconfiguration
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/errors"
  /bulk-operations/{operationId}/content-update:
    post:
      description: Upload content updates
      operationId: postContentUpdates
      parameters:
        - name: operationId
          in: path
          required: true
          description: UUID of the Bulk Operation
          schema:
            $ref: "#/components/schemas/UUID"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/bulkOperationRuleCollection"
      responses:
        "200":
          description: Rules are saved
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/bulkOperationRuleCollection"
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/errors"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/errors"
        "500":
          description: Internal server errors, e.g. due to misconfiguration
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/errors"
  /bulk-operations/{operationId}/marc-content-update:
    post:
      description: Upload MARC content updates
      operationId: postMarcContentUpdates
      parameters:
        - name: operationId
          in: path
          required: true
          description: UUID of the Bulk Operation
          schema:
            $ref: "#/components/schemas/UUID"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/bulkOperationMarcRuleCollection"
      responses:
        "200":
          description: Rules are saved
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/bulkOperationMarcRuleCollection"
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/errors"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/errors"
        "500":
          description: Internal server errors, e.g. due to misconfiguration
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/errors"
  /bulk-operations/{operationId}/preview:
    get:
      description: Get preview
      operationId: getPreviewByOperationId
      parameters:
        - name: operationId
          in: path
          required: true
          description: UUID of the Bulk Operation
          schema:
            $ref: "#/components/schemas/UUID"
        - name: step
          in: query
          required: true
          description: Key if manual approach is used
          schema:
            $ref: "#/components/schemas/bulkOperationStep"
        - in: query
          name: limit
          required: true
          schema:
            type: integer
          description: The numbers of records to return
        - in: query
          name: offset
          required: false
          schema:
            default: 0
            type: integer
          description: Query offset
      responses:
        '200':
          description: Collection of records for preview
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/unifiedTable"
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/errors"
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/errors"
        '500':
          description: Internal server errors, e.g. due to misconfiguration
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/errors"
  /bulk-operations/{operationId}/start:
    post:
      description: Start Bulk Operation
      operationId: startBulkOperation
      parameters:
        - name: operationId
          in: path
          required: true
          description: UUID of the Bulk Operation
          schema:
            $ref: "#/components/schemas/UUID"
        - name: X-Okapi-User-Id
          in: header
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/bulkOperationStart"
      responses:
        "200":
          description: Bulk Operation is started
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/bulkOperationDto"
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/errors"
        "404":
          description: Bad Request
          content:
            text/plain:
              schema:
                type: string
                example: Bulk Operation not found
        "500":
          description: Internal server errors, e.g. due to misconfiguration
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/errors"
  /bulk-operations/{operationId}/errors:
    get:
      description: Get a list of errors for preview
      operationId: getErrorsPreviewByOperationId
      parameters:
        - name: operationId
          in: path
          required: true
          description: UUID of the Bulk Operation
          schema:
            $ref: "#/components/schemas/UUID"
        - in: query
          name: limit
          required: true
          schema:
            type: integer
          description: The numbers of errors to return
      responses:
        '200':
          description: Collection of errors for preview
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/errors"
        '404':
          description: No found
          content:
            text/plain:
              schema:
                type: string
                example: Bulk Operation not found
        '500':
          description: Internal server errors, e.g. due to misconfiguration
          content:
            text/plain:
              schema:
                type: string
                example: Internal server error
  /bulk-operations:
    get:
      description: Get a list of operations
      operationId: getBulkOperationCollection
      parameters:
        - in: query
          name: query
          required: true
          schema:
            type: string
          description: Request query
        - in: query
          name: offset
          required: false
          schema:
            type: integer
          description: Query offset
        - in: query
          name: limit
          required: false
          schema:
            type: integer
          description: Query limit
      responses:
        '200':
          description: Collection of operations for preview
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/bulkOperationCollection"
        '500':
          description: Internal server errors, e.g. due to misconfiguration
          content:
            text/plain:
              schema:
                type: string
                example: Internal server error
  /bulk-operations/{operationId}/download:
    get:
      description: Download file by operation id
      operationId: downloadFileByOperationId
      parameters:
        - name: operationId
          in: path
          required: true
          description: UUID of the Bulk Operation
          schema:
            $ref: "#/components/schemas/UUID"
        - in: query
          name: fileContentType
          required: true
          schema:
            $ref: "#/components/schemas/fileContentType"
          description: The file content type
      responses:
        '200':
          description: Preview of updated items to download
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/errors"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/errors"
        "500":
          description: Internal server errors, e.g. due to misconfiguration
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/errors"
  /bulk-operations/{operationId}:
    get:
      description: Get bulk operation by id
      operationId: getBulkOperationById
      parameters:
        - name: operationId
          in: path
          required: true
          description: UUID of the Bulk Operation
          schema:
            $ref: "#/components/schemas/UUID"
      responses:
        '200':
          description: Bulk operation DTO
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/bulkOperationDto"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/errors"
        '500':
          description: Internal server errors, e.g. due to misconfiguration
          content:
            text/plain:
              schema:
                type: string
                example: Internal server error
  /bulk-operations/clean-up-log-files:
    post:
      description: Removed all files older than 30 days
      operationId: cleanUpLogFiles
      responses:
        '201':
          description: No content
        '500':
          description: Internal server errors, e.g. due to misconfiguration
          content:
            text/plain:
              schema:
                type: string
                example: Internal server error
  /bulk-operations/list-users:
    get:
      description: Get a list of users
      operationId: getListUsers
      parameters:
        - in: query
          name: query
          required: true
          schema:
            type: string
          description: Request query
        - in: query
          name: offset
          required: false
          schema:
            type: integer
          description: Query offset
        - in: query
          name: limit
          required: false
          schema:
            type: integer
          description: Query limit
      responses:
        '200':
          description: Collection of users
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/users"
        '500':
          description: Internal server errors, e.g. due to misconfiguration
          content:
            text/plain:
              schema:
                type: string
                example: Internal server error
  /bulk-operations/{operationId}/files/{fileName}:
    delete:
      description: Delete file by name and bulk operation id
      operationId: deleteFileByNameAndOperationId
      parameters:
        - in: path
          name: operationId
          required: true
          schema:
            $ref: "#/components/schemas/UUID"
          description: UUID of the Bulk Operation
        - in: path
          name: fileName
          required: true
          schema:
            type: string
          description: File name
      responses:
        '204':
          description: File deleted successfully
        '500':
          description: Internal server errors, e.g. due to misconfiguration
          content:
            text/plain:
              schema:
                type: string
                example: Internal server error
  /bulk-operations/{operationId}/cancel:
    post:
      description: Cancel bulk operation by id
      operationId: cancelOperationById
      parameters:
        - in: path
          name: operationId
          required: true
          schema:
            $ref: "#/components/schemas/UUID"
          description: UUID of the Bulk Operation
      responses:
        '200':
          description: Operation cancelled
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/errors"
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/errors"
        '500':
          description: Internal server errors, e.g. due to misconfiguration
          content:
            text/plain:
              schema:
                type: string
                example: Internal server error
  /bulk-operations/used-tenants/{operationId}:
    get:
      description: Get a list of used tenants
      operationId: getListUsedTenants
      parameters:
        - in: path
          name: operationId
          required: true
          schema:
            $ref: "#/components/schemas/UUID"
          description: UUID of the Bulk Operation
      responses:
        '200':
          description: Collection of used tenants
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
        '500':
          description: Internal server errors, e.g. due to misconfiguration
          content:
            text/plain:
              schema:
                type: string
                example: Internal server error

components:
  schemas:
    bulkOperationCollection:
      $ref: 'schemas/bulk_operation_collection.json#/BulkOperationCollection'
    bulkOperationDto:
      $ref: 'schemas/bulk_operation_dto.json#/BulkOperationDto'
    bulkOperationRuleCollection:
      $ref: 'schemas/bulk_operation_rule_collection.json#/BulkOperationRuleCollection'
    unifiedTable:
      $ref: 'schemas/unified_table.json'
    entityType:
      $ref: 'schemas/entity_type.json#/EntityType'
    identifierType:
      $ref: 'schemas/identifier_type.json#/IdentifierType'
    fileContentType:
      $ref: 'schemas/file_content_type.json#/FileContentType'
    approachType:
      $ref: 'schemas/approach_type.json#/ApproachType'
    bulkOperationStep:
      $ref: 'schemas/bulk_operation_step.json#/BulkOperationStep'
    bulkOperationStart:
      $ref: 'schemas/bulk_operation_start.json#/Start'
    queryRequest:
      $ref: 'schemas/query-request.json#/QueryRequest'
    bulkOperationMarcRuleCollection:
      $ref: 'schemas/bulk_operation_marc_rule_collection.json#/BulkOperationMarcRuleCollection'
    dataImportJobExecutionCollection:
      $ref: 'schemas/data_import_job_execution_collection.json#/DataImportJobExecutionCollection'
    UUID:
      type: string
      format: uuid
    errors:
      $ref: 'schemas/errors.json'
    users:
      $ref: 'schemas/users.json'
    instanceNoteTypeCollection:
      $ref: "schemas/instance_note_type_collection.json"
    contributorTypeCollection:
      $ref: "schemas/contributor_types.json"
    searchResult:
      type: object
      properties:
        record:
          type: object
          description: Example response