docs(abtests) v3 api

specs/abtesting-v3/common/parameters.yml

@@ -0,0 +1,158 @@
+# path
+ID:
+  in: path
+  name: id
+  description: Unique A/B test identifier.
+  required: true
+  schema:
+    $ref: "#/abTestID"
+
+# misc
+index:
+  type: string
+  description: Index name of the A/B test variant (case-sensitive).
+  example: "delcourt_production"
+
+abTestID:
+  type: integer
+  description: Unique A/B test identifier.
+  example: 224
+
+abTestScheduleID:
+  type: integer
+  description: Unique scheduled A/B test identifier.
+  example: 224
+
+endAt:
+  type: string
+  description: End date and time of the A/B test, in RFC 3339 format.
+  example: 2023-06-17T00:00:00Z
+
+createdAt:
+  type: string
+  description: Date and time when the A/B test was created, in RFC 3339 format.
+  example: 2023-06-15T15:06:04.249906Z
+
+updatedAt:
+  type: string
+  description: Date and time when the A/B test was last updated, in RFC 3339 format.
+  example: 2023-06-15T15:06:44.400601Z
+
+scheduledAt:
+  type: string
+  description: Date and time when the A/B test is scheduled to start, in RFC 3339 format.
+  example: 2023-06-15T15:06:44.400601Z
+
+name:
+  type: string
+  description: A/B test name.
+  example: Custom ranking sales rank test
+
+description:
+  type: string
+  description: Description for this variant.
+  example: Current production index
+
+trafficPercentage:
+  type: integer
+  description: Percentage of search requests each variant receives.
+  minimum: 0
+  maximum: 100
+  example: 60
+
+currencies:
+  type: object
+  description: A/B test currencies.
+  example:
+    USD:
+      currency: USD
+      revenue: 120.0
+      mean: 53.7
+      standardDeviation: 12.3
+    EUR:
+      currency: EUR
+      revenue: 100.0
+      mean: 43.7
+      standardDeviation: 10.3
+  additionalProperties:
+    $ref: "#/currency"
+    x-additionalPropertiesName: currency code
+
+currency:
+  type: object
+  properties:
+    currency:
+      type: string
+      description: Currency code.
+      example: "USD"
+    revenue:
+      type: number
+      format: double
+      description: Revenue for this currency.
+      example: 120.0
+    mean:
+      type: number
+      format: double
+      description: Mean for this currency.
+      example: 53.7
+    standardDeviation:
+      type: number
+      format: double
+      description: Standard deviation for this currency.
+      example: 12.3
+
+filterEffects:
+  type: object
+  description: A/B test filter effects resulting from configuration settings.
+  properties:
+    outliers:
+      title: outliersFilter
+      type: object
+      description: Outliers removed from the A/B test as a result of configuration settings.
+      example:
+        usersCount: 1
+        trackedSearchesCount: 237
+      properties:
+        usersCount:
+          type: integer
+          description: Number of users removed from the A/B test.
+          example: 1
+        trackedSearchesCount:
+          type: integer
+          description: Number of tracked searches removed from the A/B test.
+          example: 237
+    emptySearch:
+      title: emptySearchFilter
+      type: object
+      description: Empty searches removed from the A/B test as a result of configuration settings.
+      example:
+        usersCount: 1
+        trackedSearchesCount: 237
+      properties:
+        usersCount:
+          type: integer
+          description: Number of users removed from the A/B test.
+          example: 1
+        trackedSearchesCount:
+          type: integer
+          description: Number of tracked searches removed from the A/B test.
+          example: 237
+
+metric:
+  type: object
+  description: Defines a metric to be retrieved during an A/B test.
+  properties:
+    name:
+      type: string
+      description: Name of the metric.
+    dimension:
+      type: string
+      description: Dimension of the metric, for example, in case of a revenue metric it could be USD, EUR...
+  required:
+    - name
+  example:
+    - name: revenue
+      dimension: USD
+    - name: conversionRate
+    - name: clickThroughRate
+    - name: trackedSearchCount

specs/abtesting-v3/common/schemas/ABTest.yml

