Merge branch 'main' into provider-readme

open-feature · Jun 20, 2024 · 1eeb299 · 1eeb299
2 parents ce3ad93 + 21635df
commit 1eeb299
Showing 1 changed file with 65 additions and 41 deletions.
diff --git a/service/openapi.yaml b/service/openapi.yaml
@@ -13,46 +13,24 @@ info:
 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/configuration:
-    get:
-      summary: OFREP provider configuration
-      description: OFREP configuration to provide information about the remote flag management system, to configure the OpenFeature SDK providers. This endpoint will be called during the initialization of the provider.
-      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'
   /ofrep/v1/evaluate/flags/{key}:
     post:
+      tags: [OFREP core]
       summary: OFREP single flag evaluation contract
-      description: OFREP single flag evaluation request
+      description: |
+        OFREP single flag evaluation request.  
+        The endpoint is called by the server providers to perform single flag evaluation.
       parameters:
         - name: key
           in: path
@@ -105,8 +83,11 @@ paths:
                 $ref: '#/components/schemas/generalErrorResponse'
   /ofrep/v1/evaluate/flags:
     post:
+      tags: [OFREP core]
       summary: OFREP bulk flag evaluation contract
-      description: OFREP bulk evaluation request
+      description: |
+        OFREP bulk evaluation request.  
+        The endpoint is called by the client providers to perform single flag evaluation.
       parameters:
         - in: header
           name: If-None-Match
@@ -159,6 +140,44 @@ paths:
             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:
@@ -339,14 +358,17 @@ components:
       type: object
       description: Configurations specific for flag evaluations in OFREP provider implementation
       properties:
-        unsupportedTypes:
-          description: A list of unsupported types by the flag management system. Evaluating a flag of a listed type through OFREP provider will result in an error and yield the default value.
+        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
@@ -360,9 +382,11 @@ components:
         enabled:
           type: boolean
           description: set to true if the remote flag management system is supporting polling
-        minPollingInterval:
+        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.
+          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: