Self-Hosted API

Introduction

The Self-Hosted API is a standalone release of our Decision API that enables you to host the Decision API inside your own infrastructure. It enables you to host the decision part of the Decision API alongside your servers, thus decreasing response time. The data collection part of the Flagship platform is still hosted on our side, and the Self-Hosted API just relay the hit tracking calls to our own cloud-hosted data collection.

How does it work?

The Self-Hosted API uses the Go SDK internally in bucketing mode to synchronize the use cases with the Flagship platform. The decision logic (context targeting & visitor assignments) is done locally, which makes it really fast.

Here is a high level overview of the Self-Hosted API architecture:

1012

Why use the Self-Hosted API

The Self-Hosted API is a relevant infrastructure choice if:

  • You want a very low latency when calling the API (<10ms)

  • You do not want to use the SDK with the bucketing mode for any reason (like not wanting to add a third-party dependancy to your stack)

Caveats

Visitor assignments caching

Thanks to our hashing algorithm, a unique visitor (with a unique ID) will always see the same variation of a campaign, if the traffic allocation of the variations stays the same. If you're using a high level Flagship feature such as Experience Continuity, 1 visitor 1 experiment or Dynamic Allocation, or if you manually change the traffic allocation of your variations, the hashing algorithm is not enough. You need some sort of assignment cache to store the visitor assignment to the variation. Flagship cloud-hosted Decision API provides such a caching mechanism for you by default using our own high-velocity key-value store.

If you want to use those features with the Self-Hosted API, you need to configure your own cache to store visitor assignments. See the Configuration below to set it up.

Installation

The Flagship Self-Hosted API can be installed and deployed in your infrastructure either by downloading and running the binary, or pulling and running the docker image in your orchestration system

Using a binary

You can download the latest binary here: https://github.com/flagship-io/self-hosted-api/releasesarrow-up-right

Using a Docker image

You can pull the latest docker image from docker hub: docker pull flagshipio/self-hosted-api:latest

Running

Using a binary

Download the latest release on github and then simply run:

ENV_ID={your_environment_id} API_KEY={your_api_key} ./app

The server will run on the port 8080 by default. You can override this configuration (see Configuration)

Running with Docker

Run the following command to start the server with Docker

docker run -p 8080:8080 -e ENV_ID={your_env_id} -e API_KEY={your_api_key} flagshipio/self-hosted-api

Configuration

You can configure the self-hosted Decision API using 2 ways:

  • YAML configuration file

  • Environment Variables

Using a configuration file

Create a config.yaml along your app file, or mount it in docker in location /config.yaml:

docker run -p 8080:8080 -v ./config.yaml:/config.yaml flagshipio/self-hosted-api

The configuration file should look like this:

Using environment variables

You can override each configuration variables from the configuration file using environment variables. Just name your env variables the same as the config file, but with the following rules:

  • Env variable name should be UPPERCASE Example: ENV_ID

  • Sub configuration level are defined using a _ sign Example: CACHE_TYPE Example: CACHE_OPTIONS_DBPATH

Here is a Docker example using environment variables to setup local caching:

docker run -p 8080:8080 -e ENV_ID={your_env_id} -e API_KEY={your_api_key} -e CACHE_TYPE=local -e CACHE_OPTIONS_DBPATH=./data -v ./config.yaml:/config.yaml flagshipio/self-hosted-api

Here is a Docker Compose example of using Redis as a visitor cache engine:

Configuration parameters

You can use the following parameters to customize the Self Hosted API. Each parameter is named as in the config.yaml file, and the matching environment variable is parenthesis.

Parameter
Type
Required
Description

env_id (ENV_ID)

string

yes

The Flagship environment ID. You can get it from the Flagship platform. Default to empty string

api_key (API_KEY)

string

yes

The Flagship API Key for this environment ID. You can get it from the Flagship platform. Default to empty string

polling_interval (POLLING_INTERVAL)

int

no

The polling frequency (in seconds) to synchronize with your Flagship configuration. Default to 60

cache.type (CACHE_TYPE)

string

no

If you want to enable caching for the visitor assignment. Can be "redis" or "local". Default to empty string.

cache.options.dbPath (CACHE_OPTIONS_DBPATH)

string

no

If you chose local cache type, this is the path of the file where the cache will be stored. Default to empty string

cache.options.redisHost (CACHE_OPTIONS_REDISHOST)

string

no

If you chose redis cache type, this is the host for your redis server

cache.options.redisUsername (CACHE_OPTIONS_REDISUSERNAME)

string

no

If you chose redis cache type, this is the username for your redis server

cache.options.redisUsername (CACHE_OPTIONS_REDISPASSWORD)

string

no

If you chose redis cache type, this is the password for your redis server

cache.options.redisDb (CACHE_OPTIONS_REDISDB)

int

no

If you chose redis cache type, this is the db number for your redis server. Default to 0 (default DB)

API Reference

The Self-Hosted API has the same relative endpoints than the cloud-base Decision API V2 (latest)arrow-up-right . The only difference is that you do not need to put your environment ID inside the URL path (because the environment ID is already configured when starting the Self-Hosted API).

So instead of calling https://decision.flagship.io/v2/{{YOUR_ENVIRONMENT_ID}}/campaigns

You would call https://your.selfhosted.api.instance/v2/campaigns

You can find the Swagger API doc at the /swagger/index.html URL when running the application.

Last updated

Was this helpful?