Evaluation API

The Evaluation API is the primary component of OpenFeature that application authors interact with. The Evaluation API allows developers to evaluate feature flags to alter control flow and application characteristics.

Setting a Provider

Before you can start evaluating flags, you must set a provider. The provider is the translation layer between the evaluation API and the flag system you use.

TypeScript

import { OpenFeature } from '@openfeature/server-sdk';

OpenFeature.setProvider(new YourProviderOfChoice());

Java

import dev.openfeature.sdk.OpenFeatureAPI;

OpenFeatureAPI api = OpenFeatureAPI.getInstance();
api.setProvider(new YourProviderOfChoice());

C#

using OpenFeature;

Api.Instance.SetProvider(new YourProviderOfChoice());

Go

openfeature.SetProvider(MyFeatureProvider{})

PHP

use OpenFeature\OpenFeatureAPI;

OpenFeatureAPI::getInstance()->setProvider(new YourProviderOfChoice());

Python

import openfeature.api

openfeature.api.set_provider(YourProviderOfChoice())

Some providers need to establish connections, load flag data, or validate configuration before they can resolve flags accurately. If your SDK exposes a blocking or awaitable registration method, use it during startup when your application needs to avoid default values while the provider initializes. If you register the provider asynchronously, attach event handlers for PROVIDER_READY and PROVIDER_ERROR so your application can react when initialization succeeds or fails. See Events for language-specific handler examples.

Creating a client

The OpenFeature client is a lightweight abstraction used to evaluate feature flags. If your application is small, you may use a single client for your whole application. In larger applications, it may be helpful to create multiple clients, each with different configuration to fit the needs of different sub-modules. Clients may also be created dynamically, per each HTTP request, for instance.

TypeScript

const client = OpenFeature.getClient('my-app');

Java

Client client = api.getClient("my-app");

C#

var client = Api.Instance.GetClient("my-app");

Go

client := openfeature.NewClient("my-app")

PHP

$client = OpenFeatureAPI::getInstance()->getClient("my-app");

Python

import openfeature.api

openfeature.api.get_client("my-app")

Flag Evaluation

Basic Evaluation

The client can be used to do basic flag evaluation, which simply returns flag values of a particular type. The default value must also be specified. In the case of any error during flag evaluation, the default value will be returned, so give consideration to your default values!

TypeScript

// get a bool value
const boolValue = await client.getBooleanValue('boolFlag', false);

// get a string value
const stringValue = await client.getStringValue('stringFlag', 'default');

// get an numeric value
const numberValue = await client.getNumberValue('intFlag', 1);

// get an object value
const object = await client.getObjectValue<MyObject>('objectFlag', {});

Java

// get a boolean value
Boolean boolValue = client.getBooleanValue("boolFlag", false);

// get a string value
String stringValue = client.getStringValue("stringFlag", "default");

// get an integer value
Integer intValue = client.getIntegerValue("intFlag", 1);

// get a double value
Double doubleValue = client.getDoubleValue("doubleFlag", 0.9);

// get an object value
Value objectValue = client.getObjectValue("objectFlag", MyObjectInstance);

C#

// get a boolean value
var boolValue = await client.GetBooleanValue("boolFlag", false);

// get a string value
var stringValue = await client.GetStringValue("stringFlag", "default");

// get an integer value
var intValue = await client.GetIntegerValue("intFlag", 1);

// get an double value
var doubleValue = await client.GetDoubleValue("doubleFlag", 1);

// get an object value
var objectValue = await client.GetObjectValue("objectFlag", MyObjectInstance);

Go

// get a boolean value
boolValue, err := client.BooleanValue(context.Background(), "boolFlag", false, openfeature.EvaluationContext{})

// get a string value
stringValue, err := client.StringValue(context.Background(), "stringFlag", "default", openfeature.EvaluationContext{})

// get an integer value
intValue, err := client.IntValue(context.Background(), "intFlag", 1, openfeature.EvaluationContext{})

// get a float value
floatValue, err := client.FloatValue(context.Background(), "floatFlag", 3.14, openfeature.EvaluationContext{})

// get an object value
objectValue, err := client.ObjectValue(context.Background(), "objectFlag", myObject, openfeature.EvaluationContext{})

PHP

// get a boolean value
$boolValue = $client->getBooleanValue("boolFlag", false, null, null);

// get a string value
$stringValue = $client->getStringValue("stringFlag", "default", null, null);

// get an integer value
$intValue = $client->getIntegerValue("intFlag", 1, null, null);

// get a float value
$floatValue = $client->getFloatValue("floatFlag", 0.9, null, null);

// get an object value
$objectValue = $client->getObjectValue("objectFlag", $myObjectInstance, null, null);

Python

# get a boolean value
value = client.get_boolean_value("boolFlag", False)

# get a string value
value = client.get_string_value("stringFlag", "default")

# get an integer value
value = client.get_integer_value("intFlag", 1)

# get a float value
value = client.get_float_value("floatFlag", 0.9)

# get an object value
value = client.get_object_value("objectFlag", my_object_instance)

Detailed Evaluation

In addition to basic evaluation, detailed evaluation methods are available. These return the value, as well as additional metadata about the flag evaluation in the Evaluation Details structure.

Evaluation Details Structure Fields

Field	Description
flag key	the unique identifier for a feature flag
value	the value returned from a flag evaluation
reason (optional)	a string explaining why the flag value was returned
variant (optional)	the variant associated with the return flag value
flag metadata (optional)	a key-value structure which supports definition of arbitrary properties
error code (optional)	an error code that categorizes flag evaluation errors
error message (optional)	a string detailing the error

TypeScript

// get details of boolean evaluation
const boolDetails = await client.getBooleanDetails('boolFlag', false);

// get details of string evaluation
const stringDetails = await client.getStringDetails('stringFlag', 'default');

// get details of numeric evaluation
const numberDetails = await client.getNumberDetails('intFlag', 1);

// get details of object evaluation
const objectDetails = await client.getObjectDetails<MyObject>('objectFlag', {});

Java

// get details of boolean evaluation
FlagEvaluationDetails<Boolean> boolDetails = client.getBooleanDetails("boolFlag", false);

// get details of string evaluation
FlagEvaluationDetails<String> stringDetails = client.getStringDetails("stringFlag", "default");

// get details of integer evaluation
FlagEvaluationDetails<Integer> intDetails = client.getIntegerDetails("intFlag", 1);

// get details of double evaluation
FlagEvaluationDetails<Double> doubleDetails = client.getDoubleDetails("doubleFlag", .9);

// get details of object evaluation
FlagEvaluationDetails<Value> objectDetails = client.getObjectDetails<MyObject>("objectFlag", myObjectDefaultInstance);

C#

// get details of boolean evaluation
var boolDetails = await client.GetBooleanDetails("boolFlag", false);

// get details of string evaluation
var stringDetails = await client.GetStringDetails("stringFlag", "default");

// get details of int evaluation
var intDetails = await client.GetIntegerDetails("intFlag", 1);

// get details of double evaluation
var doubleDetails = await client.GetDoubleDetails("doubleFlag", 1);

// get details of object evaluation
var objectDetails = await client.GetObjectDetails("objectFlag", myObjectDefaultInstance);

Go

// get details of boolean evaluation
boolDetails, err := client.BooleanValueDetails(context.Background(), "boolFlag", false, openfeature.EvaluationContext{})

// get details of string evaluation
stringDetails, err := client.StringValueDetails(context.Background(), "stringFlag", "default", openfeature.EvaluationContext{})

// get details of integer evaluation
intDetails, err := client.IntValueDetails(context.Background(), "intFlag", 1, openfeature.EvaluationContext{})

// get details of float evaluation
floatDetails, err := client.FloatValueDetails(context.Background(), "floatFlag", 3.14, openfeature.EvaluationContext{})

// get details of object evaluation
objectDetails, err := client.ObjectValueDetails(context.Background(), "objectFlag", myObject, openfeature.EvaluationContext{})

PHP

// get details of a boolean evaluation
$boolDetails = $client->getBooleanDetails("boolFlag", false, null, null);

// get details of a string evaluation
$stringDetails = $client->getStringDetails("stringFlag", "default", null, null);

// get details of an integer evaluation
$intDetails = $client->getIntegerDetails("intFlag", 1, null, null);

// get details of a float evaluation
$floatDetails = $client->getFloatDetails("floatFlag", 0.9, null, null);

// get details of an object evaluation
$objectDetails = $client->getObjectDetails("objectFlag", $myObjectInstance, null, null);

Python

# get details of boolean evaluation
details = client.get_boolean_details("boolFlag", false);

# get details of string evaluation
details = client.get_string_details("stringFlag", "default");

# get details of an integer evaluation
details = client.get_integer_details("intFlag", 1);

# get details of a float evaluation
details = client.get_float_details("floatFlag", 1);

# get details of object evaluation
details = client.get_object_details("objectFlag", {});

API Shutdown

The OpenFeature API can shut down all registered providers so they can release connections, background workers, file watchers, or other resources. Call this from your application shutdown path after you stop evaluating flags. The method name varies by SDK; use the shutdown or close function documented by the SDK you are using.

TypeScript

import { OpenFeature } from '@openfeature/server-sdk';

await OpenFeature.close();

Java

import dev.openfeature.sdk.OpenFeatureAPI;

OpenFeatureAPI.getInstance().shutdown();

Python

from openfeature import api

api.shutdown()