api-spec.yaml

openapi: 3.0.0
info:
  title: ABsmartly Collector API
  version: 1.0.0
  description: An OpenAPI Specification that describes the ABsmartly Collector API. This API is mainly used when using ABsmartly in a language that does not yet have a supported SDK.
  contact:
    name: API Support
    email: api@absmartly.com
  license:
    name: Proprietary
externalDocs:
  description: Find out more about ABsmartly
  url: "https://www.absmartly.com"
servers:
  - url: https://sandbox.absmartly.io/v1
security:
  - ApiKey: []
tags:
  - name: context
    description: Context API
  - name: experiment
    description: Experiment API

paths:
  /healthy:
    get:
      tags:
        - collector
      summary: Check Service Health
      description: A GET request to check that the service is running as expected.
      operationId: collectorHealthCheck
      responses:
        200:
          description: Server is healthy
        500:
          description: Server is not healthy

  /context:
    get:
      tags:
        - context
      summary: Get Context Experiment Data
      description: A GET request for obtaining data on your experiments.
      operationId: contextGet
      parameters:
        - name: environment
          in: query
          required: false
          description: An environment to filter the results by. These can be found and created in your ABsmartly Web Console settings.
          example: development
          schema:
            type: string
        - name: application
          in: query
          required: false
          description: An application to filter the results by. These can be found and created in your ABsmartly Web Console settings.
          example: www
          schema:
            type: string
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContextGetResponse"
        400:
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        401:
          description: Unauthorized
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

    post:
      tags:
        - context
      summary: Create a Context
      description: A POST request for creating a new context and assigning variants to your users.
      operationId: contextCreate
      parameters:
        - name: X-Agent
          in: header
          required: true
          description: The User-Agent of your SDK.
          example: absmartly-Java-SDK v1.0.1
          schema:
            type: string
        - name: X-Environment
          in: header
          required: true
          description: The environment in which you are running your experiments. These can be found and created in your ABsmartly Web Console settings.
          example: development
          schema:
            type: string
        - name: X-Application
          in: header
          required: true
          description: The application in which you are running your experiments. These can be found and created in your ABsmartly Web Console settings.
          example: www
          schema:
            type: string
        - name: X-Application-Version
          in: header
          required: true
          description: The application version which you are running your experiments on.
          example: 0
          schema:
            type: integer
            format: int64
      requestBody:
        required: true
        description: |
          Units data for which to create the context and variant assignments. Unit types can be found and created in your ABsmartly Web Console settings.

          ```json
          {
            "type": "user_id" // The name of the unit type
            "uid": "4a42766ca6313d26f49985e799ff4f3790fb86efa0fce46edb3ea8fbf1ea3408" // The value of the unit that you are tracking.
          }
          ```
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ContextRequest"
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContextResponse"
        400:
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        401:
          description: Unauthorized
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

    put:
      tags:
        - context
      summary: Publish Experiment Events
      description: A PUT request for publishing your exposures, goals and attributes.
      operationId: contextPublish
      parameters:
        - name: X-Agent
          in: header
          required: true
          description: The User-Agent of your SDK.
          example: absmartly-Java-SDK v1.0.1
          schema:
            type: string
        - name: X-Environment
          in: header
          required: true
          description: The environment in which you are running your experiments. These can be found and created in your ABsmartly Web Console settings.
          example: development
          schema:
            type: string
        - name: X-Application
          in: header
          required: true
          description: The application in which you are running your experiments. These can be found and created in your ABsmartly Web Console settings.
          example: www
          schema:
            type: string
        - name: X-Application-Version
          in: header
          required: true
          description: The application version which you are running your experiments on.
          example: 0
          schema:
            type: integer
            format: int64
      requestBody:
        required: true
        description: |
          The data to be published.

          **Hashed**

          The hashed value describes whether your values have already been hashed, or if they are to be hashed by the Collector.

          **Historic**

          The historic value tells the Collector whether this is new or old data.

          **Published At**

          The publishedAt value is the time at which the request was made.

          **Units**

          Units are the values which are used to choose the variant
          assignments for each user. Unit types can be found and created in
          your ABsmartly Web Console settings. The payload takes the form of:

          ```json
          {
            "type": "user_id" // The name of the unit type
            "uid": "4a42766ca6313d26f49985e799ff4f3790fb86efa0fce46edb3ea8fbf1ea3408" // The value of the unit that you are tracking.
          }
          ```

          **Exposures**

          Exposures tell the collector information about which variant of an experiment was shown to the user, and when:

          ```json
          {
            "id": 3, // The ID of the exposed experiment.
            "name": "exp_banner_color", // The name of the exposed experiment.
            "unit": "user_id", // The unit that was used together with the experiment seed to generate the variant.
            "variant": 1, // The variant that was shown.
            "exposedAt": 1609244179528, // The time at which the exposure happened.
            "assigned": true, // Whether the user was exposed to the experiment in this specific request, it could be that the user was not assigned because it doesn’t match the audience, or the experiment is already fullOn, or the variant was overriden, etc.
            "eligible": true, // Whether the experiment is in the right part of the traffic allocation to this experiment and can be triggered.
            "overridden": false, // Whether the variant was overridden or not.
            "fullOn": false, // True if this experiment is fullOn and the winning variant is being forced to everyone.
            "custom": false, // Whether this variant was a custom assignment.
            "audienceMismatch": false // Whether this variant was shown outside of it’s specified target audience.
          }
          ```

          **Goals**

          Goals are used to track various metrics that are related to your
          experiment. Goals can be created and found in your ABsmartly Web
          Console settings:

          ```json
          {
            "name": "banner_click", // The name of the goal that you are tracking.
            "achievedAt": 1609254179528, // The time that the goal was achieved.
            "properties": {} // Any properties that you wish to pass along with this goal.
          }
          ```

          **Attributes**

          Attributes allow for segmentation of your data on the Web Console:

          ```json
          {
            "name": "age", // The name of the attribute.
            "value": 39, // The attribute's value.
            "setAt": 1609244179528 // The time at which the value was set.
          }
          ```

        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PublishRequest"
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PublishResponse"
        400:
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PublishResponse"
        401:
          description: Unauthorized
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /context/batch:
    put:
      tags:
        - context
        - batch
      summary: Publish Experiment Events for Multiple Contexts
      description: A PUT request for publishing your exposures, goals and attributes from multiple contexts.
      operationId: contextPublishBatch
      parameters:
        - name: X-Agent
          in: header
          required: true
          description: The User-Agent of your SDK.
          example: absmartly-Java-SDK v1.0.1
          schema:
            type: string
        - name: X-Environment
          in: header
          required: true
          description: The environment in which you are running your experiments. These can be found and created in your ABsmartly Web Console settings.
          example: development
          schema:
            type: string
        - name: X-Application
          in: header
          required: true
          description: The application in which you are running your experiments. These can be found and created in your ABsmartly Web Console settings.
          example: www
          schema:
            type: string
        - name: X-Application-Version
          in: header
          required: true
          description: The application version which you are running your experiments on.
          example: 0
          schema:
            type: integer
            format: int64
      requestBody:
        required: true
        description: |
          An array of data to publish.

          **Hashed**

          The hashed value describes whether your values have already been hashed, or if they are to be hashed by the Collector.

          **Historic**

          The historic value tells the Collector whether this is new or old data.

          **Published At**

          The publishedAt value is the time at which the request was made.

          **Units**

          Units are the values which are used to choose the variant
          assignments for each user. Unit types can be found and created in
          your ABsmartly Web Console settings. The payload takes the form of:

          ```json
          {
            "type": "user_id" // The name of the unit type
            "uid": "4a42766ca6313d26f49985e799ff4f3790fb86efa0fce46edb3ea8fbf1ea3408" // The value of the unit that you are tracking.
          }
          ```

          **Exposures**

          Exposures tell the collector information about which variant of an experiment was shown to the user, and when:

          ```json
          {
            "id": 3, // The ID of the exposed experiment.
            "name": "exp_banner_color", // The name of the exposed experiment.
            "unit": "user_id", // The unit that was used together with the experiment seed to generate the variant.
            "variant": 1, // The variant that was shown.
            "exposedAt": 1609244179528, // The time at which the exposure happened.
            "assigned": true, // Whether the user was exposed to the experiment in this specific request, it could be that the user was not assigned because it doesn’t match the audience, or the experiment is already fullOn, or the variant was overriden, etc.
            "eligible": true, // Whether the experiment is in the right part of the traffic allocation to this experiment and can be triggered.
            "overridden": false, // Whether the variant was overridden or not.
            "fullOn": false, // True if this experiment is fullOn and the winning variant is being forced to everyone.
            "custom": false, // Whether this variant was a custom assignment.
            "audienceMismatch": false // Whether this variant was shown outside of it’s specified target audience.
          }
          ```

          **Goals**

          Goals are used to track various metrics that are related to your
          experiment. Goals can be created and found in your ABsmartly Web
          Console settings:

          ```json
          {
            "name": "banner_click", // The name of the goal that you are tracking.
            "achievedAt": 1609254179528, // The time that the goal was achieved.
            "properties": {} // Any properties that you wish to pass along with this goal.
          }
          ```

          **Attributes**

          Attributes allow for segmentation of your data on the Web Console:

          ```json
          {
            "name": "age", // The name of the attribute.
            "value": 39, // The attribute's value.
            "setAt": 1609244179528 // The time at which the value was set.
          }
          ```

        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PublishBatchRequest"
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PublishResponse"
        400:
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PublishResponse"
        401:
          description: Unauthorized
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /experiment:
    get:
      tags:
        - experiment
      operationId: experimentGet
      summary: Get Experiment Data
      description: A GET request for obtaining data on all running experiments.
      parameters:
        - name: X-Agent
          in: header
          required: true
          description: The User-Agent of your SDK.
          example: absmartly-Java-SDK v1.0.1
          schema:
            type: string
        - name: X-Environment
          in: header
          required: true
          description: The environment in which you are running your experiments. These can be found and created in your ABsmartly Web Console settings.
          example: development
          schema:
            type: string
        - name: X-Application
          in: header
          required: true
          description: The application in which you are running your experiments. These can be found and created in your ABsmartly Web Console settings.
          example: www
          schema:
            type: string
        - name: X-Application-Version
          in: header
          required: true
          description: The application version which you are running your experiments on.
          example: 0
          schema:
            type: integer
            format: int64
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ExperimentsResponse"
        401:
          description: Unauthorized
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

