openapi: 3.1.0
servers:
  - url: /
info:
  version: 0.2.0
  title: OpenFeature Remote Evaluation Protocol (OFREP)
  description: |
    ---
    The **OpenFeature Remote Evaluation Protocol (OFREP)** is an API specification for feature flagging 
    that enables vendor-agnostic communication between applications and flag management systems. 

    OFREP defines a standard API layer between OpenFeature providers and flag management systems, 
    allowing any flag management system to implement the protocol and be compatible with 
    community-maintained providers.

    For more information, see the [OFREP documentation](https://openfeature.dev/docs/reference/other-technologies/ofrep/).

  contact:
    url: https://github.com/open-feature/protocol
  license:
    identifier: Apache-2.0
    name: Apache 2.0
security:
  - ApiKeyAuth: []
  - BearerAuth: []
tags:
  - name: OFREP Core
    description: |
      **Required**: Core APIs to implement to support OFREP.  
      *This is the minimum set of APIs required for a flag management system to be OFREP compatible.*

paths:
  /ofrep/v1/evaluate/flags/{key}:
    post:
      tags: [OFREP Core]
      summary: Evaluate A Single Feature Flag
      description: |
        Evaluates a single feature flag by its key. This endpoint is used by **server-side providers** 
        for dynamic context evaluation, where each evaluation request includes the evaluation context.

        The endpoint returns the evaluated flag value along with metadata including the evaluation 
        reason, variant, and any flag-specific metadata. The flag value can be one of several types: 
        boolean, string, integer, float, object, or a code default (indicating the provider should 
        use the code default value).

        **Use Case**: Server-side applications where evaluation context may change between requests 
        and real-time targeting decisions are required.
      operationId: evaluateFlag
      parameters:
        - name: key
          in: path
          required: true
          description: The unique identifier (key) of the feature flag
          schema:
            type: string
          example: discount-banner
      requestBody:
        required: true
        description: Evaluation request containing the context for flag evaluation
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/evaluationRequest"
            example:
              context:
                targetingKey: user-123
                email: user@example.com
                custom-plan: premium
                country: CA
      responses:
        "200":
          description: Successful flag evaluation. Returns the evaluated flag value with metadata.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/serverEvaluationSuccess"
              example:
                key: discount-banner
                value: true
                reason: TARGETING_MATCH
                variant: enabled
        "400":
          description: Bad evaluation request. The request is malformed or contains invalid context.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/evaluationFailure"
              example:
                key: my-flag
                errorCode: INVALID_CONTEXT
                errorDetails: "Context is missing required targetingKey property"
        "404":
          description: Flag not found. The specified flag key does not exist in the flag management system.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/flagNotFound"
              example:
                key: non-existent-flag
                errorCode: FLAG_NOT_FOUND
                errorDetails: "Flag 'non-existent-flag' was not found"
        "401":
          description: Unauthorized. Authentication credentials are missing, invalid, or expired.
        "403":
          description: Forbidden. The client does not have permission to access the requested resource.
        "429":
          description: Too Many Requests. Rate limit has been exceeded.
          headers:
            Retry-After:
              description: |
                Indicates when to retry the request again. Can be either a date-time string 
                or a number of seconds to wait.
              schema:
                type: string
                format: date-time
                example: "2024-02-07T12:00:00Z"
        "500":
          description: Internal Server Error. An unexpected error occurred on the server that prevented flag evaluation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/generalErrorResponse"
              example:
                errorDetails: "An internal server error occurred while processing the request"
  /ofrep/v1/evaluate/flags:
    post:
      tags: [OFREP Core]
      summary: Bulk Evaluate All Feature Flags
      description: |
        Evaluates all feature flags in a single request using a static context. This endpoint is 
        used by **client-side providers** for static context evaluation, where all flags are evaluated 
        once and then cached locally for subsequent use.

        The endpoint returns an array of all flag evaluations, where each flag can be either a 
        successful evaluation or an evaluation failure. The response includes an ETag header for 
        cache validation, allowing clients to use the `If-None-Match` header to avoid unnecessary 
        re-evaluation when flags haven't changed.
      operationId: evaluateFlagsBulk
      parameters:
        - in: header
          name: If-None-Match
          description: |
            Optional ETag value from a previous bulk evaluation response. If provided and the 
            ETag matches the current flag set, the server will return a 304 Not Modified response, 
            indicating that flags haven't changed since the last evaluation.
          schema:
            type: string
          required: false
          example: '"abc123xyz"'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/bulkEvaluationRequest"
            example:
              context:
                targetingKey: user-456
                email: user@example.com
                plan: free
                country: CA
      responses:
        "200":
          description: Successful bulk evaluation.
          headers:
            ETag:
              schema:
                type: string
              description: |
                Entity tag (ETag) representing the current state of all flags. Clients should 
                include this value in subsequent requests using the `If-None-Match` header for 
                cache validation.
              example: '"abc123xyz"'
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/bulkEvaluationSuccess"
              example:
                flags:
                  - key: discount-banner
                    value: true
                    reason: TARGETING_MATCH
                    variant: enabled
                  - key: theme-color
                    value: "blue"
                    reason: STATIC
                    variant: default
                  - key: non-existent-flag
                    errorCode: FLAG_NOT_FOUND
                    errorDetails: "Flag 'non-existent-flag' was not found"
                metadata:
                  version: v12
        "304":
          description: |
            Not Modified. The flags haven't changed since the last evaluation (ETag matches). No response body is returned.
        "400":
          description: Bad evaluation request. The request is malformed or contains invalid context.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/bulkEvaluationFailure"
              example:
                errorCode: INVALID_CONTEXT
                errorDetails: "Context is missing required targetingKey property"
        "401":
          description: Unauthorized. Authentication credentials are missing, invalid, or expired.
        "403":
          description: Forbidden. The client does not have permission to access the requested resource.
        "429":
          description: Too Many Requests. Rate limit has been exceeded.
          headers:
            Retry-After:
              description: |
                Indicates when to retry the request again. Can be either a date-time string 
                or a number of seconds to wait.
              schema:
                oneOf:
                  - type: string
                    format: date-time
                  - type: integer
                    description: Number of seconds to wait before retrying
              example: "2024-02-07T12:00:00Z"
        "500":
          description: Internal server error. An unexpected error occurred on the server that prevented flag evaluation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/generalErrorResponse"
              example:
                errorDetails: "An internal server error occurred while processing the request"
components:
  securitySchemes:
    BearerAuth:
      description: |
        Optional Bearer token authentication. If supported by the flag management system, 
        clients can authenticate using a Bearer token in the `Authorization` header following 
        the format: `Authorization: Bearer <token>`.
      type: http
      scheme: bearer
      bearerFormat: JWT
    ApiKeyAuth:
      description: |
        Optional API key authentication. If supported by the flag management system, clients 
        can authenticate by providing an API key in the `X-API-Key` header.
      type: apiKey
      in: header
      name: X-API-Key
  schemas:
    bulkEvaluationRequest:
      description: |
        Request body for bulk flag evaluation. Contains a static context that will be used 
        to evaluate all flags.
      type: object
      required:
        - context
      properties:
        context:
          $ref: "#/components/schemas/context"
    bulkEvaluationSuccess:
      description: |
        Success response for bulk flag evaluation. Contains an array of flag evaluations, 
        where each item can be either a successful evaluation or an evaluation failure. 
        This allows partial success scenarios where some flags may fail while others succeed.
      type: object
      required:
        - flags
      properties:
        flags:
          type: array
          description: Array of flag evaluations. Each evaluation can be a success or failure.
          items:
            oneOf:
              - $ref: "#/components/schemas/evaluationSuccess"
              - $ref: "#/components/schemas/evaluationFailure"
        metadata:
          $ref: "#/components/schemas/metadata"
          description: |
            Arbitrary metadata for the flag set, useful for telemetry and documentary purposes.
    bulkEvaluationFailure:
      description: |
        Failure response for bulk evaluation. Returned when the entire bulk evaluation request 
        fails (e.g., invalid context, parse errors). Individual flag failures within a successful 
        bulk evaluation are represented as evaluationFailure items in the flags array.
      type: object
      properties:
        errorCode:
          type: string
          description: |
            An error code specific to the bulk evaluation error. See 
            https://openfeature.dev/specification/types#error-code for error code definitions.
          example: INVALID_CONTEXT
        errorDetails:
          type: string
          description: Optional error details description for logging or debugging purposes
          example: "Context is missing required targetingKey property"
      required:
        - errorCode
    evaluationRequest:
      description: |
        Request body for single feature flag evaluation. Contains the evaluation context that will be 
        used to evaluate the feature flag.
      type: object
      required:
        - context
      properties:
        context:
          $ref: "#/components/schemas/context"
    serverEvaluationSuccess:
      allOf:
        - $ref: "#/components/schemas/evaluationSuccess"
    evaluationSuccess:
      description: |
        Successful feature flag evaluation response. The value property is present 
        for all flag types except `codeDefaultFlag`, which indicates the provider should use the 
        code default value.
      type: object
      required:
        - key
        - reason
      allOf:
        - properties:
            key:
              $ref: "#/components/schemas/key"
            reason:
              type: string
              description: |
                An OpenFeature reason code indicating why the flag was evaluated to this value. 
                See https://openfeature.dev/specification/types/#resolution-reason for reason code definitions.
              enum: [STATIC, TARGETING_MATCH, SPLIT, DISABLED, UNKNOWN]
            variant:
              type: string
              description: |
                Variant identifier for the evaluated feature flag value. Represents a specific variation 
                or configuration of the feature flag.
            metadata:
              allOf:
                - $ref: "#/components/schemas/metadata"
                - $ref: "#/components/schemas/flagMetadataDescription"
                - $ref: "#/components/schemas/flagMetadataExamples"
        - oneOf:
            - $ref: "#/components/schemas/booleanFlag"
            - $ref: "#/components/schemas/stringFlag"
            - $ref: "#/components/schemas/integerFlag"
            - $ref: "#/components/schemas/floatFlag"
            - $ref: "#/components/schemas/objectFlag"
            - $ref: "#/components/schemas/codeDefaultFlag"
    evaluationFailure:
      description: |
        Feature flag evaluation failure response. Returned when a feature flag evaluation fails, such as when 
        the context is invalid, required targeting keys are missing, or parsing errors occur. 
      type: object
      properties:
        key:
          $ref: "#/components/schemas/key"
        errorCode:
          type: string
          description: |
            OpenFeature compatible error code indicating the type of error. See 
            https://openfeature.dev/specification/types#error-code for error code definitions.
          enum: [PARSE_ERROR, TARGETING_KEY_MISSING, INVALID_CONTEXT, GENERAL]
        errorDetails:
          $ref: "#/components/schemas/errorDetails"
        metadata:
          allOf:
            - $ref: "#/components/schemas/metadata"
            - $ref: "#/components/schemas/flagMetadataDescription"
            - $ref: "#/components/schemas/flagMetadataExamples"
      required:
        - key
        - errorCode
    flagNotFound:
      description: |
        Feature flag not found response. Returned when a requested feature flag key does not exist in the 
        flag management system. This can be an expected response in certain flag management systems. 
        This is distinct from evaluation failures, which occur when a flag exists but cannot be evaluated.
      type: object
      properties:
        key:
          $ref: "#/components/schemas/key"
        errorCode:
          type: string
          description: Error code indicating the flag was not found
          enum: [FLAG_NOT_FOUND]
        errorDetails:
          $ref: "#/components/schemas/errorDetails"
        metadata:
          allOf:
            - $ref: "#/components/schemas/metadata"
            - $ref: "#/components/schemas/flagMetadataDescription"
            - $ref: "#/components/schemas/flagMetadataExamples"
      required:
        - key
        - errorCode
    generalErrorResponse:
      description: |
        General error response for unexpected server errors (500 status). Used when the 
        server encounters an internal error that prevents flag evaluation.
      type: object
      properties:
        errorDetails:
          $ref: "#/components/schemas/errorDetails"
    key:
      type: string
      description: |
        The unique identifier (key) of the feature flag. This is used to reference a specific 
        flag in the flag management system.
      example: discount-banner
    context:
      type: object
      description: |
        Evaluation context containing information used to evaluate feature flags. The context 
        includes a `targetingKey` (required) along with additional properties such as 
        user attributes, session data, or request metadata that can be used for targeting rules.
      required:
        - targetingKey
      properties:
        targetingKey:
          type: string
      additionalProperties: true
      example:
        targetingKey: user-123
        email: user@example.com
        plan: premium
        country: CA
    booleanFlag:
      description: A boolean typed flag value. Used for simple on/off feature flags.
      type: object
      properties:
        value:
          type: boolean
      required:
        - value
    stringFlag:
      description: A string typed flag value.
      type: object
      properties:
        value:
          type: string
      required:
        - value
    integerFlag:
      description: An integer typed flag value.
      type: object
      properties:
        value:
          type: integer
      required:
        - value
    floatFlag:
      description: A float typed flag value.
      type: object
      properties:
        value:
          type: number
          format: float
      required:
        - value
    objectFlag:
      description: An object typed flag value.
      type: object
      properties:
        value:
          type: object
          additionalProperties: true
      required:
        - value
    codeDefaultFlag:
      description: |
        A flag evaluation that defers to the code default value. When a flag evaluation returns 
        this type, it indicates that the provider should use the default value specified in the 
        application code rather than a value from the flag management system.

        **Note**: This schema has no `value` property. The provider must use the code default 
        value when processing this response.
      type: object
      properties: {}
    errorDetails:
      type: string
      description: |
        A human-readable error description providing additional context about the evaluation 
        failure. Useful for logging, debugging, and monitoring purposes.
    metadata:
      type: object
      description: |
        Arbitrary metadata object that can contain any additional information about flags or 
        flag sets. This metadata is useful for debugging and telemetry purposes.
      additionalProperties:
        oneOf:
          - type: boolean
          - type: string
          - type: number
    flagMetadataExamples:
      description: Example metadata structure for flags
      example:
        team: ecommerce
        businessPurpose: experiment
        owner: "product-team"
    flagMetadataDescription:
      description: |
        Arbitrary metadata for the flag, useful for telemetry and documentary purposes.