index.yaml

---
swagger: "2.0"
info:
  description: >
    Flagr is a feature flagging, A/B testing and dynamic configuration microservice.
    The base path for all the APIs is "/api/v1".
  title: Flagr
  version: 1.1.17
tags:
  - name: flag
    description: Everything about the flag
  - name: segment
    description: Segment defines the audience of the flag, it's the user segmentation
  - name: constraint
    description: Constraint is the unit of defining a small subset of users
  - name: distribution
    description: Distribution is the percent distribution of variants within that segment
  - name: variant
    description: Variants are the possible outcomes of flag evaluation
  - name: evaluation
    description: Evaluation is the process of evaluating a flag given the entity context
  - name: health
    description: Check if Flagr is healthy
x-tagGroups:
  - name: Flag Management
    tags:
      - flag
      - segment
      - constraint
      - distribution
      - variant
      - tag
  - name: Flag Evaluation
    tags:
      - evaluation
  - name: Health Check
    tags:
      - health
  - name: Export
    tags:
      - export
consumes:
- application/json
produces:
- application/json
schemes:
- http
basePath: "/api/v1"
paths:
  /flags:
    $ref: ./flags.yaml
  /flags/{flagID}:
    $ref: ./flag.yaml
  /flags/{flagID}/restore:
    $ref: ./flag_restore.yaml
  /flags/{flagID}/enabled:
    $ref: ./flag_enabled.yaml
  /flags/{flagID}/tags:
    $ref: ./flag_tags.yaml
  /flags/{flagID}/tags/{tagID}:
    $ref: ./flag_tag.yaml
  /flags/{flagID}/variants:
    $ref: ./flag_variants.yaml
  /flags/{flagID}/variants/{variantID}:
    $ref: ./flag_variant.yaml
  /flags/{flagID}/segments:
    $ref: ./flag_segments.yaml
  /flags/{flagID}/segments/reorder:
    $ref: ./flag_segments_reorder.yaml
  /flags/{flagID}/segments/{segmentID}:
    $ref: ./flag_segment.yaml
  /flags/{flagID}/segments/{segmentID}/constraints:
    $ref: ./flag_segment_constraints.yaml
  /flags/{flagID}/segments/{segmentID}/constraints/{constraintID}:
    $ref: ./flag_segment_constraint.yaml
  /flags/{flagID}/segments/{segmentID}/distributions:
    $ref: ./flag_segment_distributions.yaml
  /flags/{flagID}/snapshots:
    $ref: ./flag_snapshots.yaml
  /flags/entity_types:
    $ref: ./flag_entity_types.yaml
  /tags:
    $ref: ./tags.yaml
  /evaluation:
    $ref: ./evaluation.yaml
  /evaluation/batch:
    $ref: ./evaluation_batch.yaml
  /health:
    $ref: ./health.yaml
  /export/sqlite:
    $ref: ./export_sqlite.yaml
  /export/eval_cache/json:
    $ref: ./export_eval_cache_json.yaml


