api.yaml

openapi: 3.0.0
info:
  title: Harness feature flag service client apis
  version: 1.0.0
  contact:
    name: Feature Flag - developers
    url: 'https://www.harness.io'
    email: cf@harness.io
servers:
  - url: /api/1.0
    description: no host specified
  - url: 'http://localhost:3000/api/1.0'
    description: CfClient description
tags:
  - name: client
  - name: metrics
paths:
  '/client/env/{environmentUUID}/feature-configs':
    get:
      summary: Get all feature flags activations
      description: All feature flags with activations in project environment
      operationId: GetFeatureConfig
      tags:
        - client
      parameters:
        - name: environmentUUID
          in: path
          required: true
          description: Unique identifier for the environment object in the API.
          schema:
            type: string
        - $ref: '#/components/parameters/clusterQueryOptionalParam'
      security:
        - BearerAuth: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/FeatureConfig'
  '/client/env/{environmentUUID}/feature-configs/{identifier}':
    get:
      summary: Get feature config
      operationId: GetFeatureConfigByIdentifier
      tags:
        - client
      parameters:
        - name: identifier
          in: path
          required: true
          description: Unique identifier for the flag object in the API.
          schema:
            type: string
        - name: environmentUUID
          in: path
          required: true
          description: Unique identifier for the environment object in the API.
          schema:
            type: string
        - $ref: '#/components/parameters/clusterQueryOptionalParam'
      security:
        - BearerAuth: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeatureConfig'
  '/client/env/{environmentUUID}/target-segments':
    get:
      summary: Retrieve all segments.
      description: Used to retrieve all segments for certain account id.
      operationId: GetAllSegments
      tags:
        - client
      parameters:
        - name: environmentUUID
          in: path
          required: true
          description: Unique identifier for the environment object in the API.
          schema:
            type: string
        - $ref: '#/components/parameters/clusterQueryOptionalParam'
      security:
        - BearerAuth: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Segment'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '403':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  '/client/env/{environmentUUID}/target-segments/{identifier}':
    get:
      summary: Retrieve a segment by identifier
      description: Used to retrieve a segment for a certain account id by identifier
      operationId: GetSegmentByIdentifier
      tags:
        - client
      parameters:
        - name: identifier
          in: path
          required: true
          description: Unique identifier for the segment object in the API
          schema:
            type: string
        - name: environmentUUID
          in: path
          required: true
          description: Unique identifier for the environment object in the API
          schema:
            type: string
        - $ref: '#/components/parameters/clusterQueryOptionalParam'
      security:
        - BearerAuth: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Segment'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '403':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /client/auth:
    post:
      summary: Authenticate with the admin server.
      description: Used to retrieve all target segments for certain account id.
      operationId: Authenticate
      tags:
        - client
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthenticationRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationResponse'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '403':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  '/client/env/{environmentUUID}/target/{target}/evaluations':
    get:
      summary: Get feature evaluations for target
      operationId: GetEvaluations
      tags:
        - client
      parameters:
        - name: environmentUUID
          in: path
          required: true
          description: Unique identifier for the environment object in the API.
          schema:
            type: string
        - name: target
          in: path
          required: true
          description: Unique identifier for the target object in the API.
          schema:
            type: string
        - $ref: '#/components/parameters/clusterQueryOptionalParam'
      security:
        - BearerAuth: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Evaluations'
  '/client/env/{environmentUUID}/target/{target}/evaluations/{feature}':
    get:
      summary: Get feature evaluations for target
      operationId: GetEvaluationByIdentifier
      tags:
        - client
      parameters:
        - name: environmentUUID
          in: path
          required: true
          description: Unique identifier for the environment object in the API.
          schema:
            type: string
        - name: feature
          in: path
          required: true
          description: Unique identifier for the flag object in the API.
          schema:
            type: string
        - name: target
          in: path
          required: true
          description: Unique identifier for the target object in the API.
          schema:
            type: string
        - $ref: '#/components/parameters/clusterQueryOptionalParam'
      security:
        - BearerAuth: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Evaluation'
  '/metrics/{environment}':
    post:
      tags:
        - metrics
      summary: Send metrics to the Analytics server.
      description: Send metrics to Analytics server
      operationId: postMetrics
      parameters:
        - $ref: '#/components/parameters/environmentPathParam'
        - $ref: '#/components/parameters/clusterQueryOptionalParam'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Metrics'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      responses:
        '200':
          description: OK
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '403':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /stream:
    get:
      summary: Stream endpoint.
      operationId: Stream
      tags:
        - client
      parameters:
        - in: header
          name: API-Key
          schema:
            type: string
          required: true
        - $ref: '#/components/parameters/clusterQueryOptionalParam'
      security:
        - BearerAuth: []
      responses:
        '200':
          description: OK
          headers:
            Content-Type:
              schema:
                type: string
                default: text/event-stream
            Cache-Control:
              schema:
                type: string
                default: no-cache
            Connection:
              schema:
                type: string
                default: keep-alive
            Access-Control-Allow-Origin:
              schema:
                type: string
                default: '*'
        '503':
          description: Service Unavailable
