# Next-gen Indexer REST APIs — smart search, config, saved filters, recent searches, data/criteria ingest.
# Paths under Pulse DispatcherServlet /MYWORK/service/indexer/v1/...
openapi: 3.0.3
info:
  title: TM Next-Gen — Indexer
  description: |
    OpenAPI for Indexer (Universal Smart Search) APIs under `indexer/v1/...`.

    Same server base URL as MyWork and task execution: `/MYWORK/service/`.

    **Authentication:** All endpoints require the `X-reflexis-csrf-token-X` header.
    Session-derived parameters (`domainId`, `userId`, `unitId`, `profileId`, `deptId`, `langCode`, …)
    are resolved from the validated session and must not be sent by clients.

    Companion spec: `mywork/next-gen-mywork-api.yaml` (app config, tags).
    Detailed contracts: `devdocs/api/nextgen/indexer/`.
  version: 1.0.0
  contact:
    name: API Support
    email: noreply@zebra.com

servers:
  - url: /MYWORK/service/
    description: Application context + Pulse servlet (typical deployment)
  - url: https://fs3.reflexisinc.com/MYWORK/service/
    description: Example development host
  - url: http://localhost:3001/MYWORK/service/
    description: Local CORS proxy — npm run cors-proxy; path must include /MYWORK/service/

tags:
  - name: IndexerConfig
    description: Global Smart Search configuration and dynamic filter options
  - name: IndexerSearch
    description: Unified smart-search data retrieval (preview and paginated)
  - name: IndexerSearchFilters
    description: Saved search filters (list, save, delete)
  - name: IndexerRecentSearches
    description: Recent smart-search history (explicit write on redirect)
  - name: IndexerData
    description: Search data record ingest (add, update, delete) — forwards to ztm-indexer
  - name: IndexerCriteria
    description: Search criteria record ingest (add, update, delete) — forwards to ztm-indexer

security:
  - AuthTokenHeader: []

components:
  securitySchemes:
    AuthTokenHeader:
      type: apiKey
      in: header
      name: X-reflexis-csrf-token-X
      description: Session authentication token validated server-side against the user session store.

  schemas:
    JsonObject:
      type: object
      additionalProperties: true
      description: JSON object (structure varies by endpoint). Field names are snake_case in responses.
    ErrorResponse:
      type: object
      properties:
        status:
          type: string
          enum: [ER]
        api_error_code:
          type: string
          description: Application-level error code (e.g. E504, E515, E539)
        response:
          type: string
          description: Human-readable error message
      required: [status, api_error_code, response]
      example:
        status: ER
        api_error_code: E504
        response: page_type is mandatory
    CriteriaRecordsRequest:
      type: object
      required: [application_id, source_id, criteria_records]
      properties:
        application_id:
          type: string
          description: Application identifier (e.g. `100`)
        source_id:
          type: string
          description: Source identifier (e.g. `MYWORK`, `DOCS`)
        criteria_records:
          type: array
          description: Criteria rows to add, update, or delete
          items:
            type: object
            additionalProperties: true
    DataRecordsRequest:
      type: object
      required: [application_id, source_id, data_records]
      properties:
        application_id:
          type: string
        source_id:
          type: string
        data_records:
          type: array
          items:
            type: object
            additionalProperties: true
        file_path:
          type: string
          description: Optional absolute path to an attachment file on shared storage (add only)

  responses:
    Unauthorized:
      description: Invalid or missing X-reflexis-csrf-token-X (HTTP 401)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            status: ER
            api_error_code: E202
            response: User session is invalid
    BadRequest:
      description: Invalid or missing request parameter
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalServerError:
      description: Unexpected server-side error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            status: ER
            api_error_code: E500
            response: Internal server error

