Skip to content

Commit

Permalink
feat: update bucketing API OpenAPI docs to include OpenFeature Remote…
Browse files Browse the repository at this point in the history 
… Evaluation Protocol (#567)

* feat: update bucketing API OpenAPI docs to include OpenFeature Remote Evaluation Protocol

* feat: update OFREP descriptions

* fix: update formatting again

* fix: tags
  • Loading branch information
@jonathannorris
jonathannorris authored Mar 8, 2024
1 parent abcacec commit f0fede9
Showing 1 changed file with 293 additions and 8 deletions.
301 changes: 293 additions & 8 deletions bucketing-api.yaml
View file
Original file line number Diff line number Diff line change
@@ -1,16 +1,22 @@
openapi: 3.0.0
openapi: 3.1.0
info:
title: DevCycle Bucketing API
description:
Documents the DevCycle Bucketing API (https://docs.devcycle.com/bucketing-api/) which provides an API interface to
Documents the DevCycle Bucketing API (https://bucketing-api.devcycle.com/) which provides an API interface to
User Bucketing and for generated SDKs.
version: 1.1.0
version: 1.2.0

servers:
- url: https://bucketing-api.devcycle.com/

tags:
- name: EdgeDB
- name: Bucketing API
- name: Feature Opt-in
- name: OpenFeature Remote Evaluation API (OFREP)
description:
"See the OpenFeature documentation for more information: https://github.com/open-feature/protocol"

paths:
/v1/variables/{key}:
post:
Expand Down Expand Up @@ -151,7 +157,7 @@ paths:
required: false
schema:
type: string

requestBody:
description: User properties to update the EdgeDB data
required: true
Expand All @@ -175,6 +181,7 @@ paths:
$ref: '#/components/responses/NotFound'
500:
$ref: '#/components/responses/InternalServerError'

/v1/optInConfig:
get:
summary: Fetch opt-in config
Expand Down Expand Up @@ -208,6 +215,7 @@ paths:
$ref: '#/components/responses/UnauthorizedError'
500:
$ref: '#/components/responses/InternalServerError'

/v1/optIns/:user_id:
put:
summary: Update opt-in preferences for a user
Expand Down Expand Up @@ -242,6 +250,125 @@ paths:
500:
$ref: '#/components/responses/InternalServerError'

/ofrep/v1/evaluate/flags/{key}:
post:
tags:
- OpenFeature Remote Evaluation API (OFREP)
summary:
OFREP Single Flag Evaluation Request
description:
Return a single flag for a user context
parameters:
- name: key
in: path
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ofrep-evaluationRequest'
responses:
'200':
description: OFREP successful evaluation response
content:
application/json:
schema:
$ref: '#/components/schemas/ofrep-evaluationSuccess'
'400':
description: Bad evaluation request
content:
application/json:
schema:
$ref: '#/components/schemas/ofrep-evaluationFailure'
'404':
description: Flag not found
content:
application/json:
schema:
$ref: '#/components/schemas/ofrep-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-Later:
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/ofrep-generalErrorResponse'

/ofrep/v1/evaluate/flags:
post:
tags:
- OpenFeature Remote Evaluation API (OFREP)
summary:
OFREP Bulk Evaluation Request
description:
Return all flag values for a user context.
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/ofrep-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/ofrep-bulkEvaluationSuccess'
'304':
description: Bulk evaluation is not modified
'400':
description: Bad evaluation request
content:
application/json:
schema:
$ref: '#/components/schemas/ofrep-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-Later:
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/ofrep-generalErrorResponse'
components:
securitySchemes:
bearerAuth:
Expand All @@ -261,7 +388,7 @@ components:
email:
description: User's email used to identify the user on the dashaboard / target audiences
type: string

name:
description: User's name used to idenify the user on the dashaboard / target audiences
type: string
Expand All @@ -271,7 +398,7 @@ components:
additionalProperties:
type: string
maxLength: 2

country:
description: User's country in ISO 3166 alpha-2 format
additionalProperties:
Expand All @@ -281,11 +408,11 @@ components:
customData:
description: User's custom data to target the user with, data will be logged to DevCycle for use in dashboard.
type: object

lastSeenDate:
description: Date the user was last seen being used, Unix epoch timestamp format
type: number

required:
- user_id

Expand Down Expand Up @@ -471,6 +598,164 @@ components:
required:
- message

# OpenFeature Remote Evaluation API Schemas
ofrep-bulkEvaluationRequest:
description: Evaluate multiple flags in one request
properties:
context:
$ref: '#/components/schemas/ofrep-context'
ofrep-bulkEvaluationSuccess:
description: Success response for the bulk evaluation request
type: object
properties:
flags:
type: array
items:
oneOf:
- $ref: "#/components/schemas/ofrep-evaluationSuccess"
- $ref: '#/components/schemas/ofrep-evaluationFailure'

ofrep-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

ofrep-evaluationRequest:
description: Flag evaluation request
properties:
context:
$ref: '#/components/schemas/ofrep-context'

ofrep-evaluationSuccess:
description: Flag evaluation success response.
allOf:
- properties:
key:
$ref: "#/components/schemas/ofrep-key"
reason:
type: string
enum: [ 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
description: Arbitrary metadata supporting flag evaluation
- oneOf:
- $ref: "#/components/schemas/ofrep-booleanFlag"
- $ref: "#/components/schemas/ofrep-stringFlag"
- $ref: "#/components/schemas/ofrep-integerFlag"
- $ref: "#/components/schemas/ofrep-floatFlag"
- $ref: "#/components/schemas/ofrep-objectFlag"

ofrep-evaluationFailure:
description: Flag evaluation failure response
properties:
key:
$ref: '#/components/schemas/ofrep-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/ofrep-errorDetails'
required:
- key
- errorCode

ofrep-flagNotFound:
description: Flag not found response
properties:
key:
$ref: '#/components/schemas/ofrep-key'
errorCode:
type: string
enum: [ FLAG_NOT_FOUND ]
errorDetails:
$ref: '#/components/schemas/ofrep-errorDetails'
required:
- key
- errorCode

ofrep-generalErrorResponse:
description: A general error response from the service
properties:
errorDetails:
$ref: '#/components/schemas/ofrep-errorDetails'

ofrep-key:
type: string
description: Feature flag key
examples:
- my-flag

ofrep-context:
type: object
description: Context information for flag evaluation

ofrep-booleanFlag:
description: A boolean typed flag value
properties:
value:
type: boolean
description: Flag evaluation result
required:
- value

ofrep-stringFlag:
description: A string typed flag value
properties:
value:
type: string
description: Flag evaluation result
examples:
- "my-flag-value"
required:
- value

ofrep-integerFlag:
description: An integer typed flag value
properties:
value:
type: integer
description: Flag evaluation result
examples:
- 3
required:
- value

ofrep-floatFlag:
description: A float typed flag value
properties:
value:
type: number
description: Flag evaluation result
examples:
- 3.1415
required:
- value

ofrep-objectFlag:
description: An object typed flag value
properties:
value:
type: object
description: Flag evaluation result
required:
- value

ofrep-errorDetails:
type: string
description: An error description for logging or other needs

requestBodies:
UserRequestBody:
required: true
Expand Down

0 comments on commit f0fede9

Please sign in to comment.