components:
  schemas:
    FeatureState:
      type: string
      description: The state of a flag either off or on
      enum:
        - 'on'
        - 'off'
    Variation:
      type: object
      description: A variation of a flag that can be returned to a target
      properties:
        identifier:
          type: string
          description: The unique identifier for the variation
          example: off-variation
        value:
          type: string
          description: >-
            The variation value to serve such as true or false for a boolean
            flag
          example: true
        name:
          type: string
          description: The user friendly name of the variation
          example: Off VAriation
        description:
          type: string
          description: A description of the variation
      required:
        - identifier
        - value
    Clause:
      type: object
      description: A clause describes what conditions are used to evaluate a flag
      properties:
        id:
          type: string
          description: The unique ID for the clause
          example: 32434243
        attribute:
          type: string
          description: >-
            The attribute to use in the clause.  This can be any target
            attribute
          example: identifier
        op:
          type: string
          description: 'The type of operation such as equals, starts_with, contains'
          example: starts_with
        values:
          type: array
          description: The values that are compared against the operator
          items:
            type: string
        negate:
          type: boolean
          description: Is the operation negated?
          example: false
      required:
        - attribute
        - op
        - negate
        - values
    WeightedVariation:
      type: object
      description: >-
        A variation and the weighting it should receive as part of a percentage
        rollout
      properties:
        variation:
          type: string
          description: The variation identifier
          example: off-variation
        weight:
          type: integer
          description: The weight to be given to the variation in percent
          example: 50
      required:
        - variation
        - weight
    Distribution:
      type: object
      description: Describes a distribution rule
      properties:
        bucketBy:
          type: string
          description: The attribute to use when distributing targets across buckets
        variations:
          type: array
          description: A list of variations and the weight that should be given to each
          items:
            $ref: '#/components/schemas/WeightedVariation'
      required:
        - bucketBy
        - variations
    Serve:
      type: object
      description: >-
        Describe the distribution rule and the variation that should be served
        to the target
      properties:
        distribution:
          $ref: '#/components/schemas/Distribution'
        variation:
          type: string
    ServingRule:
      type: object
      description: The rule used to determine what variation to serve to a target
      properties:
        ruleId:
          type: string
          description: The unique identifier for this rule
        priority:
          type: integer
          description: >-
            The rules priority relative to other rules.  The rules are evaluated
            in order with 1 being the highest
          example: 1
        clauses:
          type: array
          description: A list of clauses to use in the rule
          items:
            $ref: '#/components/schemas/Clause'
        serve:
          $ref: '#/components/schemas/Serve'
      required:
        - priority
        - clauses
        - serve
    Prerequisite:
      type: object
      description: Feature Flag pre-requisites
      properties:
        feature:
          type: string
          description: The feature identifier that is the prerequisite
        variations:
          type: array
          description: A list of variations that must be met
          items:
            type: string
      required:
        - feature
        - variations
    TargetMap:
      type: object
      description: Target map provides the details of a target that belongs to a flag
      properties:
        identifier:
          type: string
          description: The identifier for the target
        name:
          type: string
          description: The name of the target
      required:
        - identifier
        - name
    VariationMap:
      type: object
      description: >-
        A mapping of variations to targets and target groups (segments).  The
        targets listed here should receive this variation.
      properties:
        variation:
          type: string
          description: The variation identifier
          example: off-variation
        targets:
          type: array
          description: A list of target mappings
          items:
            $ref: '#/components/schemas/TargetMap'
        targetSegments:
          type: array
          description: A list of target groups (segments)
          items:
            type: string
      required:
        - variation
    FeatureConfig:
      type: object
      properties:
        project:
          type: string
        environment:
          type: string
        feature:
          type: string
        state:
          $ref: '#/components/schemas/FeatureState'
        kind:
          type: string
          enum:
            - boolean
            - int
            - string
            - json
        variations:
          type: array
          items:
            $ref: '#/components/schemas/Variation'
          minItems: 2
        rules:
          type: array
          items:
            $ref: '#/components/schemas/ServingRule'
        defaultServe:
          $ref: '#/components/schemas/Serve'
        offVariation:
          type: string
        prerequisites:
          type: array
          items:
            $ref: '#/components/schemas/Prerequisite'
        variationToTargetMap:
          type: array
          items:
            $ref: '#/components/schemas/VariationMap'
        version:
          type: integer
          format: int64
      required:
        - project
        - environment
        - feature
        - state
        - kind
        - variations
        - defaultTarget
        - offVariation
        - defaultServe
    Tag:
      type: object
      description: A tag has a name and value
      properties:
        name:
          type: string
          description: The name of the tag
        value:
          type: string
          description: The value of the tag
      required:
        - name
    Segment:
      type: object
      description: A Target Group (Segment) response
      properties:
        identifier:
          type: string
          description: Unique identifier for the target group.
        name:
          type: string
          description: Name of the target group.
          example: Beta Testers
        environment:
          type: string
          description: The environment this target group belongs to
          example: Production
        tags:
          type: array
          description: Tags for this target group
          items:
            $ref: '#/components/schemas/Tag'
        included:
          type: array
          description: A list of Targets who belong to this target group
          items:
            $ref: '#/components/schemas/Target'
        excluded:
          type: array
          description: A list of Targets who are excluded from this target group
          items:
            $ref: '#/components/schemas/Target'
        rules:
          type: array
          items:
            $ref: '#/components/schemas/Clause'
          description: >-
            An array of rules that can cause a user to be included in this
            segment.
        createdAt:
          type: integer
          description: The data and time in milliseconds when the group was created
          format: int64
        modifiedAt:
          type: integer
          description: The data and time in milliseconds when the group was last modified
          format: int64
        version:
          type: integer
          description: >-
            The version of this group.  Each time it is modified the version is
            incremented
          example: 1
          format: int64
      required:
        - identifier
        - name
    Target:
      type: object
      description: A Target object
      properties:
        identifier:
          type: string
          description: The unique identifier for this target
          example: john-doe
        account:
          type: string
          description: The account ID that the target belongs to
          example: abcXDdffdaffd
        org:
          type: string
          description: The identifier for the organization that the target belongs to
        environment:
          type: string
          description: The identifier for the environment that the target belongs to
        project:
          type: string
          description: The identifier for the project that this target belongs to
        name:
          type: string
          description: The name of this Target
          example: John Doe
        anonymous:
          type: boolean
          description: Indicates if this target is anonymous
        attributes:
          type: object
          description: a JSON representation of the attributes for this target
          example:
            age: 20
            location: Belfast
        createdAt:
          type: integer
          description: The date and time in milliseconds when this Target was created
          format: int64
        segments:
          type: array
          description: A list of Target Groups (Segments) that this Target belongs to
          items:
            $ref: '#/components/schemas/Segment'
      required:
        - identifier
        - name
        - environment
        - project
        - account
        - org
    Error:
      type: object
      properties:
        code:
          type: string
          description: The http error code
          example: 404
        message:
          type: string
          description: The reason the request failed
          example: 'Error retrieving projects, organization ''default_org'' does not exist'
        details:
          type: object
          description: Additional details about the error
      required:
        - code
        - message
    AuthenticationRequest:
      type: object
      properties:
        apiKey:
          type: string
          example: 896045f3-42ee-4e73-9154-086644768b96
        target:
          type: object
          properties:
            identifier:
              type: string
            name:
              type: string
            anonymous:
              type: boolean
            attributes:
              type: object
          required:
            - identifier
      required:
        - apiKey
    AuthenticationResponse:
      type: object
      properties:
        authToken:
          type: string
      required:
        - authToken
    Pagination:
      type: object
      properties:
        version:
          type: integer
          description: >-
            The version of this object.  The version will be incremented each
            time the object is modified
          example: 5
        pageCount:
          type: integer
          description: The total number of pages
          example: 100
        itemCount:
          type: integer
          description: The total number of items
          example: 1
        pageSize:
          type: integer
          description: The number of items per page
          example: 1
        pageIndex:
          type: integer
          description: The current page
          example: 0
      required:
        - pageCount
        - itemCount
        - pageSize
        - pageIndex
    Evaluation:
      type: object
      properties:
        flag:
          type: string
        value:
          type: string
        kind:
          type: string
        identifier:
          type: string
      required:
        - flag
        - value
        - kind
    Evaluations:
      type: array
      items:
        $ref: '#/components/schemas/Evaluation'
    KeyValue:
      type: object
      properties:
        key:
          type: string
        value:
          type: string
      required:
        - key
        - value
    TargetData:
      type: object
      properties:
        identifier:
          type: string
        name:
          type: string
        attributes:
          type: array
          items:
            $ref: '#/components/schemas/KeyValue'
      required:
        - name
        - identifier
        - attributes
    MetricsData:
      type: object
      properties:
        timestamp:
          type: integer
          format: int64
          example: 1608175465
          description: time at when this data was recorded
        count:
          type: integer
        metricsType:
          type: string
          enum:
            - FFMETRICS
          description: This can be of type FeatureMetrics
        attributes:
          type: array
          items:
            $ref: '#/components/schemas/KeyValue'
      required:
        - attributes
        - count
        - timestamp
        - metricsType
    Metrics:
      type: object
      properties:
        targetData:
          type: array
          items:
            $ref: '#/components/schemas/TargetData'
        metricsData:
          type: array
          items:
            $ref: '#/components/schemas/MetricsData'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: api-key
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  parameters:
    clusterQueryOptionalParam:
      name: cluster
      in: query
      required: false
      description: Unique identifier for the cluster for the account
      schema:
        type: string
    environmentPathParam:
      name: environment
      in: path
      required: true
      description: environment parameter in query.
      schema:
        type: string
  responses:
    Unauthenticated:
      description: Unauthenticated
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The specified resource was not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'