@@ -0,0 +1,170 @@
+ABTests:
+  oneOf:
+    - type: array
+      description: A/B tests.
+      items:
+        $ref: '#/ABTest'
+    - type: 'null'
+      description: No A/B tests are configured for this application.
+
+ABTest:
+  type: object
+  additionalProperties: false
+  properties:
+    abTestID:
+      $ref: '../parameters.yml#/abTestID'
+    clickSignificance:
+      description: |
+        A/B test significance calculated from click events.
+
+        Values of 0.95 or higher can be considered significant,
+        that is, the difference between A and B variants is _not_ due to random variations.
+        Lower values have a.
+      oneOf:
+        - type: number
+          format: double
+          example: 1
+        - type: 'null'
+    conversionSignificance:
+      description: |
+        A/B test significance calculated from conversion events.
+
+        Values of 0.95 or higher can be considered significant,
+        that is, the difference between A and B variants is _not_ due to random variations.
+      oneOf:
+        - type: number
+          format: double
+          example: 1
+        - type: 'null'
+    addToCartSignificance:
+      description: |
+        A/B test significance calculated from add-to-cart events.
+
+        Values of 0.95 or higher can be considered significant,
+        that is, the difference between A and B variants is _not_ due to random variations.
+      oneOf:
+        - type: number
+          format: double
+          example: 1
+        - type: 'null'
+    purchaseSignificance:
+      description: |
+        A/B test significance calculated from purchase events.
+
+        Values of 0.95 or higher can be considered significant,
+        that is, the difference between A and B variants is _not_ due to random variations.
+      oneOf:
+        - type: number
+          format: double
+          example: 1
+        - type: 'null'
+    revenueSignificance:
+      description: |
+        A/B test significance calculated from revenue data.
+
+        Values of 0.95 or higher can be considered significant,
+        that is, the difference between A and B variants is _not_ due to random variations.
+      oneOf:
+        - type: object
+          additionalProperties:
+            type: number
+            format: double
+            x-additionalPropertiesName: currency code
+          example:
+            USD: 1
+            EUR: 0.87
+        - type: 'null'
+    updatedAt:
+      $ref: '../parameters.yml#/updatedAt'
+    createdAt:
+      $ref: '../parameters.yml#/createdAt'
+    endAt:
+      $ref: '../parameters.yml#/endAt'
+    name:
+      $ref: '../parameters.yml#/name'
+    status:
+      $ref: '#/Status'
+    variants:
+      $ref: 'Variant.yml#/variants'
+    configuration:
+      $ref: '#/ABTestConfiguration'
+  required:
+    - status
+    - name
+    - createdAt
+    - endAt
+    - updatedAt
+    - abTestID
+    - variants
+
+Status:
+  type: string
+  description: |
+    A/B test status.
+
+    - `active`. The A/B test is live and search traffic is split between the two variants.
+    - `stopped`. You stopped the A/B test. The A/B test data is still available for analysis.
+    - `expired`. The A/B test was automatically stopped after reaching its end date.
+    - `failed`. Creating the A/B test failed.
+  example: active
+  enum:
+    - active
+    - stopped
+    - expired
+    - failed
+
+ABTestConfiguration:
+  title: configuration
+  type: object
+  description: A/B test configuration.
+  properties:
+    outliers:
+      $ref: '#/Outliers'
+    emptySearch:
+      $ref: '#/EmptySearch'
+    minimumDetectableEffect:
+      $ref: '#/MinimumDetectableEffect'
+
+Outliers:
+  type: object
+  description: Configuration for handling outliers.
+  properties:
+    exclude:
+      type: boolean
+      description: Whether to exclude outliers when calculating A/B test results.
+      default: true
+
+EmptySearch:
+  type: object
+  description: Configuration for handling empty searches.
+  properties:
+    exclude:
+      type: boolean
+      description: Whether to exclude empty searches when calculating A/B test results.
+
+MinimumDetectableEffect:
+  type: object
+  description: Configuration for the smallest difference between test variants you want to detect.
+  properties:
+    size:
+      type: number
+      format: double
+      minimum: 0
+      maximum: 1
+      description: |
+        Smallest difference in an observable metric between variants.
+        For example, to detect a 10% difference between variants, set this value to 0.1.
+    metric:
+      $ref: '#/EffectMetric'
+  required:
+    - size
+    - metric
+
+EffectMetric:
+  type: string
+  description: Metric for which you want to detect the smallest relative difference.
+  enum:
+    - addToCartRate
+    - clickThroughRate
+    - conversionRate
+    - purchaseRate

specs/abtesting-v3/common/schemas/ABTestResponse.yml

@@ -0,0 +1,14 @@
+ABTestResponse:
+  type: object
+  additionalProperties: false
+  properties:
+    index:
+      $ref: '../parameters.yml#/index'
+    abTestID:
+      $ref: '../parameters.yml#/abTestID'
+    taskID:
+      $ref: '../../../common/responses/common.yml#/taskID'
+  required:
+    - abTestID
+    - index
+    - taskID

specs/abtesting-v3/common/schemas/AddABTestsVariant.yml

@@ -0,0 +1,38 @@
+AddABTestsVariant:
+  oneOf:
+    - $ref: '#/abTestsVariant'
+    - $ref: '#/abTestsVariantSearchParams'
+
+abTestsVariantSearchParams:
+  allOf:
+    - $ref: '#/abTestsVariant'
+    - $ref: '#/customSearchParams'
+
+abTestsVariant:
+  type: object
+  additionalProperties: false
+  properties:
+    index:
+      $ref: '../parameters.yml#/index'
+    trafficPercentage:
+      $ref: '../parameters.yml#/trafficPercentage'
+    description:
+      $ref: '../parameters.yml#/description'
+  required:
+    - index
+    - trafficPercentage
+
+customSearchParams:
+  type: object
+  description: |
+    Search parameters to add to the test variant.
+    Only use this parameter if the two variants use the same index.
+  example: {'typoTolerance': false, 'synonyms': false}
+  additionalProperties: false
+  properties:
+    customSearchParameters:
+      type: object
+  required:
+    - customSearchParameters
+  x-discriminator-fields:
+    - customSearchParameters