definitions:

  # Flag
  flag:
    type: object
    required:
      - description
      - enabled
      - dataRecordsEnabled
    properties:
      id:
        type: integer
        format: int64
        minimum: 1
        readOnly: true
      key:
        description: unique key representation of the flag
        type: string
        minLength: 1
      description:
        type: string
        minLength: 1
      enabled:
        type: boolean
      tags:
        type: array
        items:
          $ref: "#/definitions/tag"
      segments:
        type: array
        items:
          $ref: "#/definitions/segment"
      variants:
        type: array
        items:
          $ref: "#/definitions/variant"
      dataRecordsEnabled:
        description: enabled data records will get data logging in the metrics pipeline, for example, kafka.
        type: boolean
      entityType:
        description: it will override the entityType in the evaluation logs if it's not empty
        type: string
      notes:
        description: flag usage details in markdown format
        type: string
      createdBy:
        type: string
      updatedBy:
        type: string
      updatedAt:
        type: string
        format: date-time
  createFlagRequest:
    type: object
    required:
      - description
    properties:
      description:
        type: string
        minLength: 1
      key:
        description: unique key representation of the flag
        type: string
      template:
        description: template for flag creation
        type: string
  putFlagRequest:
    type: object
    properties:
      description:
        type: string
        minLength: 1
        x-nullable: true
      dataRecordsEnabled:
        type: boolean
        description: enabled data records will get data logging in the metrics pipeline, for example, kafka.
        x-nullable: true
      entityType:
        description: it will overwrite entityType into evaluation logs if it's not empty
        type: string
        x-nullable: true
      enabled:
        type: boolean
        x-nullable: true
      key:
        type: string
        x-nullable: true
      notes:
        type: string
        x-nullable: true
  setFlagEnabledRequest:
    type: object
    required:
      - enabled
    properties:
      enabled:
        type: boolean

  # Flag Snapshot
  flagSnapshot:
    type: object
    required:
      - id
      - flag
      - updatedAt
    properties:
      id:
        type: integer
        format: int64
        minimum: 1
        readOnly: true
      updatedBy:
        type: string
      flag:
        $ref: "#/definitions/flag"
      updatedAt:
        type: string
        minLength: 1

  # Tag
  tag:
    type: object
    required:
      - value
    properties:
      id:
        type: integer
        format: int64
        minimum: 1
        readOnly: true
      value:
        type: string
        minLength: 1
  createTagRequest:
    type: object
    required:
      - value
    properties:
      value:
        type: string
        minLength: 1

  # Segment
  segment:
    type: object
    required:
      - description
      - rank
      - rolloutPercent
    properties:
      id:
        type: integer
        format: int64
        minimum: 1
        readOnly: true
      description:
        type: string
        minLength: 1
      constraints:
        type: array
        items:
          $ref: "#/definitions/constraint"
      distributions:
        type: array
        items:
          $ref: "#/definitions/distribution"
      rank:
        type: integer
        format: int64
        minimum: 0
      rolloutPercent:
        type: integer
        format: int64
        minimum: 0
        maximum: 100
  createSegmentRequest:
    type: object
    required:
      - description
      - rolloutPercent
    properties:
      description:
        type: string
        minLength: 1
      rolloutPercent:
        type: integer
        format: int64
        minimum: 0
        maximum: 100
  putSegmentRequest:
    type: object
    required:
      - description
      - rolloutPercent
    properties:
      description:
        type: string
        minLength: 1
      rolloutPercent:
        type: integer
        format: int64
        minimum: 0
        maximum: 100
  putSegmentReorderRequest:
    type: object
    required:
      - segmentIDs
    properties:
      segmentIDs:
        type: array
        minItems: 1
        items:
          type: integer
          format: int64
          minimum: 1

  # Variant
  variant:
    type: object
    required:
      - key
    properties:
      id:
        type: integer
        format: int64
        minimum: 1
        readOnly: true
      key:
        type: string
        minLength: 1
      attachment:
        type: object
  createVariantRequest:
    type: object
    required:
      - key
    properties:
      key:
        type: string
        minLength: 1
      attachment:
        type: object
  putVariantRequest:
    type: object
    required:
      - key
    properties:
      key:
        type: string
        minLength: 1
      attachment:
        type: object

  # Constraint
  constraint:
    type: object
    required:
      - property
      - operator
      - value
    properties:
      id:
        type: integer
        format: int64
        minimum: 1
        readOnly: true
      property:
        type: string
        minLength: 1
      operator:
        type: string
        minLength: 1
        enum:
          - "EQ"
          - "NEQ"
          - "LT"
          - "LTE"
          - "GT"
          - "GTE"
          - "EREG"
          - "NEREG"
          - "IN"
          - "NOTIN"
          - "CONTAINS"
          - "NOTCONTAINS"
      value:
        type: string
        minLength: 1
  createConstraintRequest:
    type: object
    required:
      - property
      - operator
      - value
    properties:
      property:
        type: string
        minLength: 1
      operator:
        type: string
        minLength: 1
      value:
        type: string
        minLength: 1

  # Distribution
  distribution:
    type: object
    required:
      - percent
      - variantID
      - variantKey
    properties:
      id:
        type: integer
        format: int64
        minimum: 1
        readOnly: true
      percent:
        type: integer
        format: int64
        minimum: 0
        maximum: 100
      variantKey:
        type: string
        minLength: 1
      variantID:
        type: integer
        format: int64
        minimum: 1
  putDistributionsRequest:
    type: object
    required:
      - distributions
    properties:
      distributions:
        type: array
        items:
          $ref: "#/definitions/distribution"

  # Evaluation
  evalContext:
    type: object
    properties:
      entityID:
        type: string
        description: entityID is used to deterministically at random to evaluate the flag result. If it's empty, flagr will randomly generate one.
      entityType:
        type: string
      entityContext:
        type: object
      enableDebug:
        type: boolean
      flagID:
        description: flagID
        type: integer
        format: int64
        minimum: 1
      flagKey:
        description: flagKey. flagID or flagKey will resolve to the same flag. Either works.
        type: string
      flagTags:
        description: flagTags. flagTags looks up flags by tag. Either works.
        type: array
        x-omitempty: true
        items:
          type: string
      flagTagsOperator:
        description: >-
          determine how flagTags is used to filter flags to be evaluated. OR extends the evaluation to those which
          contains at least one of the provided flagTags or AND limit the evaluation to those which contains all the
          flagTags.
        type: string
        enum:
          - "ANY"
          - "ALL"
        default: "ANY"
  evalResult:
    type: object
    properties:
      flagID:
        type: integer
        format: int64
      flagKey:
        type: string
      flagSnapshotID:
        type: integer
        format: int64
      segmentID:
        type: integer
        format: int64
      variantID:
        type: integer
        format: int64
      variantKey:
        type: string
      variantAttachment:
        type: object
      evalContext:
        $ref: "#/definitions/evalContext"
      timestamp:
        type: string
      evalDebugLog:
        $ref: "#/definitions/evalDebugLog"
  evalDebugLog:
    type: object
    properties:
      segmentDebugLogs:
        type: array
        items:
          $ref: "#/definitions/segmentDebugLog"
      msg:
        type: string
  segmentDebugLog:
    type: object
    properties:
      segmentID:
        type: integer
        format: int64
        minimum: 1
      msg:
        type: string

  # Evaluation Batch
  evaluationEntity:
    type: object
    properties:
      entityID:
        type: string
      entityType:
        type: string
      entityContext:
        type: object
  evaluationBatchRequest:
    type: object
    required:
      - entities
    properties:
      entities:
        type: array
        items:
          $ref: "#/definitions/evaluationEntity"
        minItems: 1
      enableDebug:
        type: boolean
      flagIDs:
        description: flagIDs
        type: array
        items:
          type: integer
          format: int64
          minimum: 1
        minItems: 1
      flagKeys:
        description: flagKeys. Either flagIDs, flagKeys or flagTags works. If pass in multiples, Flagr may return duplicate results.
        type: array
        items:
          type: string
          minLength: 1
        minItems: 1
      flagTags:
        description: flagTags. Either flagIDs, flagKeys or flagTags works. If pass in multiples, Flagr may return duplicate results.
        type: array
        items:
          type: string
          minLength: 1
        minItems: 1
      flagTagsOperator:
        description: >-
          determine how flagTags is used to filter flags to be evaluated. OR extends the evaluation to those which
          contains at least one of the provided flagTags or AND limit the evaluation to those which contains all the
          flagTags.
        type: string
        enum:
          - "ANY"
          - "ALL"
        default: "ANY"
  evaluationBatchResponse:
    type: object
    required:
      - evaluationResults
    properties:
      evaluationResults:
        type: array
        items:
          $ref: "#/definitions/evalResult"

  # Health check
  health:
    type: object
    properties:
      status:
        type: string

  # Default Error
  error:
    type: object
    required:
      - message
    properties:
      message:
        type: string
        minLength: 1