openapi: 3.1.0
servers:
  - url: /
info:
  version: 0.1.0
  title: OpenFeature Remote Evaluation Protocol (OFREP)
  description: OFREP define the protocol for remote flag evaluations
  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.*
  - name: OFREP Extensions
    description: |
      **Optional**: Extension APIs to provide full support for OFREP.  
      *These APIs are utilized by the providers to enhance the OFREP experience.*
      
paths:
  /ofrep/v1/evaluate/flags/{key}:
    post:
      tags: [OFREP core]
      summary: OFREP single flag evaluation contract
      description: |
        OFREP single flag evaluation request.
        The endpoint is called by the server providers to perform single flag evaluation.
      parameters:
        - name: key
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/evaluationRequest'
      responses:
        '200':
          description: OFREP successful evaluation response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/evaluationSuccess'
        '400':
          description: Bad evaluation request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/evaluationFailure'
        '404':
          description: Flag not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/flagNotFound'
        '401':
          description: Unauthorized - You need credentials to access the API
        '403':
          description: Forbidden - You are not authorized to access the API
        '429':
          description: Rate limit reached on the Flag Management System
          headers:
            Retry-After:
              description: Indicates when to retry the request again
              schema:
                type: string
                format: date-time
                examples:
                  - '2024-02-07T12:00:00Z'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/generalErrorResponse'
  /ofrep/v1/evaluate/flags:
    post:
      tags: [OFREP core]
      summary: OFREP bulk flag evaluation contract
      description: |
        OFREP bulk evaluation request.
        The endpoint is called by the client providers to evaluate all flags at once.
      parameters:
        - in: header
          name: If-None-Match
          description: The request will be processed only if ETag doesn't match any of the values listed.
          schema:
            type: string
          required: false
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/bulkEvaluationRequest'
      responses:
        '200':
          description: OFREP successful evaluation response
          headers:
            ETag:
              schema:
                type: string
              description: Entity tag used for cache validation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bulkEvaluationSuccess'
        '304':
          description: Bulk evaluation is not modified
        '400':
          description: Bad evaluation request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bulkEvaluationFailure'
        '401':
          description: Unauthorized - You need credentials to access the API
        '403':
          description: Forbidden - You are not authorized to access the API
        '429':
          description: Rate limit reached on the Flag Management System
          headers:
            Retry-After:
              description: Indicates when to retry the request again
              schema:
                type: string
                format: date-time
                examples:
                  - '2024-02-07T12:00:00Z'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/generalErrorResponse'
  /ofrep/v1/configuration:
    get:
      tags: [OFREP extensions]
      summary: OFREP provider configuration
      description: |
        OFREP configuration is used to supply information about the remote flag management system and to set up the OpenFeature SDK providers.
        The providers will contact this endpoint only if the client has opted in.
      parameters:
        - in: header
          name: If-None-Match
          description: The request will be processed only if ETag doesn't match any of the values listed.
          schema:
            type: string
          required: false
      responses:
        '200':
          description: OFREP metadata response
          headers:
            ETag:
              schema:
                type: string
              description: Entity tag used for cache validation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/configurationResponse'
        '304':
          description: Flag Management System Metadata is not modified
        '401':
          description: Unauthorized - You need credentials to access the API
        '403':
          description: Forbidden - You are not authorized to access the API
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/generalErrorResponse'
components:
  securitySchemes:
    BearerAuth:
      description: (optional) Bearer Authorization to your flag management system.
      type: http
      scheme: bearer
    ApiKeyAuth:
      description: (optional) API Key to your flag management system.
      type: apiKey
      in: header
      name: X-API-Key
  schemas:
    bulkEvaluationRequest:
      description: Evaluate multiple flags in one request
      properties:
        context:
          $ref: '#/components/schemas/context'
    bulkEvaluationSuccess:
      description: Success response for the bulk evaluation request
      type: object
      required:
        - flags
      properties:
        flags:
          type: array
          items:
            oneOf:
              - $ref: "#/components/schemas/evaluationSuccess"
              - $ref: '#/components/schemas/evaluationFailure'
    bulkEvaluationFailure:
      description: Bulk evaluation failure response
      properties:
        errorCode:
          type: string
          description: An appropriate  code specific to the bulk evaluation error. See https://openfeature.dev/specification/types#error-code
        errorDetails:
          type: string
          description: Optional error details description for logging or other needs
      required:
        - errorCode
    evaluationRequest:
      description: Flag evaluation request
      properties:
        context:
          $ref: '#/components/schemas/context'
    evaluationSuccess:
      description: Flag evaluation success response.
      allOf:
        - properties:
            key:
              $ref: "#/components/schemas/key"
            reason:
              type: string
              examples: [ STATIC,TARGETING_MATCH,SPLIT,DISABLED,UNKNOWN ]
              description: An OpenFeature reason for the evaluation
            variant:
              type: string
              description: Variant of the evaluated flag value
            metadata:
              type: object
              additionalProperties:
                oneOf:
                  - type: boolean
                  - type: string
                  - type: number
              description: Arbitrary metadata supporting flag evaluation
        - oneOf:
            - $ref: "#/components/schemas/booleanFlag"
            - $ref: "#/components/schemas/stringFlag"
            - $ref: "#/components/schemas/integerFlag"
            - $ref: "#/components/schemas/floatFlag"
            - $ref: "#/components/schemas/objectFlag"
    evaluationFailure:
      description: Flag evaluation failure response
      properties:
        key:
          $ref: '#/components/schemas/key'
        errorCode:
          type: string
          enum: [ PARSE_ERROR,TARGETING_KEY_MISSING,INVALID_CONTEXT,GENERAL ]
          description: OpenFeature compatible error code. See https://openfeature.dev/specification/types#error-code
        errorDetails:
          $ref: '#/components/schemas/errorDetails'
      required:
        - key
        - errorCode
    flagNotFound:
      description: Flag not found response
      properties:
        key:
          $ref: '#/components/schemas/key'
        errorCode:
          type: string
          enum: [ FLAG_NOT_FOUND ]
        errorDetails:
          $ref: '#/components/schemas/errorDetails'
      required:
        - key
        - errorCode
    generalErrorResponse:
      description: A general error response from the service
      properties:
        errorDetails:
          $ref: '#/components/schemas/errorDetails'
    key:
      type: string
      description: Feature flag key
      examples:
        - my-flag
    context:
      type: object
      description: Context information for flag evaluation
      properties:
        targetingKey:
          type: string
          description: A string logically identifying the subject of evaluation (end-user, service, etc).
          examples:
            - user-123
      additionalProperties: true
    booleanFlag:
      description: A boolean typed flag value
      properties:
        value:
          type: boolean
          description: Flag evaluation result
      required:
        - value
    stringFlag:
      description: A string typed flag value
      properties:
        value:
          type: string
          description: Flag evaluation result
          examples:
            - "my-flag-value"
      required:
        - value
    integerFlag:
      description: An integer typed flag value
      properties:
        value:
          type: integer
          description: Flag evaluation result
          examples:
            - 3
      required:
        - value
    floatFlag:
      description: A float typed flag value
      properties:
        value:
          type: number
          description: Flag evaluation result
          examples:
            - 3.1415
      required:
        - value
    objectFlag:
      description: An object typed flag value
      properties:
        value:
          type: object
          description: Flag evaluation result
      required:
        - value
    errorDetails:
      type: string
      description: An error description for logging or other needs
    configurationResponse:
      description: OFREP metadata response
      properties:
        name:
          type: string
          description: name of the flag management system
          examples:
            - flagd
            - go-feature-flag
        capabilities:
          type: object
          description: Capabilities of the flag management system and how to configure them in the provider.
          properties:
            cacheInvalidation:
              $ref: '#/components/schemas/featureCacheInvalidation'
            flagEvaluation:
              $ref: '#/components/schemas/flagEvaluation'
    flagEvaluation:
      type: object
      description: Configurations specific for flag evaluations in OFREP provider implementation
      properties:
        supportedTypes:
          description: |
            Evaluating a flag of unlisted type through the OFREP provider will result in an error and yield the default value.
            However, when supportedTypes is undefined/empty, provider assumes that all flag evaluation types are supported by the flag management system
          type: array
          items:
            type: string
            enum: [int, float, string, boolean, object]
          examples:
            - ["object", "int", "float"]
            - null
    featureCacheInvalidation:
      type: object
      description: Configuration for the cache cacheInvalidation
      properties:
        polling:
          $ref: '#/components/schemas/featureCacheInvalidationPolling'
    featureCacheInvalidationPolling:
      type: object
      description: Configuration of the polling for the featureCacheInvalidation
      properties:
        enabled:
          type: boolean
          description: set to true if the remote flag management system is supporting polling
        minPollingIntervalMs:
          type: number
          description: |
            Minimum polling interval (in millisecond) supported by the flag management system.  
            The provider should ensure not to set any polling value under this minimum.
          examples:
            - 60000
      required:
        - name