basePath: /
definitions:
controller.FlagChangeResponse:
properties:
flags:
additionalProperties:
type: integer
type: object
hash:
type: integer
type: object
controller.retrieverRefreshResponse:
properties:
refreshed:
type: boolean
type: object
exporter.FeatureEvent:
properties:
contextKind:
description: |-
ContextKind is the kind of context which generated an event. This will only be "anonymousUser" for events generated
on behalf of an anonymous user or the reserved word "user" for events generated on behalf of a non-anonymous user
example: user
type: string
creationDate:
description: CreationDate When the feature flag was requested at Unix epoch
time in milliseconds.
example: 1680246000011
type: integer
default:
description: |-
Default value is set to true if feature flag evaluation failed, in which case the value returned was the default
value passed to variation. If the default field is omitted, it is assumed to be false.
example: false
type: boolean
key:
description: Key of the feature flag requested.
example: my-feature-flag
type: string
kind:
description: |-
Kind for a feature event is feature.
A feature event will only be generated if the trackEvents attribute of the flag is set to true.
example: feature
type: string
metadata:
allOf:
- $ref: '#/definitions/exporter.FeatureEventMetadata'
description: Metadata are static information added in the providers to give
context about the events generated.
source:
description: |-
Source indicates where the event was generated.
This is set to SERVER when the event was evaluated in the relay-proxy and PROVIDER_CACHE when it is evaluated from the cache.
example: SERVER
type: string
userKey:
description: |-
UserKey The key of the user object used in a feature flag evaluation. Details for the user object used in a feature
flag evaluation as reported by the "feature" event are transmitted periodically with a separate index event.
example: 94a25909-20d8-40cc-8500-fee99b569345
type: string
value:
description: Value of the feature flag returned by feature flag evaluation.
variation:
description: |-
Variation of the flag requested. Flag variation values can be "True", "False", "Default" or "SdkDefault"
depending on which value was taken during flag evaluation. "SdkDefault" is used when an error is detected and the
default value passed during the call to your variation is used.
example: admin-variation
type: string
version:
description: |-
Version contains the version of the flag. If the field is omitted for the flag in the configuration file
the default version will be 0.
example: v1.0.0
type: string
type: object
exporter.FeatureEventMetadata:
additionalProperties: true
type: object
flag.ErrorCode:
enum:
- PROVIDER_NOT_READY
- FLAG_NOT_FOUND
- PARSE_ERROR
- TYPE_MISMATCH
- GENERAL
- INVALID_CONTEXT
- TARGETING_KEY_MISSING
- FLAG_CONFIG
type: string
x-enum-varnames:
- ErrorCodeProviderNotReady
- ErrorCodeFlagNotFound
- ErrorCodeParseError
- ErrorCodeTypeMismatch
- ErrorCodeGeneral
- ErrorCodeInvalidContext
- ErrorCodeTargetingKeyMissing
- ErrorFlagConfiguration
flag.Flag:
properties:
defValue:
description: default value (as text); for usage message
type: string
name:
description: name as it appears on command line
type: string
usage:
description: help message
type: string
value:
description: value as set
type: object
model.AllFlagRequest:
properties:
evaluationContext:
allOf:
- $ref: '#/definitions/model.EvaluationContextRequest'
description: EvaluationContext The representation of a EvaluationContext for
your feature flag system.
type: object
model.CollectEvalDataRequest:
properties:
events:
description: Events is the list of the event we send in the payload
items:
$ref: '#/definitions/exporter.FeatureEvent'
type: array
meta:
allOf:
- $ref: '#/definitions/exporter.FeatureEventMetadata'
description: Meta are the extra information added during the configuration
type: object
model.CollectEvalDataResponse:
properties:
ingestedContentCount:
description: IngestedContentCount number of model.FeatureEvents that have
been sent to the data exporter
type: integer
type: object
model.EvalFlagRequest:
properties:
defaultValue:
description: The value will we use if we are not able to get the variation
of the flag.
evaluationContext:
allOf:
- $ref: '#/definitions/model.EvaluationContextRequest'
description: EvaluationContext The representation of a EvaluationContext for
your feature flag system.
type: object
model.EvaluationContextRequest:
properties:
custom:
additionalProperties:
type: string
description: Custom is a map containing all extra information for this user.
example:
company: GO Feature Flag
email: contact@gofeatureflag.org
firstname: John
lastname: Doe
type: object
key:
description: Key is the identifier of the UserRequest.
example: 08b5ffb7-7109-42f4-a6f2-b85560fbd20f
type: string
type: object
model.HealthResponse:
properties:
initialized:
description: Set to true if the HTTP server is started
example: true
type: boolean
type: object
model.InfoResponse:
properties:
cacheRefresh:
description: This is the last time when your flag file was read and store
in the internal cache.
example: "2022-06-13T11:22:55.941628+02:00"
type: string
type: object
model.OFREPBulkEvaluateSuccessResponse:
properties:
flags:
items:
$ref: '#/definitions/model.OFREPFlagBulkEvaluateSuccessResponse'
type: array
type: object
model.OFREPCommonErrorResponse:
properties:
errorCode:
$ref: '#/definitions/flag.ErrorCode'
errorDetails:
type: string
type: object
model.OFREPConfigCapabilities:
properties:
cacheInvalidation:
$ref: '#/definitions/model.OFREPConfigCapabilitiesCacheInvalidation'
flagEvaluation:
$ref: '#/definitions/model.OFREPConfigCapabilitiesFlagEvaluation'
type: object
model.OFREPConfigCapabilitiesCacheInvalidation:
properties:
polling:
$ref: '#/definitions/model.OFREPConfigCapabilitiesCacheInvalidationPolling'
type: object
model.OFREPConfigCapabilitiesCacheInvalidationPolling:
properties:
enabled:
type: boolean
minPollingInterval:
type: integer
type: object
model.OFREPConfigCapabilitiesFlagEvaluation:
properties:
unsupportedTypes:
items:
type: string
type: array
type: object
model.OFREPConfiguration:
properties:
capabilities:
$ref: '#/definitions/model.OFREPConfigCapabilities'
name:
type: string
type: object
model.OFREPEvalFlagRequest:
properties:
context:
additionalProperties:
type: string
example:
company: GO Feature Flag
firstname: John
lastname: Doe
targetingKey: 4f433951-4c8c-42b3-9f18-8c9a5ed8e9eb
type: object
type: object
model.OFREPEvaluateErrorResponse:
properties:
errorCode:
$ref: '#/definitions/flag.ErrorCode'
errorDetails:
type: string
key:
type: string
type: object
model.OFREPEvaluateSuccessResponse:
properties:
key:
type: string
metadata:
additionalProperties: {}
type: object
reason:
type: string
value: {}
variant:
type: string
type: object
model.OFREPFlagBulkEvaluateSuccessResponse:
properties:
errorCode:
type: string
errorDetails:
type: string
key:
type: string
metadata:
additionalProperties: {}
type: object
reason:
type: string
value: {}
variant:
type: string
type: object
modeldocs.AllFlags:
description: AllFlags contains the full list of all the flags available for the
user
properties:
flags:
additionalProperties:
$ref: '#/definitions/modeldocs.FlagState'
description: flags is the list of flag for the user.
type: object
valid:
description: '`true` if something went wrong in the relay proxy (flag does
not exists, ...) and we serve the defaultValue.'
example: false
type: boolean
type: object
modeldocs.EvalFlagDoc:
properties:
errorCode:
description: Code of the error returned by the server.
example: ""
type: string
failed:
description: '`true` if something went wrong in the relay proxy (flag does
not exists, ...) and we serve the defaultValue.'
example: false
type: boolean
metadata:
additionalProperties: true
description: Metadata is a field containing information about your flag such
as an issue tracker link, a description, etc ...
type: object
reason:
description: reason why we have returned this value.
example: TARGETING_MATCH
type: string
trackEvents:
description: '`true` if the event was tracked by the relay proxy.'
example: true
type: boolean
value:
description: The flag value for this user.
variationType:
description: The variation used to give you this value.
example: variation-A
type: string
version:
description: The version of the flag used.
example: "1.0"
type: string
type: object
modeldocs.FlagState:
properties:
timestamp:
description: Timestamp is the time when the flag was evaluated.
example: 1652113076
type: integer
trackEvents:
description: TrackEvents this flag is trackable.
example: false
type: boolean
value:
description: Value is the flag value, it can be any JSON types.
variationType:
description: VariationType is the name of the variation used to have the flag
value.
example: variation-A
type: string
type: object
modeldocs.HTTPErrorDoc:
properties:
message:
description: Message of your error
example: An error occurred
type: string
type: object
notifier.DiffCache:
properties:
added:
additionalProperties:
$ref: '#/definitions/flag.Flag'
type: object
deleted:
additionalProperties:
$ref: '#/definitions/flag.Flag'
type: object
updated:
additionalProperties:
$ref: '#/definitions/notifier.DiffUpdated'
type: object
type: object
notifier.DiffUpdated:
properties:
new_value:
$ref: '#/definitions/flag.Flag'
old_value:
$ref: '#/definitions/flag.Flag'
type: object
info:
contact:
email: contact@gofeatureflag.org
name: GO feature flag relay proxy
url: https://gofeatureflag.org
description: "# Introduction\n\nThis API is documented in **OpenAPI format** and
describe the REST API of the **GO Feature Flag relay proxy**.\n\nThe relay proxy
is a component to evaluate your feature flags remotely when using **GO Feature
Flag**. \nThis API is mostly used by all the OpenFeature providers."
license:
name: MIT
url: https://github.com/thomaspoignant/go-feature-flag/blob/main/LICENSE
title: GO Feature Flag relay proxy endpoints
x-logo:
url: https://raw.githubusercontent.com/thomaspoignant/go-feature-flag/main/logo_128.png
paths:
/admin/v1/retriever/refresh:
post:
description: |-
This endpoint is used to force the refresh of the flags in the cache.
This endpoint is used when you know explicitly that a flag has changed, and you want to trigger
the collection of the new versions.
produces:
- application/json
responses:
"200":
description: Success
schema:
$ref: '#/definitions/controller.retrieverRefreshResponse'
"400":
description: Bad Request
schema:
$ref: '#/definitions/modeldocs.HTTPErrorDoc'
"500":
description: Internal server error
schema:
$ref: '#/definitions/modeldocs.HTTPErrorDoc'
security:
- ApiKeyAuth: []
summary: This endpoint is used to force the refresh of the flags in the cache.
tags:
- Admin API to manage GO Feature Flag
/debug/pprof/:
get:
description: |-
This endpoint is provided by the echo pprof middleware.
To know more please check this blogpost from the GO team https://go.dev/blog/pprof.
Visit the page /debug/pprof/ to see the available endpoints, all endpoint are not in the swagger documentation because they are standard pprof endpoints.
This endpoint is only available in debug mode.
produces:
- text/plain
responses:
"200":
description: OK
schema:
type: string
summary: pprof endpoint
tags:
- Profiling
/health:
get:
description: |-
Making a **GET** request to the URL path `/health` will tell you if the relay proxy is ready to serve
traffic.
This is useful especially for loadbalancer to know that they can send traffic to the service.
produces:
- application/json
responses:
"200":
description: OK
schema:
$ref: '#/definitions/model.HealthResponse'
summary: Health
tags:
- Monitoring
/info:
get:
description: |-
Making a **GET** request to the URL path `/info` will give you information about the actual state
of the relay proxy.
As of Today the level of information is small be we can improve this endpoint to returns more
information.
produces:
- application/json
responses:
"200":
description: OK
schema:
$ref: '#/definitions/model.InfoResponse'
summary: Info
tags:
- Monitoring
/metrics:
get:
description: This endpoint is providing metrics about the relay proxy in the
prometheus format.
produces:
- text/plain
responses:
"200":
description: OK
schema:
type: string
summary: Prometheus endpoint
tags:
- Monitoring
/ofrep/v1/configuration:
get:
consumes:
- application/json
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:
- description: The request will be processed only if ETag doesn't match.
in: header
name: If-None-Match
type: string
produces:
- application/json
responses:
"200":
description: Success
schema:
$ref: '#/definitions/model.OFREPConfiguration'
"304":
description: 'Etag: \"117-0193435c612c50d93b798619d9464856263dbf9f\'
schema:
type: string
"401":
description: Unauthorized
schema:
$ref: '#/definitions/modeldocs.HTTPErrorDoc'
"404":
description: Flag Not Found
schema:
$ref: '#/definitions/model.OFREPEvaluateErrorResponse'
"500":
description: Internal server error
schema:
$ref: '#/definitions/modeldocs.HTTPErrorDoc'
security:
- ApiKeyAuth: []
summary: OFREP provider configuration
tags:
- OpenFeature Remote Evaluation Protocol (OFREP)
/ofrep/v1/evaluate/flags:
post:
consumes:
- application/json
description: |-
Making a **POST** request to the URL `/ofrep/v1/evaluate/flags` will give you the value of the list
of feature flags for this evaluation context.
If no flags are provided, the API will evaluate all available flags in the configuration.
parameters:
- description: The request will be processed only if ETag doesn't match.
in: header
name: If-None-Match
type: string
- description: Evaluation Context and list of flag for this API call
in: body
name: data
required: true
schema:
$ref: '#/definitions/model.OFREPEvalFlagRequest'
produces:
- application/json
responses:
"200":
description: OFREP successful evaluation response
schema:
$ref: '#/definitions/model.OFREPBulkEvaluateSuccessResponse'
"304":
description: 'Etag: \"117-0193435c612c50d93b798619d9464856263dbf9f\'
schema:
type: string
"400":
description: Bad evaluation request
schema:
$ref: '#/definitions/model.OFREPCommonErrorResponse'
"401":
description: Unauthorized - You need credentials to access the API
schema:
$ref: '#/definitions/modeldocs.HTTPErrorDoc'
"403":
description: Forbidden - You are not authorized to access the API
schema:
$ref: '#/definitions/modeldocs.HTTPErrorDoc'
"500":
description: Internal server error
schema:
$ref: '#/definitions/modeldocs.HTTPErrorDoc'
security:
- ApiKeyAuth: []
summary: Open-Feature Remote Evaluation Protocol bulk evaluation API.
tags:
- OpenFeature Remote Evaluation Protocol (OFREP)
/ofrep/v1/evaluate/flags/{flag_key}:
post:
consumes:
- application/json
description: |
Making a **POST** request to the URL `/ofrep/v1/evaluate/flags/{your_flag_name}` will give you the
value of the flag for this evaluation context
parameters:
- description: Evaluation Context for this API call
in: body
name: data
required: true
schema:
$ref: '#/definitions/model.OFREPEvalFlagRequest'
- description: Name of your feature flag
in: path
name: flag_key
required: true
type: string
produces:
- application/json
responses:
"200":
description: Success
schema:
$ref: '#/definitions/model.OFREPEvaluateSuccessResponse'
"400":
description: Bad Request
schema:
$ref: '#/definitions/model.OFREPEvaluateErrorResponse'
"401":
description: Unauthorized
schema:
$ref: '#/definitions/modeldocs.HTTPErrorDoc'
"404":
description: Flag Not Found
schema:
$ref: '#/definitions/model.OFREPEvaluateErrorResponse'
"500":
description: Internal server error
schema:
$ref: '#/definitions/modeldocs.HTTPErrorDoc'
security:
- ApiKeyAuth: []
summary: Evaluate a feature flag using the OpenFeature Remote Evaluation Protocol
tags:
- OpenFeature Remote Evaluation Protocol (OFREP)
/v1/allflags:
post:
consumes:
- application/json
description: |-
Making a **POST** request to the URL `/v1/allflags` will give you the values of all the flags for
this user.
To get a variation you should provide information about the user.
For that you should provide some user information in JSON in the request body.
parameters:
- description: Payload of the user we want to challenge against the flag.
in: body
name: data
required: true
schema:
$ref: '#/definitions/model.AllFlagRequest'
produces:
- application/json
responses:
"200":
description: Success
schema:
$ref: '#/definitions/modeldocs.AllFlags'
"400":
description: Bad Request
schema:
$ref: '#/definitions/modeldocs.HTTPErrorDoc'
"500":
description: Internal server error
schema:
$ref: '#/definitions/modeldocs.HTTPErrorDoc'
security:
- ApiKeyAuth: []
summary: All flags variations for a user
tags:
- GO Feature Flag Evaluation API
/v1/data/collector:
post:
consumes:
- application/json
description: |-
This endpoint is receiving the events of your flags usage to send them in the data collector.
It is used by the different Open Feature providers to send in bulk all the cached events to avoid
to lose track of what happen when a cached flag is used.
parameters:
- description: List of flag evaluation that be passed to the data exporter
in: body
name: data
required: true
schema:
$ref: '#/definitions/model.CollectEvalDataRequest'
produces:
- application/json
responses:
"200":
description: Success
schema:
$ref: '#/definitions/model.CollectEvalDataResponse'
"400":
description: Bad Request
schema:
$ref: '#/definitions/modeldocs.HTTPErrorDoc'
"500":
description: Internal server error
schema:
$ref: '#/definitions/modeldocs.HTTPErrorDoc'
security:
- ApiKeyAuth: []
summary: Endpoint to send usage of your flags to be collected
tags:
- GO Feature Flag Evaluation API
/v1/feature/{flag_key}/eval:
post:
consumes:
- application/json
description: |-
Making a **POST** request to the URL `/v1/feature/<your_flag_name>/eval` will give you the value of the
flag for this user.
To get a variation you should provide information about the user:
- User information in JSON in the request body.
- A default value in case there is an error while evaluating the flag.
Note that you will always have a usable value in the response, you can use the field `failed` to know if
an issue has occurred during the validation of the flag, in that case the value returned will be the
default value.
parameters:
- description: Payload of the user we want to get all the flags from.
in: body
name: data
required: true
schema:
$ref: '#/definitions/model.EvalFlagRequest'
- description: Name of your feature flag
in: path
name: flag_key
required: true
type: string
produces:
- application/json
responses:
"200":
description: Success
schema:
$ref: '#/definitions/modeldocs.EvalFlagDoc'
"400":
description: Bad Request
schema:
$ref: '#/definitions/modeldocs.HTTPErrorDoc'
"500":
description: Internal server error
schema:
$ref: '#/definitions/modeldocs.HTTPErrorDoc'
security:
- ApiKeyAuth: []
summary: Evaluate a feature flag
tags:
- GO Feature Flag Evaluation API
/v1/flag/change:
get:
consumes:
- application/json
description: |-
Making a **GET** request to the URL `/v1/flag/change` will give you the hash of the current
configuration, you can use this hash to know if the configuration has changed.
parameters:
- description: The request will be processed only if ETag doesn't match.
in: header
name: If-None-Match
type: string
produces:
- application/json
responses:
"200":
description: Success
schema:
$ref: '#/definitions/controller.FlagChangeResponse'
"304":
description: 'Etag: \"117-0193435c612c50d93b798619d9464856263dbf9f\'
schema:
type: string
"500":
description: Internal server error
schema:
$ref: '#/definitions/modeldocs.HTTPErrorDoc'
security:
- ApiKeyAuth: []
summary: Endpoint to poll if you want to know if there is a configuration change
in the flags
tags:
- GO Feature Flag Evaluation API
/ws/v1/flag/change:
post:
consumes:
- application/json
description: |
This endpoint is a websocket endpoint to be notified about flag changes, every change
will send a request to the client with a model.DiffCache format.
parameters:
- description: apiKey use authorize the connection to the relay proxy
in: query
name: apiKey
type: string
produces:
- application/json
responses:
"200":
description: Success
schema:
$ref: '#/definitions/notifier.DiffCache'
"400":
description: Bad Request
schema:
$ref: '#/definitions/modeldocs.HTTPErrorDoc'
"500":
description: Internal server error
schema:
$ref: '#/definitions/modeldocs.HTTPErrorDoc'
summary: Websocket endpoint to be notified about flag changes
tags:
- GO Feature Flag Evaluation Websocket API
securityDefinitions:
ApiKeyAuth:
description: Use configured APIKeys in yaml config as authorization keys, disabled
when this yaml config is not set.
in: header
name: Authorization
type: apiKey
swagger: "2.0"