openapi: 3.0.0
info:
  title: Indexing Service
  version: v1
  description: |
    The indexing service allows you to manage indexing configuration. Currently supported index providers:
      * Algolia - https://www.algolia.com
      * Battery Included - https://www.batteryincluded.io

    **Provider mutual exclusivity:**
    Only one provider can be active at a time per tenant. This constraint is enforced by the configuration service.

    **Battery Included limitations:**
    This feature is in a `preview` state and payload sent to battery included is subject to change. 
    Battery Included only supports the `MERGE` site-aware fields strategy. Tenants configured with the `SPLIT`
    strategy will have Battery Included indexing silently skipped.

    **Algolia limitations:**
    By default, Algolia indexes provided by Emporix support records up to 10kB in size.
    In order to support larger records, you must provide your own Algolia service.
    For more information, please refer to documents provided by Algolia:
      * [Algolia documentation](https://www.algolia.com/doc/guides/scaling/algolia-service-limits#application-record-and-index-limits)
      * [Algolia FAQ](https://support.algolia.com/hc/en-us/articles/4406981897617-Is-there-a-size-limit-for-my-index-records)
  contact:
    email: documentation@emporix.com
servers:
  - url: 'https://api.emporix.io'
paths:
  '/indexing/{tenant}/configurations':
    post:
      summary: Create a new configuration
      description: |-
        Creates a new index configuration. Supported providers:
        * Algolia - https://www.algolia.com
        * Battery Included - https://www.batteryincluded.io

        Identifier of a newly created configuration is a provider name.
        Only one provider can be active per tenant at a time.
      security:
        - OAuth2:
            - indexing.search_manage
      parameters:
        - $ref: '#/components/parameters/trait_tenant'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IndexConfiguration'
            examples:
              Create Algolia configuration:
                value:
                  active: true
                  searchKey: 84dc4886f81f805c42bdd89d64de751a
                  applicationId: 8AP2HABA2I
                  indexName: exampleTenant
                  writeKey: 51ebe89215dddcf85e5dacd5643d17e7
                  provider: ALGOLIA
              Create Battery Included configuration:
                value:
                  active: true
                  indexName: exampleTenant
                  writeKey: bi-api-key-abc123
                  provider: BATTERY_INCLUDED
                  excludedMixinKeys:
                    - internalAttributes
        description: ''
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IndexCreationResponse'
              examples:
                Algolia creation response:
                  value:
                    id: ALGOLIA
                Battery Included creation response:
                  value:
                    id: BATTERY_INCLUDED
        '400':
          $ref: '#/components/responses/BadRequest_400'
        '401':
          $ref: '#/components/responses/Unauthorized_401'
        '403':
          $ref: '#/components/responses/Forbidden_403'
      operationId: POST-indexing-create-config
      tags:
        - Configuration
    get:
      summary: Get all configurations
      description: Retrieves all configurations of index providers. The returned response contains search and write keys.
      security:
        - OAuth2:
            - indexing.search_view
      parameters:
        - $ref: '#/components/parameters/trait_tenant'
      responses:
        '200':
          description: ''
          content:
            application/json:
              examples:
                Get all configurations:
                  value:
                    - active: true
                      searchKey: 84dc4886f81f805c42bdd89d64de751a
                      applicationId: 8AP2HABA2I
                      indexName: exampleTenant
                      writeKey: 51ebe89215dddcf85e5dacd5643d17e7
                      provider: ALGOLIA
                    - active: false
                      indexName: exampleTenant
                      writeKey: bi-api-key-abc123
                      provider: BATTERY_INCLUDED
                      excludedMixinKeys:
                        - internalAttributes
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/IndexConfiguration'
        '401':
          $ref: '#/components/responses/Unauthorized_401'
        '403':
          $ref: '#/components/responses/Forbidden_403'
      operationId: GET-indexing-list-configs
      tags:
        - Configuration
    parameters:
      - schema:
          type: string
        name: tenant
        in: path
        required: true
  '/indexing/{tenant}/configurations/{provider}':
    get:
      summary: Get configuration by provider name
      description: |-
        Retrieves a single configuration by a provider name. Supported providers:
        * Algolia - https://www.algolia.com
        * Battery Included - https://www.batteryincluded.io
      security:
        - OAuth2:
            - indexing.search_view
      parameters: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              examples:
                Get Algolia configuration:
                  value:
                    active: true
                    searchKey: 84dc4886f81f805c42bdd89d64de751a
                    applicationId: 8AP2HABA2I
                    indexName: exampleTenant
                    writeKey: 51ebe89215dddcf85e5dacd5643d17e7
                    provider: ALGOLIA
                Get Battery Included configuration:
                  value:
                    active: true
                    indexName: exampleTenant
                    writeKey: bi-api-key-abc123
                    provider: BATTERY_INCLUDED
                    excludedMixinKeys:
                      - internalAttributes
              schema:
                $ref: '#/components/schemas/IndexConfiguration'
        '401':
          $ref: '#/components/responses/Unauthorized_401'
        '403':
          $ref: '#/components/responses/Forbidden_403'
        '404':
          $ref: '#/components/responses/NotFound_404'
      tags:
        - Configuration
      operationId: GET-indexing-retrieve-config
    put:
      summary: Update configuration by provider name
      description: Updates an existing index configuration.
      security:
        - OAuth2:
            - indexing.search_manage
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IndexConfiguration'
            examples:
              Update Algolia configuration:
                value:
                  active: true
                  searchKey: 84dc4886f81f805c42bdd89d64de751a
                  applicationId: 8AP2HABA2I
                  indexName: exampleTenant
                  writeKey: 51ebe89215dddcf85e5dacd5643d17e7
                  provider: ALGOLIA
              Update Battery Included configuration:
                value:
                  active: true
                  indexName: exampleTenant
                  writeKey: bi-api-key-abc123
                  provider: BATTERY_INCLUDED
                  excludedMixinKeys:
                    - internalAttributes
                    - customData
      responses:
        '204':
          description: Configuration updated
        '400':
          $ref: '#/components/responses/BadRequest_400'
        '403':
          $ref: '#/components/responses/Forbidden_403'
        '404':
          $ref: '#/components/responses/NotFound_404'
      operationId: PUT-indexing-update-config
      tags:
        - Configuration
    delete:
      summary: Delete configuration
      description: Deletes the configuration based on the provider name.
      security:
        - OAuth2:
            - indexing.search_manage
      parameters:
        - $ref: '#/components/parameters/trait_tenant'
      responses:
        '204':
          description: Configuration deleted
        '401':
          $ref: '#/components/responses/Unauthorized_401'
        '403':
          $ref: '#/components/responses/Forbidden_403'
        '404':
          $ref: '#/components/responses/NotFound_404'
      operationId: DELETE-indexing-remove-config
      tags:
        - Configuration
    parameters:
      - name: tenant
        in: path
        required: true
        description: |
          The tenant that the caller is acting upon.

          Please note that this value is always lowercase.
        schema:
          pattern: '^[a-z][a-z0-9]+$'
          minLength: 3
          maxLength: 16
          type: string
      - $ref: '#/components/parameters/trait_provider'
  '/indexing/{tenant}/public/configurations':
    parameters:
      - $ref: '#/components/parameters/trait_tenant'
    get:
      summary: Get all public configurations
      tags:
        - Public Configuration
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/IndexPublicConfiguration'
              examples:
                Public configurations:
                  value:
                    - active: true
                      searchKey: 84dc4886f81f805c42bdd89d64de751a
                      applicationId: 8AP2HABA2I
                      indexName: exampleTenant
                      provider: ALGOLIA
                    - active: false
                      indexName: exampleTenant
                      provider: BATTERY_INCLUDED
        '401':
          description: Unauthorized
      operationId: GET-indexing-list-public-configs
      description: Retrieves all configurations of index providers. The returned response contains only search keys. Write keys are not returned.
      security:
        - OAuth2: []
  '/indexing/{tenant}/public/configurations/{provider}':
    parameters:
      - $ref: '#/components/parameters/trait_tenant'
      - $ref: '#/components/parameters/trait_provider'
    get:
      summary: Get public configuration
      tags:
        - Public Configuration
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IndexPublicConfiguration'
              examples:
                Public Algolia configuration:
                  value:
                    active: true
                    searchKey: 84dc4886f81f805c42bdd89d64de751a
                    applicationId: 8AP2HABA2I
                    indexName: exampleTenant
                    provider: ALGOLIA
                Public Battery Included configuration:
                  value:
                    active: true
                    indexName: exampleTenant
                    provider: BATTERY_INCLUDED
                    searchKey: 84dc4886f81f805c42bdd89d64de751x
        '401':
          $ref: '#/components/responses/Unauthorized_401'
        '404':
          $ref: '#/components/responses/NotFound_404'
      operationId: GET-indexing-retrieve-public-config
      description: |-
        Retrieves a single public configuration by a provider name. Supported providers:
        * Algolia - https://www.algolia.com
        * Battery Included - https://www.batteryincluded.io
      security:
        - OAuth2: []
  '/indexing/{tenant}/reindex':
    parameters:
      - schema:
          type: string
        name: tenant
        in: path
        required: true
    post:
      summary: Reindex
      operationId: POST-indexing-reindex
      responses:
        '204':
          description: ''
        '400':
          $ref: '#/components/responses/BadRequest_400'
        '401':
          $ref: '#/components/responses/Unauthorized_401'
        '403':
          $ref: '#/components/responses/Forbidden_403'
      tags:
        - Reindex
      description: |-
        Triggers indexing process of products for the tenant. The reindex works with a `FULL` mode - all products are reindexed.
      security:
        - OAuth2:
            - indexing.search_manage
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Reindex'
            examples:
              Reindex request:
                value:
                  mode: FULL
components:
  schemas:
    errorMessage:
      title: error
      description: Schema for API specified errors.
      type: object
      properties:
        code:
          description: 'Original HTTP error code, should be consistent with the response HTTP code'
          type: integer
        status:
          description: Classification of the error type
          type: string
        message:
          description: Descriptive error message for debugging
          type: string
        details:
          type: array
          description: Error details
          items:
            type: string
    IndexPublicConfiguration:
      title: IndexPublicConfiguration
      type: object
      properties:
        searchKey:
          type: string
          description: API Key used for search purposes.
        applicationId:
          type: string
          description: Application id of an indexer provider.
        indexName:
          type: string
          description: Identifier of an index.
        provider:
          type: string
          description: 'Index provider name. Supported providers: `ALGOLIA` (https://www.algolia.com), `BATTERY_INCLUDED` (https://www.batteryincluded.io). Only one provider can be active per tenant at a time.'
          enum:
            - ALGOLIA
            - BATTERY_INCLUDED
        active:
          type: boolean
          description: Indicates if the configuration is active or not.
    IndexConfiguration:
      title: IndexConfiguration
      allOf:
        - $ref: '#/components/schemas/IndexPublicConfiguration'
        - type: object
          properties:
            writeKey:
              type: string
              description: API key used for write purposes.
            excludedMixinKeys:
              type: array
              items:
                type: string
              description: >-
                Optional list of root product mixin keys to exclude from indexing.
                When set, the specified mixin keys are omitted from both the non-localized
                and localized portions of the indexed document.
                Applies only to the `BATTERY_INCLUDED` provider; ignored for `ALGOLIA`.
          required:
            - provider
    IndexCreationResponse:
      title: IndexCreationResponse
      type: object
      properties:
        id:
          type: string
          description: Identifier of a newly created configuration.
    Reindex:
      title: Reindex
      type: object
      properties:
        mode:
          type: string
          enum:
            - FULL
          description: 'Indicates reindex mode. Supported modes: `FULL`.'
  responses:
    Forbidden_403:
      description: Given authorization scopes are not sufficient and do not match scopes required by the endpoint.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorMessage'
          examples:
            ForbiddenExample:
              value:
                status: Forbidden
                details:
                  - 'Missing required scopes ''[indexing.search_view]'''
                code: 403
                message: Scope validation failed
    Unauthorized_401:
      description: Given request is unauthorized - the authorization token is invalid or has expired. Details will be provided in the response payload.
      content:
        application/json:
          schema:
            type: object
            properties:
              fault:
                type: object
                properties:
                  faultstring:
                    type: string
                  detail:
                    type: object
                    properties:
                      errorcode:
                        type: string
          examples:
            UnauthorizedExample:
              value:
                fault:
                  faultstring: Invalid access token
                  detail:
                    errorcode: oauth.v2.InvalidAccessToken
            AccessTokenExpiredExample:
              value:
                fault:
                  faultstring: Access Token expired
                  detail:
                    errorcode: keymanagement.service.access_token_expired
    BadRequest_400:
      description: Request was syntactically incorrect. Details will be provided in the response payload.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorMessage'
          examples:
            Example 1:
              value:
                code: 400
                status: Bad Request
                message: The provider UNKNOWN_PROVIDER is not supported.
    NotFound_404:
      description: Resource has not been found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorMessage'
          examples:
            Not found:
              value:
                code: 404
                status: Not Found
                message: The provider UNKNOWN_PROVIDER is not supported.
  parameters:
    trait_tenant:
      name: tenant
      in: path
      required: true
      description: |
        The tenant that the caller is acting upon.

        Please note that this value is always lowercase.
      schema:
        pattern: '^[a-z][a-z0-9]+$'
        minLength: 3
        maxLength: 16
        type: string
    trait_provider:
      name: provider
      in: path
      required: true
      schema:
        type: string
        enum:
          - ALGOLIA
          - BATTERY_INCLUDED
      description: 'Provider name. Supported values: `ALGOLIA`, `BATTERY_INCLUDED`'
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: 'https://api.emporix.io/oauth/token'
          scopes:
            indexing.search_view: Needed to read an index provider configuration
            indexing.search_manage: Needed to manage an index provider configuration
  examples: {}
  requestBodies: {}
security:
  - OAuth2:
      - indexing.search_manage
      - indexing.search_view
tags:
  - name: Configuration
  - name: Public Configuration
  - name: Reindex