components:
  schemas:
    ExperimentAssignment:
      type: object
      required:
        - id
        - iteration
        - name
        - variant
        - eligible
        - config
      properties:
        id:
          type: integer
          format: int32
          minimum: 0
          example: 3
        iteration:
          type: integer
          format: int32
          minimum: 0
          example: 2
        name:
          type: string
          example: exp_banner_color
        variant:
          type: integer
          format: int32
          minimum: 0
          maximum: 127
          example: 1
        eligible:
          type: boolean
          example: true
        audienceMismatch:
          type: boolean
          example: false
        originalVariant:
          type: integer
          format: int32
          minimum: 0
          maximum: 127
          example: 1
        config:
          type: string
          nullable: true
    Unit:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          example: user_id
        uid:
          type: string
          minLength: 1
          maxLength: 640
          example: 4a42766ca6313d26f49985e799ff4f3790fb86efa0fce46edb3ea8fbf1ea3408
    Exposure:
      type: object
      description: Hello world
      required:
        - id
        - name
        - variant
        - exposedAt
        - assigned
        - eligible
      properties:
        id:
          type: integer
          format: int32
          minimum: 0
          example: 3
        name:
          type: string
          example: exp_banner_color
        unit:
          type: string
          nullable: true
          example: user_id
        variant:
          type: integer
          format: int32
          minimum: 0
          maximum: 128
          example: 1
        exposedAt:
          type: integer
          format: int64
          example: 1609244179528
        assigned:
          type: boolean
          example: true
        eligible:
          type: boolean
          example: true
        overridden:
          type: boolean
          example: false
        fullOn:
          type: boolean
          example: false
        custom:
          type: boolean
          example: false
        audienceMismatch:
          type: boolean
          example: false
    GoalAchievement:
      type: object
      required:
        - name
        - achievedAt
      properties:
        name:
          type: string
          example: banner_click
        achievedAt:
          type: integer
          format: int64
          example: 1609254179528
        properties:
          type: object
          nullable: true
    Attribute:
      type: object
      required:
        - name
        - setAt
      properties:
        name:
          type: string
          example: age
        value:
          example: 39
          nullable: true
        setAt:
          type: integer
          format: int64
          example: 1609244179528
    Experiment:
      type: object
      required:
        - id
        - name
        - iteration
        - split
        - trafficSplit
        - variants
      properties:
        id:
          type: integer
          example: 123
        name:
          type: string
          example: exp_banner_color
        iteration:
          type: integer
          example: 0
        split:
          type: array
          items:
            type: number
            format: double
          example: [0.5, 0.5]
        trafficSplit:
          type: array
          items:
            type: number
            format: double
          example: [0.0, 1.0]
        variants:
          type: array
          items:
            $ref: "#/components/schemas/ExperimentVariant"
    ExperimentVariant:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          example: treatment
        config:
          type: string
          nullable: true
          example: '{"color":"red"}'
    ContextRequest:
      type: object
      required:
        - units
      properties:
        units:
          type: array
          items:
            $ref: "#/components/schemas/Unit"
    ContextResponse:
      type: object
      required:
        - units
        - assignments
      properties:
        units:
          type: array
          items:
            $ref: "#/components/schemas/Unit"
        assignments:
          type: array
          items:
            $ref: "#/components/schemas/ExperimentAssignment"
    ContextGetResponse:
      type: object
      required:
        - experiments
      properties:
        experiments:
          type: array
          items:
            $ref: "#/components/schemas/ContextExperiment"
    ContextExperiment:
      type: object
      required:
        - id
        - name
        - iteration
        - unitType
        - environment
        - seed
        - split
        - trafficSeed
        - trafficSplit
        - fullOnVariant
        - applications
        - variants
        - audience
        - audienceStrict
      properties:
        id:
          type: integer
          example: 123
        name:
          type: string
          example: exp_banner_color
        iteration:
          type: integer
          example: 0
        unitType:
          type: string
          example: user_id
        environment:
          type: string
          example: production
        seed:
          type: integer
          format: int64
          example: 9453674179528
        split:
          type: array
          items:
            type: number
            format: double
          example: [0.5, 0.5]
        trafficSeed:
          type: integer
          format: int64
          example: -56241591889905
        trafficSplit:
          type: array
          items:
            type: number
            format: double
          example: [0.0, 1.0]
        fullOnVariant:
          type: integer
          format: int32
          minimum: 0
          maximum: 127
          example: 1
        applications:
          type: array
          items:
            $ref: "#/components/schemas/ExperimentApplication"
        variants:
          type: array
          items:
            $ref: "#/components/schemas/ExperimentVariant"
        audience:
          type: string
          example: '{ "filter": [{ "gt": [{ "var": "age" }, { "value": 20 }] }] }'
        audienceStrict:
          type: boolean
          example: false
    ExperimentApplication:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          example: website
    PublishRequest:
      type: object
      required:
        - units
        - publishedAt
      properties:
        hashed:
          type: boolean
          nullable: true
          default: false
        historic:
          type: boolean
          nullable: true
          default: false
        publishedAt:
          type: integer
          format: int64
          example: 1609244179528
        units:
          type: array
          items:
            $ref: "#/components/schemas/Unit"
        exposures:
          type: array
          items:
            $ref: "#/components/schemas/Exposure"
        goals:
          type: array
          items:
            $ref: "#/components/schemas/GoalAchievement"
        attributes:
          type: array
          items:
            $ref: "#/components/schemas/Attribute"
    PublishResponseMessage:
      type: object
      required:
        - batchIndex
        - eventIndex
        - subject
        - message
      properties:
        batchIndex:
          type: integer
        eventIndex:
          type: integer
        subject:
          type: string
        message:
          type: string
    PublishResponse:
      type: object
      required:
        - ok
      properties:
        ok:
          type: boolean
        warnings:
          type: array
          items:
            $ref: "#/components/schemas/PublishResponseMessage"
        errors:
          type: array
          items:
            $ref: "#/components/schemas/PublishResponseMessage"
    PublishBatchRequest:
      type: object
      required:
        - requests
      properties:
        requests:
          type: array
          minItems: 1
          maxItems: 500
          items:
            $ref: "#/components/schemas/PublishRequest"
    ExperimentsResponse:
      type: object
      required:
        - ok
        - experiments
      properties:
        experiments:
          type: array
          items:
            $ref: "#/components/schemas/Experiment"
    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: integer
          format: int64
        message:
          type: string
  securitySchemes:
    ApiKey:
      type: apiKey
      name: X-API-Key
      in: header
      required: true