The Edge API is only available with on our SaaS platform. It does not form part of our Open Source project.
The Flagsmith Architecture is based around a server-side flag engine. This comes with a number of benefits, but it can increase latency, especially when the calls are being made from a location that is far from the EU; the location of our current API. It also provides a single point of failure in the event of an AWS region-wide outage.
The Edge API solves both of these issues. It provides a datastore and Edge compute API that is replicated across 8 AWS regions, with latency-based routing and global failover in the event of a region outage.
The Edge API provides API service from the following AWS regions:
- Europe (London) - eu-west-2
- US East (Ohio) - us-east-2
- US West (N. California) - us-west-1
- Asia Pacific (Mumbai) - ap-south-1
- Asia Pacific (Sydney) - ap-southeast-2
- South America (São Paulo) - sa-east-1
- Asia Pacific (Seoul) - ap-northeast-2
- Asia Pacific (Singapore) - ap-southeast-1
Enabling the Edge API
Existing Organisations created before 7th June 2022 have their Projects deployed to the Core API. You can migrate your Project over to our Edge API by going to the Project Settings page and hitting the "Start Migration" button. The migration will take between 1 minute and an hour depending on how many Identities your Project has.
The Core API will continue to work normally during and following the migration. See the Migration Steps for more info.
Once you have had your Projects migrated to Edge, all you will need to do is point your SDK to a new Flagsmith Edge API
edge.api.flagsmith.com. This domain points to our Edge CDN. That's it!
The easiest way to do this is to upgrade to the latest version of the Flagsmith SDK for your language.
If you are unable to upgrade, you can manually point the existing SDK to the Edge API endpoint. So for example, in the
Java SDK we just add the
FlagsmithClient flagsmithClient = FlagsmithClient.newBuilder()
Note that the Edge API URL is:
Check the docs for your language SDK on how to override the endpoint URL prefix.
The migration process will carry out a one-way sync of your
Identity data, from the Core API to the Edge API. All your
Identity data will continue to exist within the Core API, and you can continue to write
Identities to the Core API
if you wish.
The goal is to get all of your applications running against the Edge API, where you will benefit from global low latency as well as multi-region failover and fault tolerance.
Step 1 - Prepare your applications
Set your applications up to point to the Flagsmith Edge API. This means going from
edge.api.flagsmith.com. You can either set this explicitly in our SDK or just ensure you are running the latest
version of the SDK; by default the latest version of the SDKs will point to
Step 2 - Migrate your data
You can now trigger a one-way sync of data for each of your Flagsmith Projects within the Flagsmith Dashboard. You can migrate your Project over to our Edge API by going to the Project Settings page and hitting the "Start Migration" button. This will start a job that can take between 1 minute and 1 hour, depending on how much data you have. Once the job is complete, all the Identities that were present in your Core API will be present in the Edge API.
The Core API will continue to work normally during and following the migration.
If you have a product like a mobile app, where you cannot immediately force your users to upgrade (as opposed to a web app, for example), you will likely generate Identity writes to the old Core API.
Following and during the migration, if we receive a request to an
Identity endpoint that results in a write to the
core API, we will persist the data in the Core API and replay the request into the Edge API. You can then update your
API endpoints/SDKs in your own time to gradually move over the Edge API. This will give you time to migrate your users
over to the new version of your application.
Note that writes to the Core API will still work into the future, but the data will not be synchronised across the two platforms (Core and Edge).
Step 3 - Deploy your applications
Once your data has been copied onto the Edge API datastore, you can now deploy your applications that point to the new
edge.api.flagsmith.com and benefit from global low latency!
Things you should know
Some of the secure Identity endpoints have changed
If you are using our REST API to manipulate/update/list your Identities, some of these endpoints have changed. Please get in touch if you need any help related to this.
New Identity Overrides will only apply to the Edge API
After the migration, any new Identity Overrides you apply to flag values for specific Identities will only be applied to the Edge API.
Increment and Decrement endpoints are deprecated
You probably didn't know these existed though, right?
Bulk Trait endpoint is deprecated
But you can still achieve the same functionality using our POST /identities endpoints.
The API responses have been slimmed down
Our core API responses are quite verbose, and the SDKs ignore a lot of the fields they receive. We've taken the opportunity to remove these additional, unused fields. This wont affect the SDKs but if you are using these values via the REST API, things have changed. The list of removed fields is as follows:
Core API Only
Core and Edge API
How It Works
Our core Rules Engine has been factored out of our REST API. This
allows us to use it as a dependency within both the Flagsmith API, but also within a set of Lambda functions that
service SDK API calls. You can point your SDK clients to our global CDN
edge.api.flagsmith.com which will serve your
request using a Lambda function running in an AWS data-centre near your client. This is how we reduce latency!
DynamoDB Global Tables
We store state within our API - both related to the Environments for your Projects, but also for the Identities within those Environments. Our Edge design sees us write this data through to DynamoDB global tables, which are replicated globally. Our Lambda functions then connect to the nearest DynamoDB table to retrieve both Environment and Identity data.