queryTool.yaml

openapi: 3.0.0
info:
  title: Folio Query Tool API
  version: v1
  description: Folio Query Tool API

paths:
  /entity-types/{entityTypeId}:
    get:
      operationId: getEntityType
      description: Get definition of an Entity Type.
      tags:
        - entity-types
      parameters:
        - $ref: '#/components/parameters/entityTypeId'
        - $ref: '#/components/parameters/include-hidden'
      responses:
        '200':
          description: 'Definition of the requested entity type'
          content:
            application/json:
              example:
                id: 0cb79a4c-f7eb-4941-a104-745224ae0292
                name: item_details
                private: false
                root: true
                columns: []
              schema:
                $ref: '#/components/schemas/entityType'
        '400':
          $ref: '#/components/responses/badRequestResponse'
        '500':
          $ref: '#/components/responses/internalServerErrorResponse'

  /entity-types/{entityTypeId}/columns/{columnName}/values:
    get:
      operationId: getColumnValues
      description: Get the values of an entity type column.
      tags:
        - entity-types
      parameters:
        - $ref: '#/components/parameters/entityTypeId'
        - $ref: '#/components/parameters/columnName'
        - $ref: '#/components/parameters/search'
      responses:
        '200':
          description: 'Values of an entity type column'
          content:
            application/json:
              example:
                content:
                  - value: item_status
                    name: Item Status
              schema:
                $ref: '#/components/schemas/columnValues'
        '400':
          $ref: '#/components/responses/badRequestResponse'
        '500':
          $ref: '#/components/responses/internalServerErrorResponse'

  /query:
    get:
      operationId: runFqlQuery
      description: Runs an FQL query
      tags:
        - fqlQuery
      parameters:
        - $ref: '#/components/parameters/fqlQuery'
        - $ref: '#/components/parameters/entityTypeIdQueryParam'
        - $ref: '#/components/parameters/fields'
        - $ref: '#/components/parameters/afterId'
        - $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: Query result
          content:
            application/json:
              example:
                content:
                  - id:
                      type: object
                    item_status:
                      type: object
                totalRecords: 1
              schema:
                $ref: '#/components/schemas/resultsetPage'
        '400':
          $ref: '#/components/responses/badRequestResponse'
        '500':
          $ref: '#/components/responses/internalServerErrorResponse'
    post:
      operationId: runFqlQueryAsync
      description: Runs an FQL query asynchronously
      tags:
        - fqlQuery
      requestBody:
        description: Query request
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/submitQuery'
      responses:
        '200':
          description: 'The identifier for the query run'
          content:
            application/json:
              example:
                queryId: 37140576-be84-1a0e-7546-0912d8320019
              schema:
                $ref: '#/components/schemas/queryIdentifier'
        '400':
          $ref: '#/components/responses/badRequestResponse'
        '500':
          $ref: '#/components/responses/internalServerErrorResponse'

  /query/{queryId}:
    get:
      operationId: getQuery
      description: Get details of a submitted query, optionally including the results
      tags:
        - fqlQuery
      parameters:
        - $ref: '#/components/parameters/queryId'
        - $ref: '#/components/parameters/includeResults'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: 'Details of the submitted query'
          content:
            application/json:
              example:
                entityTypeId: 0cb79a4c-f7eb-4941-a104-745224ae0292
                fqlQuery: user_active == true
                queryId: 37140576-be84-1a0e-7546-0912d8320019
                startDate: 2023-04-04T21:56:08.673+00:00
                status: IN_PROGRESS
              schema:
                $ref: '#/components/schemas/queryDetails'
        '400':
          $ref: '#/components/responses/badRequestResponse'
        '500':
          $ref: '#/components/responses/internalServerErrorResponse'
    delete:
      operationId: deleteQuery
      description: Delete a query and its results
      tags:
        - fqlQuery
      parameters:
        - $ref: '#/components/parameters/queryId'
      responses:
        '204':
          description: Query has been deleted
        '404':
          description: Query with id not found
  /query/{queryId}/sortedIds:
    get:
      operationId: getSortedIds
      description: Get ids of query results in sorted order
      deprecated: true
      summary: This endpoint is deprecated and will be removed in a future release
      tags:
        - fqlQuery
      parameters:
        - $ref: '#/components/parameters/queryId'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: 'Details of the submitted query'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/queryResultIds'
        '400':
          $ref: '#/components/responses/badRequestResponse'
        '500':
          $ref: '#/components/responses/internalServerErrorResponse'
  /query/contents:
    post:
      tags:
        - fqlQuery
      operationId: getContents
      description: get contents for list of ids
      requestBody:
        description: Contents request
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/contentsRequest'
      responses:
        '200':
          description: A page of list contents
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contents'
        '400':
          $ref: '#/components/responses/badRequestResponse'
        '500':
          $ref: '#/components/responses/internalServerErrorResponse'
  /query/contents/privileged:
    post:
      tags:
        - fqlQuery
      operationId: getContentsPrivileged
      description: get contents for list of ids using a specified user proxy
      requestBody:
        description: Contents request
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/contentsRequest'
      responses:
        '200':
          description: A page of list contents
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contents'
        '400':
          $ref: '#/components/responses/badRequestResponse'
        '500':
          $ref: '#/components/responses/internalServerErrorResponse'
