---
openapi: 3.0.3
info:
  title: Query Orchestration API
  description: API documentation for the Query Orchestration services.
  version: 1.0.0
servers:
  - url: https://api.example.com/v1
    description: Production server
tags:
  - name: QueryService
    description: Operations related to queries
  - name: JobCollectorService
    description: Operations related to job collectors
  - name: ExportService
    description: Operations related to exports

paths:
  /queries:
    get:
      operationId: listQueries
      tags:
        - QueryService
      summary: List queries
      description: Retrieves a list of queries based on filter criteria.
      responses:
        '200':
          description: A list of queries.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListQueries'
        '400':
          description: Invalid request parameters.
        '404':
          description: Query not found.
    post:
      operationId: createQuery
      tags:
        - QueryService
      summary: Create a new query
      description: Creates a new query with the provided details.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QueryCreate'
      responses:
        '201':
          description: Query created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdMessage'
        '400':
          description: Invalid request body.

  /queries/{id}:
    get:
      operationId: getQueryById
      tags:
        - QueryService
      summary: Get a query by ID
      description: Retrieves a specific query by its ID.
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: The ID of the query to retrieve.
      responses:
        '200':
          description: Query details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Query'
        '400':
          description: Invalid request parameters.
        '404':
          description: Query not found.
    patch:
      operationId: updateQuery
      tags:
        - QueryService
      summary: Update a query
      description: Updates an existing query with new details.
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: The ID of the query to update.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QueryUpdate'
      responses:
        '200':
          description: Query updated successfully.
        '400':
          description: Invalid request body.
    delete:
      operationId: deprecateQuery
      tags:
        - QueryService
      summary: Deprecate a query
      description: Deprecates a specific query by its ID.
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: The ID of the query to deprecate.
      responses:
        '200':
          description: Query deprecated successfully.
        '400':
          description: Invalid request body.
        '404':
          description: Query not found.

  /queries/{id}/test:
    post:
      operationId: testQuery
      tags:
        - QueryService
      summary: Test a query
      description: Executes a test run of a query with the provided parameters.
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: The ID of the query to test.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QueryTestRequest'
      responses:
        '200':
          description: Test result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryTestResponse'
        '400':
          description: Invalid request body.

  /job-collectors:
    post:
      operationId: createJobCollector
      tags:
        - JobCollectorService
      summary: Create a job collector
      description: Creates a new job collector.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JobCollectorCreate'
      responses:
        '201':
          description: Job collector created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdMessage'
        '400':
          description: Invalid request body.

  /job-collectors/{id}:
    get:
      operationId: getJobCollectorById
      tags:
        - JobCollectorService
      summary: Get a job collector by ID
      description: Retrieves a specific job collector by its ID.
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: The ID of the job collector to retrieve.
      responses:
        '200':
          description: Job collector details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobCollector'
        '404':
          description: Job collector not found.
    put:
      operationId: updateJobCollector
      tags:
        - JobCollectorService
      summary: Update a job collector
      description: Updates an existing job collector with new details.
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: The ID of the job collector to update.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JobCollectorUpdate'
      responses:
        '204':
          description: Job collector updated successfully.
        '400':
          description: Invalid request body.
        '404':
          description: Job collector not found.

  /export:
    post:
      operationId: triggerExport
      tags:
        - ExportService
      summary: Trigger an export
      description: Initiates the export process.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExportTrigger'
      responses:
        '201':
          description: Export triggered successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdMessage'
        '400':
          description: Invalid request body.
        '404':
          description: Job not found.

  /export/{id}:
    get:
      operationId: exportState
      tags:
        - ExportService
      summary: Check export state.
      description: Checks the current state of an export.
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: The ID of the export.
      responses:
        '200':
          description: Export has been completed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExportDetails'
        '404':
          description: Export job not found.


components:
  schemas:
    QueryType:
      type: string
      enum:
        - JSON_EXTRACTOR
        - CONTEXT_FULL
      description: Specifies the type of the query.

    Query:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the query.
        type:
          $ref: '#/components/schemas/QueryType'
          description: Type of the query.
        active_version:
          type: integer
          format: int32
          description: The active version of the query.
        latest_version:
          type: integer
          format: int32
          description: The latest version of the query.
        config:
          type: string
          description: Configuration for the query.
        required_queries:
          type: array
          items:
            type: string
          description: List of required query IDs.
      required:
        - id
        - type
        - active_version
        - latest_version
        - required_queries

    ListQueries:
      type: object
      properties:
        queries:
          type: array
          items:
            $ref: '#/components/schemas/Query'
          description: List of queries.
      required:
        - queries

    QueryCreate:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/QueryType'
          description: Type of the query to create.
        config:
          type: string
          description: Configuration for the new query.
        required_queries:
          type: array
          items:
            type: string
          description: List of required query IDs.
      required:
        - type

    QueryUpdate:
      type: object
      properties:
        config:
          type: string
          description: Updated configuration for the query.
        active_version:
          type: integer
          format: int32
          description: Updated active version.
        required_queries:
          type: array
          items:
            type: string
          description: Updated list of required query IDs.

    QueryTestRequest:
      type: object
      properties:
        document_id:
          type: string
          description: ID of the document to test against.
        query_version:
          type: integer
          format: int32
          description: Version of the query to use for testing.
      required:
        - document_id
        - query_version

    QueryTestResponse:
      type: object
      properties:
        value:
          type: string
          description: Result of the query test.
      required:
        - value

    IdMessage:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for entity.
      required:
        - id

    JobCollector:
      type: object
      properties:
        example_property:
          type: string
          description: Example property for JobCollector.
      description: JobCollector model.

    JobCollectorCreate:
      type: object
      properties:
        example_property:
          type: string
          description: Example property for JobCollectorCreate.
      description: Payload for creating a JobCollector.

    JobCollectorUpdate:
      type: object
      properties:
        example_property:
          type: string
          description: Example property for JobCollectorUpdate.
      description: Payload for updating a JobCollector.

    ExportTrigger:
      type: object
      properties:
        job_id:
          type: string
          description: The job id of the query results to be exported.
        ingestion_filters:
          type: object
          description: Filter the scope based on ingestion parameters.
          properties:
            start_date:
              type: string
              description: This first date of ingestion.
            end_date:
              type: string
              description: The last date of ingestion.
        field_filters:
          type: array
          description: Filter the scope based on field output values.
          items:
            $ref: '#/components/schemas/FieldFilter'
      description: Payload for triggering an export.
      required:
        - job_id

    FieldFilter:
      type: object
      properties:
        field_name:
          type: string
          description: The name of the field in question.
        condition:
          $ref: "#/components/schemas/FieldFilterCondition"
        values:
          type: array
          description: The values useful to the filter.
          items:
            type: string
      description: Filtering a column
      required:
        - field_name
        - condition
        - values

    FieldFilterCondition:
      type: string
      enum:
        - less_than
        - greater_than
        - closed_interval
        - open_interval
        - left_closed_interval
        - right_closed_interval
        - include
        - exclude
      description: The possible field filtering conditions.

    ExportStatus:
      type: string
      enum:
        - completed
        - in_progress
        - failed
      description: The possible export job states.

    ExportDetails:
      type: object
      properties:
        job_id:
          type: string
          description: The job id relative to the export.
        status:
          $ref: '#/components/schemas/ExportStatus'
        output_location:
          type: string
          description: The location in which the export zip file will be found.
          example: s3://{bucket}/{clientid}/{jobid}/{timestamp}_{exportid}.zip
      description: Payload for export trigger response.
      required:
        - id
        - status