paths:
  # ---------------------------------------------------------------------------
  # Indexer — configuration
  # ---------------------------------------------------------------------------
  /indexer/v1/config/global-smart-search:
    get:
      tags: [IndexerConfig]
      summary: Global Smart Search configuration
      operationId: getGlobalSmartSearchConfig
      description: |
        Returns permission-filtered applications, per-app filter definitions (`basic` / `advanced`),
        date filter presets, and UI defaults from `INDEXER_SETUP` system codes.

        See `devdocs/api/nextgen/indexer/INDEXER_API_CONTRACT_GlobalSmartSearch.md`.
      responses:
        '200':
          description: 'Success — `{status: OK, global_smart_search_config: {...}}`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonObject'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /indexer/v1/config/filter-options:
    get:
      tags: [IndexerConfig]
      summary: Dynamic filter option lookup
      operationId: getFilterOptions
      description: |
        Returns option lists for filters whose `option_source` is `"D"` (dynamic).
        May include `range_limit` for range-slider filters (e.g. QDocs file size).
      parameters:
        - name: app_id
          in: query
          required: true
          schema:
            type: string
          description: Application ID (e.g. `100`, `105`)
          example: '100'
        - name: source
          in: query
          required: true
          schema:
            type: string
          description: Filter key from global-smart-search config (e.g. `status`, `priority`)
          example: status
      responses:
        '200':
          description: 'Success — `{status: OK, filter_options: [...], range_limit?: {...}}`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonObject'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'

  # ---------------------------------------------------------------------------
  # Indexer — search data
  # ---------------------------------------------------------------------------
  /indexer/v1/search/data:
    get:
      tags: [IndexerSearch]
      summary: Smart-search data (preview or paginated)
      operationId: getIndexerSearchData
      description: |
        Unified replacement for legacy `/service/search/getSearchData` and
        `/service/search/getMoreSearchData`. All session params are derived from the auth token.

        **Fetch modes:**
        - `preview` — initial/top-level view (limited records, no pagination)
        - `paginated` — full pagination with Next/Previous (`user_action=NP` / `PP`)

        **Recommended paginated flow:** send `user_action` on every paginated call.
        - `A` (Apply) — fresh search; requires `search_data`, `start_date`, `end_date`
        - `NP` / `PP` — next/previous page; search text and dates are resolved from Redis session

        See `devdocs/api/nextgen/indexer/INDEXER_SEARCH_API_CONTRACT.md`.
      parameters:
        - name: application_id
          in: query
          required: true
          schema:
            type: string
          description: Application ID (`100` Projects, `101`–`104` Forms/Walks, `105` QDocs, `107` QCheck)
          example: '100'
        - name: page_type
          in: query
          required: true
          schema:
            type: string
            enum: ['O', 'R']
          description: '`O` = Overlay, `R` = Result Page'
        - name: fetch_mode
          in: query
          required: true
          schema:
            type: string
            enum: [preview, paginated]
        - name: is_requested_for_all
          in: query
          required: true
          schema:
            type: string
            enum: ['true', 'false']
          description: Preview only — `true` fetches RECORDS_COUNT_ALL per app; `false` fetches RECORDS_COUNT_INDIVIDUAL
        - name: search_data
          in: query
          required: false
          schema:
            type: string
          description: Search text. Required for new search (`user_action=A` or no pagination cursor)
        - name: start_date
          in: query
          required: false
          schema:
            type: string
          description: Range start `yyyyMMdd`. Required for new search
          example: '20260101'
        - name: end_date
          in: query
          required: false
          schema:
            type: string
          description: Range end `yyyyMMdd`. Required for new search
          example: '20260331'
        - name: user_action
          in: query
          required: false
          schema:
            type: string
            enum: ['A', 'NP', 'PP']
          description: Paginated flow — `A` Apply, `NP` Next Page, `PP` Previous Page
        - name: search_reference
          in: query
          required: false
          schema:
            type: string
          description: Legacy pagination cursor (ignored when `user_action` is present)
        - name: page_number
          in: query
          required: false
          schema:
            type: integer
          description: Legacy direct page jump (ignored when `user_action` is present)
        - name: search_category
          in: query
          required: false
          schema:
            type: string
          description: Comma-separated category filter
        - name: ignore_case
          in: query
          required: false
          schema:
            type: string
            enum: ['Y', 'N']
          description: Case sensitivity — defaults to `Y`
        - name: tags
          in: query
          required: false
          schema:
            type: string
          description: Comma-separated tags
        - name: advanced_search
          in: query
          required: false
          schema:
            type: string
            enum: ['Y', 'N']
        - name: view_type
          in: query
          required: false
          schema:
            type: string
          description: '`SV` Store View, `DV` Department View, etc.'
          example: SV
        - name: filter_metadata
          in: query
          required: false
          schema:
            type: string
          description: URL-encoded JSON object of structured filter values (see INDEXER_SEARCH_API_CONTRACT.md)
      responses:
        '200':
          description: |
            Success — preview (`has_more_results`, `records_count`) or paginated
            (`current_page`, `has_next`, `has_previous`, …). Empty `search_data` is valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonObject'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'

  # ---------------------------------------------------------------------------
  # Indexer — saved search filters
  # ---------------------------------------------------------------------------
  /indexer/v1/search-filters:
    get:
      tags: [IndexerSearchFilters]
      summary: List saved search filters
      operationId: getSearchFilters
      description: |
        Returns custom and system saved filters for the authenticated user.
        See `devdocs/api/nextgen/indexer/INDEXER_API_CONTRACT_SearchFilters.md`.
      responses:
        '200':
          description: 'Success — `{status: OK, search_filters: {custom: [], system: []}}`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonObject'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'

    post:
      tags: [IndexerSearchFilters]
      summary: Save a new search filter
      operationId: saveSearchFilter
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required: [filter_name, filter_criteria]
              properties:
                filter_name:
                  type: string
                  description: Display name — mandatory (E530)
                filter_criteria:
                  type: string
                  description: Semicolon-separated criteria string — mandatory (E531)
      responses:
        '200':
          description: 'Success — `{status: OK, search_filter: {...}}`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonObject'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'

    delete:
      tags: [IndexerSearchFilters]
      summary: Delete a saved search filter
      operationId: deleteSearchFilter
      parameters:
        - name: filter_id
          in: query
          required: true
          schema:
            type: string
          description: Filter ID to delete — mandatory (E532)
      responses:
        '200':
          description: 'Success — `{status: OK, message: "..."}`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonObject'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'

  # ---------------------------------------------------------------------------
  # Indexer — recent searches
  # ---------------------------------------------------------------------------
  /indexer/v1/recent-searches/add:
    post:
      tags: [IndexerRecentSearches]
      summary: Record a recent search on redirect
      operationId: addRecentSearch
      description: |
        Explicit write path — clients call this after the user picks a search result and is redirected.
        `/indexer/v1/search/data` never persists recents as a side-effect.

        See `devdocs/api/nextgen/indexer/INDEXER_API_CONTRACT_RecentSearches.md`.
      parameters:
        - name: search_text
          in: query
          required: true
          schema:
            type: string
          description: Query text — mandatory (E539)
        - name: application_id
          in: query
          required: true
          schema:
            type: string
          description: App scope (e.g. `100`) or sentinel `ALL` — mandatory (E501)
        - name: result_count
          in: query
          required: false
          schema:
            type: integer
          description: Hit count from client; defaults to 1 when omitted
        - name: start_date
          in: query
          required: false
          schema:
            type: string
        - name: end_date
          in: query
          required: false
          schema:
            type: string
        - name: searched_on_all
          in: query
          required: false
          schema:
            type: boolean
        - name: profile_id
          in: query
          required: false
          schema:
            type: string
        - name: department_id
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          description: 'Success — `{status: OK, message: "Recent search added successfully."}`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonObject'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /indexer/v1/recent-searches:
    get:
      tags: [IndexerRecentSearches]
      summary: List recent searches (newest first)
      operationId: getRecentSearches
      parameters:
        - name: application_id
          in: query
          required: false
          schema:
            type: string
          description: Scope to one app (e.g. `100`) or `ALL`
        - name: searched_on_all
          in: query
          required: false
          schema:
            type: boolean
          description: When true, returns only ALL-mode rows (takes precedence over application_id)
      responses:
        '200':
          description: 'Success — `{status: OK, recent_searches: [...]}` (may be empty)'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonObject'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'

    delete:
      tags: [IndexerRecentSearches]
      summary: Delete one recent-search row
      operationId: deleteRecentSearch
      parameters:
        - name: recent_search_id
          in: query
          required: true
          schema:
            type: string
          description: Row UUID — mandatory (E536)
      responses:
        '200':
          description: 'Success — `{status: OK, message: "Recent search deleted successfully."}`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonObject'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /indexer/v1/recent-searches/all:
    delete:
      tags: [IndexerRecentSearches]
      summary: Clear recent-search history
      operationId: clearRecentSearches
      description: Idempotent — optional scope via `application_id` or `searched_on_all=true`.
      parameters:
        - name: application_id
          in: query
          required: false
          schema:
            type: string
        - name: searched_on_all
          in: query
          required: false
          schema:
            type: boolean
      responses:
        '200':
          description: 'Success — `{status: OK, message: "Recent searches cleared successfully."}`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonObject'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'

  # ---------------------------------------------------------------------------
  # Indexer — data ingest
  # ---------------------------------------------------------------------------
  /indexer/v1/data:
    post:
      tags: [IndexerData]
      summary: Add search data records
      operationId: addIndexerData
      description: |
        Forwards to ztm-indexer `SearchDataController`. Each `data_records` item carries
        `entityId`, `documentId`, `searchCategory`, etc. See
        `devdocs/api/nextgen/indexer/INDEXER_API_CONTRACT_Data.md`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DataRecordsRequest'
      responses:
        '200':
          description: 'Success — `{status: OK, message: "..."}`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonObject'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'

    put:
      tags: [IndexerData]
      summary: Update search data records
      operationId: updateIndexerData
      description: Each record should include `whereJSON` and `updateJSON` objects.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DataRecordsRequest'
      responses:
        '200':
          description: 'Success — `{status: OK, message: "..."}`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonObject'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'

    delete:
      tags: [IndexerData]
      summary: Delete search data records
      operationId: deleteIndexerData
      description: Each delete item must include `domainId`, `applicationId`, and `documentId` (E542).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DataRecordsRequest'
      responses:
        '200':
          description: 'Success — `{status: OK, message: "..."}`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonObject'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'

  # ---------------------------------------------------------------------------
  # Indexer — criteria ingest
  # ---------------------------------------------------------------------------
  /indexer/v1/criteria:
    post:
      tags: [IndexerCriteria]
      summary: Add search criteria records
      operationId: addIndexerCriteria
      description: |
        Forwards to ztm-indexer `SearchCriteriaController`. See
        `devdocs/api/nextgen/indexer/INDEXER_API_CONTRACT_Criteria.md`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CriteriaRecordsRequest'
      responses:
        '200':
          description: 'Success — `{status: OK, message: "..."}`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonObject'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'

    put:
      tags: [IndexerCriteria]
      summary: Update search criteria records
      operationId: updateIndexerCriteria
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CriteriaRecordsRequest'
      responses:
        '200':
          description: 'Success — `{status: OK, message: "..."}`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonObject'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'

    delete:
      tags: [IndexerCriteria]
      summary: Delete search criteria records
      operationId: deleteIndexerCriteria
      description: Each delete item must include `domainId`, `applicationId`, and `documentId` (E552).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CriteriaRecordsRequest'
      responses:
        '200':
          description: 'Success — `{status: OK, message: "..."}`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonObject'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