components:
  parameters:
    entityTypeId:
      name: entityTypeId
      in: path
      required: true
      description: UUID of the entity type
      schema:
        $ref: '#/components/schemas/UUID'
    entityTypeIdQueryParam:
      name: entityTypeId
      in: query
      required: true
      description: UUID of the entity type
      schema:
        $ref: '#/components/schemas/UUID'
    columnName:
      name: columnName
      in: path
      required: true
      description: Name of an entity type column
      schema:
        type: string
    search:
      name: search
      in: query
      required: false
      description: A search text that can be used to filter column values. If provided, only the values that begins with the given text will be returned in API response.
      schema:
        type: string
    queryId:
      name: queryId
      in: path
      required: true
      description: UUID of the query
      schema:
        $ref: '#/components/schemas/UUID'
    includeResults:
      name: includeResults
      in: query
      required: false
      description: Indicates if query results should be included in the query details response
      schema:
        type: boolean
    fqlQuery:
      name: query
      in: query
      schema:
        type: string
      required: true
      description: A complete query expressed as a FQL string. It should contain the from part that defines the entity type and the where/criteria part.
    fields:
      name: fields
      in: query
      schema:
        type: array
        items:
          type: string
      required: false
      description: fields to include in the query results
    offset:
      name: offset
      in: query
      schema:
        type: integer
        default: 0
        minimum: 0
        maximum: 2147483647
      required: false
      description: Skip over a number of elements by specifying an offset value for the query
    limit:
      name: limit
      in: query
      schema:
        type: integer
        default: 100
        minimum: 1
        maximum: 2147483647
      required: false
      description: Limit the number of elements returned in the response
    afterId:
      name: afterId
      in: query
      schema:
        type: array
        items:
          type: string
      required: false
      description: ID of the last element from the previous query
    include-hidden:
      name: includeHidden
      in: query
      required: false
      description: Include the hidden column in the display
      schema:
        type: boolean
        default: false

  schemas:
    UUID:
      $ref: schemas/common.json#/UUID
    entityType:
      $ref: schemas/entityType.json#/EntityType
    entityDataType:
      $ref: schemas/entityDataType.json#/EntityDataType
    stringType:
      $ref: schemas/entityDataType.json#/StringType
    rangedUUIDType:
      $ref: schemas/entityDataType.json#/RangedUUIDType
    openUUIDType:
      $ref: schemas/entityDataType.json#/OpenUUIDType
    stringUUIDType:
      $ref: schemas/entityDataType.json#/StringUUIDType
    numberType:
      $ref: schemas/entityDataType.json#/NumberType
    integerType:
      $ref: schemas/entityDataType.json#/IntegerType
    booleanType:
      $ref: schemas/entityDataType.json#/BooleanType
    dateType:
      $ref: schemas/entityDataType.json#/DateType
    enumType:
      $ref: schemas/entityDataType.json#/EnumType
    objectType:
      $ref: schemas/entityDataType.json#/ObjectType
    objectTypeContainer:
      $ref: schemas/entityDataType.json#/ObjectTypeContainer
    nestedObjectProperty:
      $ref: schemas/entityDataType.json#/NestedObjectProperty
    arrayType:
      $ref: schemas/entityDataType.json#/ArrayType
    jsonbArrayType:
      $ref: schemas/entityDataType.json#/JsonbArrayType
    entityTypeDefaultSort:
      $ref: schemas/entityTypeDefaultSort.json
    errors:
      $ref: schemas/error/errors.json
    error:
      $ref: schemas/error/error.json
    parameters:
      $ref: schemas/error/parameters.json
    parameter:
      $ref: schemas/error/parameter.json
    resultsetPage:
      $ref: schemas/resultset.json#/ResultsetPage
    queryDetails:
      $ref: schemas/query.json#/QueryDetails
    queryIdentifier:
      $ref: schemas/query.json#/QueryIdentifier
    columnValues:
      $ref: schemas/columnValues.json
    submitQuery:
      $ref: schemas/query.json#/SubmitQuery
    contentsRequest:
      $ref: schemas/query.json#/ContentsRequest

    fqmMigrateRequest:
      $ref: schemas/fqmMigrateRequest.json
    fqmMigrateResponse:
      $ref: schemas/fqmMigrateResponse.json

    queryResultIds:
      type: array
      items:
        type: array
        items:
          type: string
    fields:
      type: array
      items:
        type: string
    contents:
      type: array
      items:
        type: object
        additionalProperties:
          type: object

  responses:
    badRequestResponse:
      description: Bad request errors
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errors'
    internalServerErrorResponse:
      description: When unhandled exception occurred during code execution, e.g. NullPointerException
      content:
        application/json:
          example:
            errors:
              - message: Unexpected error
                code: unexpected.error
            total_records: 1
          schema:
            $ref: '#/components/schemas/errors'