Merged in feature/docresult (pull request #105)

Document Result Endpoint * testing * cleantesting * progress * query * lint * readme * dockerclient * api * passtest * tests * test
2025-03-17 18:14:15 +00:00
parent f7c41c4ef3
commit 555b6d420b
105 changed files with 3276 additions and 2484 deletions
@@ -0,0 +1,931 @@
+---
+openapi: 3.0.3
+info:
+  title: Query Orchestration API
+  description: API documentation for the Query Orchestration services.
+  version: 0.0.1
+servers:
+  - url: https://doczy.com/v1
+    description: Production server
+tags:
+  - name: ClientService
+    description: Operations related to clients
+  - name: CollectorService
+    description: Operations related to collectors
+  - name: DocumentsService
+    description: Operations related to documents
+  - name: QueryAPI
+    description: Operations related to queries
+  - name: ExportService
+    description: Operations related to exports
+
+paths:
+  /client:
+    post:
+      operationId: createClient
+      tags:
+        - ClientService
+      summary: Create a new client
+      description: Creates a new client with the provided details.
+      security:
+        - placeholderAuth: []
+      requestBody:
+        description: The details required to create a client
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/ClientCreate"
+      responses:
+        "201":
+          description: Client created successfully.
+          headers:
+            RateLimit:
+              $ref: "#/components/headers/RateLimit"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ClientIDBody"
+        "400":
+          $ref: "#/components/responses/InvalidRequest"
+        "500":
+          $ref: "#/components/responses/InternalError"
+
+  /client/{id}:
+    parameters:
+      - $ref: "#/components/parameters/ClientID"
+    get:
+      operationId: getClient
+      tags:
+        - ClientService
+      summary: Get a client by ID
+      description: Retrieves a specific client by its ID.
+      security:
+        - placeholderAuth: []
+      responses:
+        "200":
+          description: Client details.
+          headers:
+            RateLimit:
+              $ref: "#/components/headers/RateLimit"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/DocClient"
+        "400":
+          $ref: "#/components/responses/InvalidRequest"
+        "500":
+          $ref: "#/components/responses/InternalError"
+    patch:
+      operationId: updateClient
+      tags:
+        - ClientService
+      summary: Update a client
+      description: Updates an existing client with new details.
+      security:
+        - placeholderAuth: []
+      requestBody:
+        description: The details to update
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/ClientUpdate"
+      responses:
+        "200":
+          description: Client updated successfully.
+          headers:
+            RateLimit:
+              $ref: "#/components/headers/RateLimit"
+        "400":
+          $ref: "#/components/responses/InvalidRequest"
+        "500":
+          $ref: "#/components/responses/InternalError"
+
+  /query:
+    get:
+      operationId: listQueries
+      tags:
+        - QueryAPI
+      summary: List queries
+      description: Retrieves a list of queries based on filter criteria.
+      security:
+        - placeholderAuth: []
+      responses:
+        "200":
+          description: A list of queries.
+          headers:
+            RateLimit:
+              $ref: "#/components/headers/RateLimit"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ListQueries"
+        "400":
+          $ref: "#/components/responses/InvalidRequest"
+        "500":
+          $ref: "#/components/responses/InternalError"
+    post:
+      operationId: createQuery
+      tags:
+        - QueryAPI
+      summary: Create a new query
+      description: Creates a new query with the provided details.
+      security:
+        - placeholderAuth: []
+      requestBody:
+        description: The details required to create a query
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/QueryCreate"
+      responses:
+        "201":
+          description: Query created successfully.
+          headers:
+            RateLimit:
+              $ref: "#/components/headers/RateLimit"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/IdMessage"
+        "400":
+          $ref: "#/components/responses/InvalidRequest"
+        "500":
+          $ref: "#/components/responses/InternalError"
+
+  /query/{id}:
+    parameters:
+      - $ref: "#/components/parameters/QueryID"
+    get:
+      operationId: getQuery
+      tags:
+        - QueryAPI
+      summary: Get a query by ID
+      description: Retrieves a specific query by its ID.
+      security:
+        - placeholderAuth: []
+      responses:
+        "200":
+          description: Query details.
+          headers:
+            RateLimit:
+              $ref: "#/components/headers/RateLimit"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Query"
+        "400":
+          $ref: "#/components/responses/InvalidRequest"
+        "500":
+          $ref: "#/components/responses/InternalError"
+    patch:
+      operationId: updateQuery
+      tags:
+        - QueryAPI
+      summary: Update a query
+      description: Updates an existing query with new details.
+      security:
+        - placeholderAuth: []
+      requestBody:
+        description: The update values for the desired query.
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/QueryUpdate"
+      responses:
+        "200":
+          description: Query updated successfully.
+          headers:
+            RateLimit:
+              $ref: "#/components/headers/RateLimit"
+        "400":
+          $ref: "#/components/responses/InvalidRequest"
+        "500":
+          $ref: "#/components/responses/InternalError"
+
+  /query/{id}/test:
+    parameters:
+      - $ref: "#/components/parameters/QueryID"
+    post:
+      operationId: testQuery
+      tags:
+        - QueryAPI
+      summary: Test a query
+      description: Executes a test run of a query with the provided parameters.
+      security:
+        - placeholderAuth: []
+      requestBody:
+        description: The query test requirements.
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/QueryTestRequest"
+      responses:
+        "200":
+          description: Test result.
+          headers:
+            RateLimit:
+              $ref: "#/components/headers/RateLimit"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/QueryTestResponse"
+        "400":
+          $ref: "#/components/responses/InvalidRequest"
+        "500":
+          $ref: "#/components/responses/InternalError"
+
+  /client/{id}/status:
+    parameters:
+      - $ref: "#/components/parameters/ClientID"
+    get:
+      operationId: getStatusByClientId
+      tags:
+        - ClientService
+      summary: Get client sync status
+      description: Retrieves the sync status by its client ID.
+      security:
+        - placeholderAuth: []
+      responses:
+        "200":
+          description: Client status details.
+          headers:
+            RateLimit:
+              $ref: "#/components/headers/RateLimit"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ClientStatusBody"
+        "400":
+          $ref: "#/components/responses/InvalidRequest"
+        "500":
+          $ref: "#/components/responses/InternalError"
+
+  /client/{id}/collector:
+    parameters:
+      - $ref: "#/components/parameters/ClientID"
+    get:
+      operationId: getCollectorByClientId
+      tags:
+        - CollectorService
+      summary: Get a collector by client ID
+      description: Retrieves a specific collector by its client ID.
+      security:
+        - placeholderAuth: []
+      responses:
+        "200":
+          description: Collector details.
+          headers:
+            RateLimit:
+              $ref: "#/components/headers/RateLimit"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Collector"
+        "400":
+          $ref: "#/components/responses/InvalidRequest"
+        "500":
+          $ref: "#/components/responses/InternalError"
+    patch:
+      operationId: setCollectorByClientId
+      tags:
+        - CollectorService
+      summary: Set a collector
+      description: Set client collector with new details.
+      security:
+        - placeholderAuth: []
+      requestBody:
+        description: The details to be set for the collector.
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CollectorSet"
+      responses:
+        "204":
+          description: Collector set successfully.
+          headers:
+            RateLimit:
+              $ref: "#/components/headers/RateLimit"
+        "400":
+          $ref: "#/components/responses/InvalidRequest"
+        "500":
+          $ref: "#/components/responses/InternalError"
+
+  /client/{id}/documents:
+    parameters:
+      - $ref: "#/components/parameters/ClientID"
+    get:
+      operationId: listDocumentsByClientId
+      tags:
+        - DocumentsService
+      summary: List the documents for a client
+      description: Retrieves the list of documents by the client ID.
+      security:
+        - placeholderAuth: []
+      responses:
+        "200":
+          description: Client documents list.
+          headers:
+            RateLimit:
+              $ref: "#/components/headers/RateLimit"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ListDocuments"
+        "400":
+          $ref: "#/components/responses/InvalidRequest"
+        "500":
+          $ref: "#/components/responses/InternalError"
+
+  /document/{id}:
+    parameters:
+      - $ref: "#/components/parameters/DocumentID"
+    get:
+      operationId: getDocument
+      tags:
+        - DocumentsService
+      summary: Get document details by its id
+      description: Retrieves the details of a document by its id.
+      security:
+        - placeholderAuth: []
+      responses:
+        "200":
+          description: Document details.
+          headers:
+            RateLimit:
+              $ref: "#/components/headers/RateLimit"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Document"
+        "400":
+          $ref: "#/components/responses/InvalidRequest"
+        "500":
+          $ref: "#/components/responses/InternalError"
+
+  /client/{id}/export:
+    parameters:
+      - $ref: "#/components/parameters/ClientID"
+    post:
+      operationId: triggerExport
+      tags:
+        - ExportService
+      summary: Trigger an export
+      description: Initiates the export process.
+      security:
+        - placeholderAuth: []
+      requestBody:
+        description: The export requirements.
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/ExportTrigger"
+      responses:
+        "201":
+          description: Export triggered successfully.
+          headers:
+            RateLimit:
+              $ref: "#/components/headers/RateLimit"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/IdMessage"
+        "400":
+          $ref: "#/components/responses/InvalidRequest"
+        "500":
+          $ref: "#/components/responses/InternalError"
+
+  /export/{id}:
+    parameters:
+      - $ref: "#/components/parameters/ExportID"
+    get:
+      operationId: exportState
+      tags:
+        - ExportService
+      summary: Check export state.
+      description: Checks the current state of an export.
+      security:
+        - placeholderAuth: []
+      responses:
+        "200":
+          description: Export has been completed.
+          headers:
+            RateLimit:
+              $ref: "#/components/headers/RateLimit"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ExportDetails"
+        "400":
+          $ref: "#/components/responses/InvalidRequest"
+        "500":
+          $ref: "#/components/responses/InternalError"
+
+components:
+  parameters:
+    ClientID:
+      in: path
+      name: id
+      required: true
+      schema:
+        $ref: "#/components/schemas/ClientID"
+      description: The client ID.
+
+    ExportID:
+      in: path
+      name: id
+      required: true
+      schema:
+        $ref: "#/components/schemas/ExportID"
+      description: The export ID.
+
+    QueryID:
+      in: path
+      name: id
+      required: true
+      schema:
+        $ref: "#/components/schemas/QueryID"
+      description: The ID of the query.
+
+    DocumentID:
+      in: path
+      name: id
+      required: true
+      schema:
+        $ref: "#/components/schemas/DocumentID"
+      description: The document ID.
+
+  headers:
+    RateLimit:
+      schema:
+        type: string
+        pattern: "^[0-9]+;window=[0-9]+$"
+        maxLength: 32
+      description: Rate limit information in format "limit;window=time-window"
+      example: "100;window=60"
+
+  securitySchemes:
+    placeholderAuth:
+      type: apiKey
+      in: header
+      name: X-API-Key
+      description: "Placeholder security scheme for future implementation"
+
+  responses:
+    InvalidRequest:
+      description: Invalid request body.
+      headers:
+        RateLimit:
+          $ref: "#/components/headers/RateLimit"
+
+    InternalError:
+      description: Internal server error.
+      headers:
+        RateLimit:
+          $ref: "#/components/headers/RateLimit"
+
+  schemas:
+    ClientID:
+      type: string
+      description: The client external id
+      example: AAA
+      maxLength: 36
+      pattern: "^.+$"
+
+    ClientUID:
+      type: string
+      format: uuid
+      description: The client internal unique id
+      example: 0195853c-8fdd-77cd-b36c-255241bddd33
+      maxLength: 36
+
+    QueryID:
+      type: string
+      format: uuid
+      description: The query id.
+      example: 019580df-ef65-7676-8de9-94435a93337a
+      maxLength: 36
+
+    DocumentID:
+      type: string
+      format: uuid
+      description: The document id.
+      example: 019580df-b3f8-7348-9ab1-1e55b3f18ed7
+      maxLength: 36
+
+    ExportID:
+      type: string
+      format: uuid
+      description: The export id.
+      example: 019580de-4d51-713c-98ee-464e83811f13
+      maxLength: 36
+
+    ClientName:
+      type: string
+      description: The client name
+      example: AArete
+      maxLength: 256
+      pattern: "^.+$"
+
+    ClientCanSync:
+      type: boolean
+      description: If the client is allowing active syncs
+
+    QueryType:
+      type: string
+      enum:
+        - JSON_EXTRACTOR
+        - CONTEXT_FULL
+      description: Specifies the type of the query.
+
+    QueryConfig:
+      type: string
+      description: Configuration for the query.
+      maxLength: 2048
+      pattern: '^\{.+\}$'
+
+    Query:
+      description: A logic unit of execution.
+      type: object
+      properties:
+        id:
+          $ref: "#/components/schemas/QueryID"
+        type:
+          $ref: "#/components/schemas/QueryType"
+        active_version:
+          $ref: "#/components/schemas/Version"
+        latest_version:
+          $ref: "#/components/schemas/Version"
+        config:
+          $ref: "#/components/schemas/QueryConfig"
+        required_queries:
+          $ref: "#/components/schemas/RequiredQueryIDs"
+      required:
+        - id
+        - type
+        - active_version
+        - latest_version
+
+    ListQueries:
+      description: A set of queries.
+      type: object
+      properties:
+        queries:
+          type: array
+          maxItems: 512
+          items:
+            $ref: "#/components/schemas/Query"
+          description: List of queries.
+      required:
+        - queries
+
+    QueryCreate:
+      description: The parameters required to create a query.
+      type: object
+      properties:
+        type:
+          $ref: "#/components/schemas/QueryType"
+        config:
+          $ref: "#/components/schemas/QueryConfig"
+        required_queries:
+          $ref: "#/components/schemas/RequiredQueryIDs"
+      required:
+        - type
+
+    RequiredQueryIDs:
+      type: array
+      maxItems: 256
+      items:
+        $ref: "#/components/schemas/QueryID"
+      description: List of required query IDs.
+
+    QueryUpdate:
+      description: The properties that may be updated for a query.
+      type: object
+      properties:
+        config:
+          $ref: "#/components/schemas/QueryConfig"
+        active_version:
+          $ref: "#/components/schemas/Version"
+        required_queries:
+          $ref: "#/components/schemas/RequiredQueryIDs"
+
+    QueryTestRequest:
+      description: The properties for a query test request.
+      type: object
+      properties:
+        document_id:
+          $ref: "#/components/schemas/DocumentID"
+        query_version:
+          $ref: "#/components/schemas/Version"
+      required:
+        - document_id
+        - query_version
+
+    QueryTestResponse:
+      description: The response from a query test.
+      type: object
+      properties:
+        value:
+          type: string
+          description: Result of the query test.
+          pattern: "^.+$"
+          maxLength: 2048
+      required:
+        - value
+
+    DocClient:
+      description: The properties of a client.
+      type: object
+      properties:
+        uid:
+          $ref: "#/components/schemas/ClientUID"
+        id:
+          $ref: "#/components/schemas/ClientID"
+        name:
+          $ref: "#/components/schemas/ClientName"
+        can_sync:
+          $ref: "#/components/schemas/ClientCanSync"
+      required:
+        - id
+        - uid
+        - name
+        - can_sync
+
+    ClientStatus:
+      type: string
+      enum:
+        - IN_SYNC
+        - NOT_SYNCED
+        - NOT_SYNCING
+      description: Specifies the status of a client.
+
+    ClientStatusBody:
+      description: A client status information object.
+      type: object
+      properties:
+        status:
+          $ref: "#/components/schemas/ClientStatus"
+      required:
+        - status
+
+    ClientIDBody:
+      description: The client id.
+      type: object
+      properties:
+        id:
+          $ref: "#/components/schemas/ClientID"
+      required:
+        - id
+
+    ListDocuments:
+      type: array
+      description: The documents in the client.
+      maxItems: 256
+      items:
+        $ref: "#/components/schemas/DocumentSummary"
+
+    Hash:
+      type: string
+      description: The document hash
+      maxLength: 2048
+      pattern: "^.+$"
+
+    DocumentSummary:
+      description: The document properties.
+      type: object
+      properties:
+        id:
+          $ref: "#/components/schemas/DocumentID"
+        hash:
+          $ref: "#/components/schemas/Hash"
+      required:
+        - id
+        - hash
+
+    Document:
+      description: The document properties.
+      type: object
+      properties:
+        id:
+          $ref: "#/components/schemas/DocumentID"
+        client_id:
+          $ref: "#/components/schemas/ClientID"
+        hash:
+          $ref: "#/components/schemas/Hash"
+        fields:
+          type: object
+          description: "The fields and the value for the document"
+          additionalProperties: true
+          example:
+            property1: "string value"
+            property2: 42
+            property3: true
+            property4:
+              nestedProperty: "nested value"
+            property5: [1, 2, 3]
+      required:
+        - id
+        - client_id
+        - hash
+        - fields
+
+    ClientCreate:
+      description: The properties for creation.
+      type: object
+      properties:
+        id:
+          $ref: "#/components/schemas/ClientID"
+        name:
+          $ref: "#/components/schemas/ClientName"
+      required:
+        - id
+        - name
+
+    ClientUpdate:
+      description: The properties that may be updated.
+      type: object
+      properties:
+        name:
+          $ref: "#/components/schemas/ClientName"
+        can_sync:
+          $ref: "#/components/schemas/ClientCanSync"
+
+    IdMessage:
+      description: A single uuid.
+      type: object
+      properties:
+        id:
+          type: string
+          format: uuid
+          description: Unique identifier for entity.
+          maxLength: 36
+      required:
+        - id
+
+    CodeVersion:
+      type: integer
+      format: int64
+      minimum: 1
+      maximum: 9223372036854775808
+      description: The desired code version.
+
+    Version:
+      type: integer
+      format: int32
+      minimum: 0
+      maximum: 2147483647
+      description: The desired version.
+
+    Collector:
+      type: object
+      properties:
+        client_id:
+          $ref: "#/components/schemas/ClientID"
+        active_version:
+          $ref: "#/components/schemas/Version"
+        latest_version:
+          $ref: "#/components/schemas/Version"
+        minimum_cleaner_version:
+          $ref: "#/components/schemas/CodeVersion"
+        minimum_text_version:
+          $ref: "#/components/schemas/CodeVersion"
+        fields:
+          $ref: "#/components/schemas/CollectorFields"
+      description: Collector model.
+      required:
+        - client_id
+        - fields
+        - minimum_cleaner_version
+        - minimum_text_version
+        - latest_version
+        - active_version
+
+    CollectorFields:
+      type: array
+      maxItems: 256
+      description: The fields in the collector.
+      items:
+        $ref: "#/components/schemas/CollectorField"
+
+    CollectorSet:
+      type: object
+      properties:
+        minimum_cleaner_version:
+          $ref: "#/components/schemas/CodeVersion"
+        minimum_text_version:
+          $ref: "#/components/schemas/CodeVersion"
+        active_version:
+          $ref: "#/components/schemas/Version"
+        fields:
+          $ref: "#/components/schemas/CollectorFields"
+      description: Payload for updating a Collector.
+
+    CollectorFieldName:
+      type: string
+      pattern: "^[a-zA-Z]+$"
+      maxLength: 256
+      description: The output field name.
+
+    CollectorField:
+      type: object
+      description: The field properties for the collector.
+      properties:
+        name:
+          $ref: "#/components/schemas/CollectorFieldName"
+        query_id:
+          $ref: "#/components/schemas/QueryID"
+      required:
+        - name
+        - query_id
+
+    ExportTrigger:
+      type: object
+      properties:
+        ingestion_filters:
+          type: object
+          description: Filter the scope based on ingestion parameters.
+          properties:
+            start_date:
+              type: string
+              format: date-time
+              maxLength: 32
+              description: This first date of ingestion.
+            end_date:
+              type: string
+              format: date-time
+              maxLength: 32
+              description: The last date of ingestion.
+        field_filters:
+          type: array
+          maxItems: 256
+          description: Filter the scope based on field output values.
+          items:
+            $ref: "#/components/schemas/FieldFilter"
+      description: Payload for triggering an export.
+
+    FieldFilter:
+      type: object
+      properties:
+        field_name:
+          $ref: "#/components/schemas/CollectorFieldName"
+        condition:
+          $ref: "#/components/schemas/FieldFilterCondition"
+        values:
+          type: array
+          description: The values useful to the filter.
+          maxItems: 100
+          items:
+            type: string
+            pattern: "^.+$"
+            maxLength: 256
+      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 states.
+
+    ExportDetails:
+      type: object
+      properties:
+        client_id:
+          $ref: "#/components/schemas/ClientID"
+        status:
+          $ref: "#/components/schemas/ExportStatus"
+        output_location:
+          type: string
+          description: The location in which the export zip file will be found.
+          example: s3://abc/AA/20250213/019587ac-073b-7098-8426-bad970f8c974.csv
+          maxLength: 2048
+          pattern: '^s3://.+/.+/[0-9]{8}/.+\.csv$'
+      description: Payload for export trigger response.
+      required:
+        - client_id
+        - status