Before the “Edge,” we need to be sure about the “API.”

A waiter between two worlds

An API, short for application programming interface, is a set of rules that lets one piece of software ask another piece of software for something. You never see it directly, yet you use APIs all day. When a weather app shows tomorrow’s forecast, it has asked a weather service for the numbers through an API.

Requests and responses

Almost every API works as a conversation of two messages. Your software sends a request, which says what it wants and who it is. The service sends back a response, which carries the answer or an explanation of why it cannot answer. Each request travels across the internet in small pieces called packets, and each trip takes time.

Where feature flags come in

A feature flag is a switch in your software that decides whether a feature is visible. A remote config value is a similar idea, but the switch holds a number or some text instead of a simple on or off. Flagsmith stores these switches and their rules. Your app does not hold the answers. It asks Flagsmith, through an API, “What are the flags for this user right now?”

That question is asked often. A busy app may ask it every time a user opens the app, loads a page or starts a session. Because it sits right at the start of the user’s experience, this API must be quick and it must almost never fail.

A short definition, then the reasons behind it.

The definition

The Flagsmith Edge API is the version of the Flagsmith flag-serving API that runs at many locations around the world, close to your users. It is the part of Flagsmith that your SDKs talk to when they ask for flags, identities and traits. An SDK is a ready-made code library that your app uses so it does not have to speak the raw API language itself.

On Flagsmith’s hosted cloud service, SDKs are normally pointed at the edge servers by default. You often use it without choosing it. Setting up an SDK with an environment key and keeping the default address is usually all it takes.

The word “edge”

In computing, the edge means the places nearest to the people using a service, as opposed to the central data centre where the main system lives. A service “at the edge” has been spread out to many such nearby places. You may already know the idea from content delivery networks, which keep copies of images and videos near viewers so pages load quickly.

What it does and does not do

The Edge API focuses on serving flags quickly. It answers questions from your apps, using stored copies of your settings. It is not where your team edits flags. Editing happens in the Flagsmith dashboard and the management API, which talk to the central part of the system, commonly called the core. Keeping serving separate from editing is the main design idea behind the whole thing.

It is also worth knowing that the Edge API is a feature of Flagsmith’s hosted offering. If you run Flagsmith on your own servers, you reach for different tools to get similar speed, and a later chapter explains them. As details can change between versions and plans, always confirm current behaviour in the official documentation for your setup.

One picture holds the whole story.

flowchart LR
  Admin["Product Manager in Dashboard"] --> Core["Flagsmith Core API and Database"]
  Core -->|"publishes changes"| Store["Replicated Edge Data Store"]
  Phone["Mobile App SDK"] --> E1["Edge API: nearest location"]
  Web["Web App SDK"] --> E1
  Server["Backend Service SDK"] --> E1
  E1 --> Store

Reading the picture

On the left sits a person changing a flag in the dashboard. That change goes to the core, which is the central system with the main database, the permission checks and the audit log. The core is built for correctness and rich features. Once the change is safely saved, the core publishes the new settings to a replicated edge data store, which is a database whose contents are copied to several regions.

On the right, three kinds of apps ask for flags: a phone app, a website and a backend service. All of them talk to the edge location nearest them. That location reads the settings from the replicated store, works out the answer, and replies. The core is not involved in that reply at all.

Why this split is clever

Editing flags happens a few times an hour. Reading flags happens thousands or millions of times a minute. These are two very different workloads. A system that tries to do both in one place must be a compromise. Splitting them lets each half be built for its own job. The core can focus on safety and detail. The edge can focus on speed and simplicity.

Even the fastest software cannot beat the speed of light.

Latency in one sentence

Latency is the time between asking for something and starting to receive the answer. Low latency feels instant. High latency feels sluggish. Users rarely say “the latency is high.” They say “this app feels slow,” and then they leave.

A back-of-the-envelope calculation

Signals in optical fibre travel at roughly two hundred thousand kilometres per second, which is about two thirds of the speed of light in empty space. The distance from India to the east coast of the United States is roughly twelve thousand kilometres. A request must go there and the answer must come back, so the signal covers about twenty-four thousand kilometres. Dividing gives about 0.12 seconds, or around 120 milliseconds, and that is the absolute minimum, before any computer does any work.

Real internet routes are longer than straight lines, and every router and server adds a small delay. A real round trip over that distance is often considerably longer. Now remember that opening a connection takes several back-and-forth messages. A single flag request from a far-away app can easily cost a noticeable fraction of a second. If the same app asks a server in its own region, the physics cost drops to a few milliseconds.

Why flags are especially sensitive

Many requests can happen in the background while the user does something else. A flag request is different. Often the screen cannot decide what to draw until it knows the flags. If your app waits for a slow answer, one of two bad things happens: the user sees a blank spinner, or the app shows the default version and then suddenly switches to the new one, causing a visible flicker. Both feel unpolished. Fast answers prevent both.

The business angle

Large online companies have shared results from experiments showing that extra delays reduce engagement and purchases. Even without exact figures, the direction is clear and consistent: slower pages, fewer completed actions. A flag service sits in the path of almost every page, so keeping it fast is a small investment that protects a large part of the experience.

Six ideas appear in nearly every Edge API conversation.

Two kinds of keys

Flagsmith uses two kinds of environment keys. A client-side key is designed to be placed in code that runs on a user’s device, such as a website or mobile app. Because anyone can look inside such code, this key is treated as public. It can only be used to read flags for that environment. A server-side key is secret and is meant only for your own backend servers. It can do more, such as reading the full environment settings for local evaluation. Never put a server-side key into code that reaches users’ devices.

How a flag gets decided

When the Edge API receives a question, it follows a short list of steps. It finds the environment from the key. It looks at the default value of each flag. It checks whether any segment rules match the user. It checks whether any specific override applies to this exact user. The most specific rule wins. The result is a clear list: each flag, whether it is enabled, and any value attached to it.

The same list of steps is used everywhere in Flagsmith. This matters because it means the answer from the Edge API, from the core, and from an SDK doing local evaluation should agree for the same inputs.

Follow a single question from your app to the answer and back.

sequenceDiagram
  participant A as App with SDK
  participant R as Global Router
  participant E as Edge API Node
  participant D as Edge Data Store
  A->>R: Request flags with environment key
  R->>E: Route to nearest healthy location
  E->>D: Load environment settings and identity data
  D-->>E: Return stored data
  E->>E: Evaluate rules, segments and overrides
  E-->>A: Return flags and values

Step by step

Why stateless nodes are a gift

A stateless service holds no private memory of earlier requests. Everything it needs comes either with the request or from the shared data store. That design makes scaling easy: if traffic doubles, more copies are started, and any copy can answer any request. If one copy fails, the next request simply goes to another copy, and nobody notices.

Why the core is not in the path

Notice that the core never appears in Figure 2. This is deliberate. If every flag request needed the core, then the core would be the bottleneck, and a problem there would hurt every user everywhere. By answering from copied data, the edge keeps working even if the core is slow, busy or briefly unavailable. The people editing flags may be inconvenienced, but the people using your app are not.

The edge answers from copies, so copies must stay fresh.

flowchart TD
  A["Someone saves a flag change"] --> B["Core API validates and stores it"]
  B --> C["Audit log entry written"]
  B --> D["Background task prepares environment document"]
  D --> E["Write to edge data store"]
  E --> F["Replicate to other locations"]
  F --> G["Edge API serves new value"]
  G --> H["SDK picks it up on next request or update"]

The journey in plain words

When a product manager flips a flag, the core first checks that the person is allowed to, validates the change and saves it in its main database. It also writes an entry in the audit log, the diary of who changed what. Then a background task takes the relevant settings and builds an environment document. That is a compact bundle holding everything needed to answer flag questions for one environment: its flags, their values, segments and rules.

The bundle is written into the edge data store, which then copies it to other regions. From that moment, edge nodes reading from the store will use the new version. The final step is on the app’s side: the SDK sees the new value the next time it asks, or sooner if real-time updates are in use.

Eventual consistency, explained gently

Copying data to many places takes a short time. During that short time, one location may already show the new value while another still shows the old one. This situation is called eventual consistency: the copies are not identical at every instant, but they will become identical soon without anyone intervening. In everyday conditions, the gap is brief, often a matter of seconds, but you should not design anything that needs every user on Earth to see a change at exactly the same millisecond.

Why this trade is usually worth it

For flags, a gap of a few seconds almost never matters. If you roll out a feature to ten percent of users, it makes no difference whether it started at 14:15:00 or 14:15:04. In return, you get flag answers that are fast everywhere and that keep working during trouble at the core. Engineers call this choosing availability and speed over perfect instant agreement, and for read-heavy data like flags, it is the sensible choice.

What about the dashboard?

The dashboard reads from the core, so it shows the saved change immediately. You may therefore see the new value in the dashboard a moment before your own test app sees it. If your test seems to disagree with the dashboard, wait a few seconds and ask again before assuming something is broken.

Per-user answers need per-user data, and that data must be nearby too.

Two kinds of questions

An app can ask two kinds of questions. The first is “What are the flags for this environment?” That answer is the same for everyone, so it depends only on the environment settings. The second is “What are the flags for this particular user?” Now the answer may depend on who the user is, what traits they have, which segments they fall into, and whether a special override exists for them.

To answer the second kind quickly, the Edge API needs the identity’s data close at hand. That is why identities and their traits are stored in the edge data store as well, and not only in the core. When a user’s traits are sent along with the request, the edge can store them and use them straight away.

What traits are good for

Traits turn raw user facts into useful decisions. A trait called “plan” with the value “premium” lets you show an advanced feature only to premium users. A trait called “app version” lets you hide a feature from an old version that cannot display it. A trait called “country” lets you switch on a feature only where it is legal or ready. Because the data lives at the edge, these decisions need no extra trips.

How segments use traits

A segment is defined by rules over traits, for example “plan equals premium and country equals India.” When the edge node receives a user’s traits, it checks them against every segment rule for the environment and finds which segments match. If a flag has a different value for a matching segment, that value is used. If more than one segment matches, the order of priority you set decides the winner.

Percentage rollouts and fairness

Many teams roll features out to a percentage of users, such as five percent, then twenty-five, then everyone. For this to feel fair, the same user must always land on the same side of the split. Otherwise a person could see the new feature on one visit and not on the next. Flagsmith handles this by turning each user’s ID into a stable number, using a mathematical function that always gives the same output for the same input, and comparing that number with your percentage. The result is steady and repeatable, and it is the same regardless of which edge location answers.

Be careful what you store

Traits are convenient, but anything you send is stored. Avoid placing secrets or sensitive personal details in traits. Names, emails and payment details almost never belong there. Use internal IDs and coarse facts such as a plan name or a region. This habit is covered further in the security chapter.

The SDK is the polite messenger standing between your app and the service.

Client-side and server-side SDKs

Flagsmith offers SDKs for many languages. They fall into two broad kinds. Client-side SDKs run in places users control, such as a web browser or a phone. They usually ask the Edge API for the flags of one user at a time and hold the result in memory. Server-side SDKs run in your own backend. They can either ask the Edge API on each request, which is called remote evaluation, or download the whole environment document and decide on their own machine, which is local evaluation. Both approaches are valid. They simply trade freshness, speed and cost differently.

What a good SDK does for you

• Attaches the key and identity to each request so you do not have to.
• Holds a short-lived copy in memory so your code can check a flag many times without repeated network calls.
• Provides default values that your code can fall back on if the network is not available.
• Can refresh periodically or listen for live updates, so long-running apps stay current.
• Can report usage of flags, so you see which are actually used.

Real-time updates

Some SDKs can keep a lightweight connection open so that Flagsmith can announce a change the moment it happens, instead of waiting for the next time the app asks. The technique used is often server-sent events, a simple standard where a server pushes small messages down a connection that stays open. This is helpful for web apps that stay open for hours, because a flag change can take effect without a page refresh. Availability and setup differ between SDKs, so check the documentation for yours.

Why your own defaults matter

A default value is what your code uses when it cannot get an answer. Picking it well is one of the most important decisions in using flags. As a rule, the default should be the safe, stable behaviour, usually “feature off.” If the network fails, users see the old, well-tested version instead of an unfinished feature. The chapter on reliability returns to this idea, because it is the foundation of graceful failure.

Three ways to get flag answers fast, and when each one fits.

Option one: remote evaluation through the Edge API

This is the default path. Your app asks the Edge API, which decides and replies. It is simple, always fresh within the short copying delay, and works well for browsers and phones. The cost is one network trip per refresh, which the edge design keeps small.

Option two: local evaluation in a server SDK

A backend service can download the whole environment document once, keep it in memory, and decide for every user on its own, with no network call at all. The SDK refreshes the document on a timer, commonly measured in tens of seconds. The benefit is extremely fast decisions and far fewer requests. The cost is that changes appear only when the next refresh happens, and this approach needs a secret server-side key, so it is only for trusted backends.

Option three: the Edge Proxy for self-hosted setups

If you run Flagsmith on your own servers, you do not get Flagsmith’s global edge locations. Flagsmith provides an open-source component called the Edge Proxy that you place near your applications. It holds a cached copy of the environment documents and answers SDK requests itself, asking the main Flagsmith server only now and then for updates. This takes load off your main installation and puts the answers closer to your apps.

flowchart TD
  Q["Where does your app run?"] --> A{"Using Flagsmith cloud?"}
  A -->|"Yes"| B{"Need freshest answer per user?"}
  B -->|"Yes"| E["Use Edge API with remote evaluation"]
  B -->|"No, trusted backend"| L["Consider local evaluation in server SDK"]
  A -->|"No, self-hosted"| P["Use Edge Proxy near your apps"]

Mixing approaches

Nothing forces you to choose only one. A common pattern is local evaluation in the busiest backend services and remote evaluation through the edge for browsers and phones. All of them read the same environment settings and use the same decision steps, so a user sees consistent behaviour no matter which route answered.

One honest caution: local evaluation cannot always replicate every feature in exactly the same way, for example when identity data lives only at the service. Check the documentation of your SDK for any listed differences before relying on it for a special case.

What “fast” means, and how the edge stays fast when traffic explodes.

Three numbers worth knowing

Latency is how long one request takes. Throughput is how many requests are handled each second. Tail latency is the time experienced by the slowest few requests, often described as the ninety-ninth percentile, which means only one request in a hundred is slower. Averages hide pain. A service with a great average and a terrible tail still makes some users miserable, so mature teams watch the tail.

How the edge keeps latency low

• Nearby servers cut the physics cost of travel.
• Small, focused work: the edge does one job and does not carry the weight of the whole dashboard.
• Data already in place: no long calls back to a central database.
• In-memory evaluation: rule checks are quick computations.
• Connection reuse: modern SDKs and servers keep connections open so later requests skip the setup handshake.

How it scales up

Because edge nodes are stateless, horizontal scaling works well. That means adding more identical copies instead of making one copy bigger. When traffic spikes, such as a marketing email that sends a million people to your app within minutes, the platform starts more copies to share the load. When traffic falls, the extra copies are removed. You do not need to forecast the spike or buy hardware in advance.

The cold start question

Systems that start copies on demand can suffer a cold start, a small extra delay the first time a fresh copy handles a request, because it must load itself first. Providers work hard to keep this small, and steady traffic keeps copies warm. As an app developer, you cannot control it directly, but you can protect your users from it by caching flags on the client and by never blocking the whole screen on a single flag call.

What you can do on your side

• Ask for flags once per session or page load, then reuse the answer in memory.
• Avoid calling the API inside loops or on every small user action.
• Use client-side caching so repeated app launches show something immediately.
• Prefer one request that returns all flags over many requests that return one flag each.
• For busy backends, consider local evaluation to avoid network calls entirely.

Plan for the day something goes wrong, because that day always comes.

What availability means

Availability is the share of time a service works when you need it. People often describe it in “nines.” Ninety-nine point nine percent allows roughly nine hours of downtime in a year. Ninety-nine point nine nine percent allows under an hour. Each extra nine is much harder and costlier to achieve. Spreading a service across many locations is the classic way to reach more nines, because one failure no longer takes everything down.

How the edge design helps

The edge has no single front door. Requests are routed to nearby locations, and unhealthy locations can be skipped. Data is replicated, so a lost copy can be replaced from another. Nodes are stateless, so a crashed node leaves nothing behind that needs repairing. The core, which is more complex, sits out of the request path, so its problems do not become your users’ problems.

Designing your app for graceful failure

No service promises perfection, so well-built apps expect occasional failures and handle them quietly. The diagram below shows the flow a careful SDK and app follow whenever they need a flag.

flowchart TD
  S["App needs a flag"] --> C{"Cached value available?"}
  C -->|"Yes and fresh"| U["Use cached value"]
  C -->|"No or stale"| N["Call Edge API"]
  N --> OK{"Call succeeded?"}
  OK -->|"Yes"| V["Use and cache fresh value"]
  OK -->|"No"| R{"Retry allowed?"}
  R -->|"Yes"| N
  R -->|"No"| D["Use default flag value"]

Reading the flow

If a fresh answer is already in memory, use it and make no call at all. If not, ask the Edge API. If that works, use the answer and save it. If it fails, retry a limited number of times, waiting a little longer between attempts, an approach called backoff that prevents a struggling service from being flooded by eager retries. If everything fails, use the default you chose in advance. The user sees a working app, perhaps with an older version of a feature, rather than an error.

Offline and degraded modes

Some SDKs support saving flag data to local storage or reading it from a file, so apps can start even with no network, and some provide an offline mode designed for testing and for environments cut off from the internet. When your app must work on aeroplanes, in basements or in remote locations, these features are worth learning. Details differ by language, so read your SDK’s guide.

Blast radius

The blast radius of a failure is how much it affects. The edge design shrinks it: a problem in one location affects only that location’s traffic, and a problem in the core affects only editing. Good flag habits shrink it further, because a bad feature can be switched off in seconds, without a new release.

A fast front door is only useful if it has a good lock.

Keys and their reach

Security starts with the two kinds of keys from Chapter 5. A client-side key can sit in public code, so it must be capable of reading flags only. A server-side key is secret and powerful. Store it in a secrets manager or in protected environment settings, never in a code repository, a chat message or a mobile app. If a secret key is ever exposed, create a new one and retire the old one at once.

Encryption in transit

Requests to the Edge API travel over HTTPS, which scrambles the conversation so that anyone listening on the network sees only noise. Keep your SDK settings on the secure address, and never switch to plain, unencrypted connections to “make debugging easier.”

Browser rules, briefly

Web browsers have a safety rule called CORS, which stands for cross-origin resource sharing. It decides whether a page from one website may call a service on another. The Edge API is built to be called from browsers, but if your own proxy or gateway sits in front of it, you must configure it to allow your website’s address. A page that suddenly cannot load flags and shows a CORS message in the browser console is the classic sign.

What data leaves your walls

When you send an identity and its traits to the edge, you are sending information about your users to a third party and storing it in several regions. Follow data minimisation, which means sending only what you need. Prefer internal IDs over emails, and coarse facts like “plan” over detailed personal ones. Review your privacy policy and customer contracts, and consider whether any rules, such as the European Union’s GDPR, restrict where data may be stored. If you have strict regional rules, ask Flagsmith about regional options and about running it yourself.

Abuse and limits

Public endpoints invite abuse. Hosted services commonly apply rate limits, which cap how many requests one caller can make in a given time. A bug in your app, such as a loop that asks for flags thousands of times a second, can hit those limits and also inflate your costs. Another reason to cache sensibly.

You cannot improve what you cannot see.

Three kinds of signals

Metrics are numbers over time, such as requests per minute. Logs are text records of individual events. Traces follow one request through several services. Together they are called observability, and they let you answer questions about a system without guessing.

What to watch on your side of the fence

You cannot see inside Flagsmith’s edge machines, but you can measure how the edge behaves from your app’s point of view. These are the measures worth tracking:

Status pages and alerts

Hosted services publish a status page showing current incidents and past history. Subscribe your team to its notifications, and link it from your own runbook. Then create alerts in your own monitoring tool for flag call failures, so you hear about trouble from a graph before you hear it from customers.

Link flag changes to graphs

A strong habit is placing markers on your dashboards whenever a flag changes, using Flagsmith’s integrations with monitoring tools. When a graph suddenly jumps, a marker beside the jump saves valuable minutes. The Edge API is quick, but your own application behaviour is often the real cause of an incident, and flags are one of the most common triggers.

Define what “good” means

Write down a target such as “ninety-nine percent of flag requests finish in under 300 milliseconds from the user’s device, and fewer than one in a thousand falls back to a default.” A target turns vague feelings into something you can measure and discuss. Such targets are often called service level objectives, and they help teams decide when a problem is serious enough to wake someone at night.

Using the Edge API is mostly a matter of configuration, not construction.

Getting started in plain steps

Migrating older projects

Flagsmith has evolved over time. Older projects were created when the core served everything, and Flagsmith has offered a path to move such projects onto the edge so they benefit from the faster design. The move involves copying environment and identity data to the edge store. Treat it like any data migration: read the official migration notes, choose a quiet period, test with a non-production project first, and check that flags and identity overrides match afterwards. Ask Flagsmith support if you are uncertain, because the exact steps depend on your plan and history.

Environments and keys in practice

Use a separate environment, and therefore a separate key, for each stage. This keeps test flips away from real users. Name keys clearly in your own secrets store, such as “web-client-production,” so nobody uses the wrong one by accident. Rotate server-side keys on a schedule.

Self-hosted and private options

Some organisations cannot use a shared hosted service because of company rules or laws. Flagsmith can be run on your own infrastructure, and there are private hosted arrangements for larger customers. In such cases, you do not get the global edge in the same form, so plan for the Edge Proxy and local evaluation described earlier, and put the proxy in the same regions as your users and servers.

Habits that work well with an edge-served flag system, and habits that cause pain.

Patterns worth copying

Advantages and trade-offs of edge serving

Anti-patterns to avoid

A short, practical checklist drawn from everything so far.

Do these

• Choose safe defaults for every flag, and test the app with the network turned off.
• Use the right key in the right place: client-side keys in apps, server-side keys on servers only.
• Cache on the client and refresh on a sensible timer, measured in tens of seconds or minutes, not milliseconds.
• Set timeouts on every flag call so the screen never waits forever.
• Use stable user IDs so rollouts and overrides stay consistent.
• Keep traits small and non-sensitive.
• Watch the edge from your side with request time, error and fallback metrics.
• Retire old flags once a feature is fully released, to keep code clean.

Common mistakes and quick cures

When something looks wrong, check in a calm and predictable order.

The usual suspects

A calm order of checks

First, confirm the change exists: look at the dashboard and the audit log. Second, confirm you are asking the right environment with the right key. Third, wait a short moment and ask again, in case copying is not finished. Fourth, clear any caches in your app or test tool. Fifth, check the identity and traits you send, since segment rules rely on them. Sixth, look at the status page and your own network. Going through this order avoids jumping straight to blaming the service.

Test with a clean slate

When results are confusing, try a brand new test identity that has never been used, with only the traits you choose. If a clean identity behaves correctly, the problem is likely an old override or stored trait on the other identity. If a clean identity also behaves wrongly, the problem is in the environment settings or the key.

A fallback you have never tried is only a hope.

Why test the unhappy paths

Most people test that flags work when everything is fine. The real value lies in testing what happens when things are not fine: the network drops, the answer is slow, the key is wrong, or the service returns an error. Those are exactly the situations in which your safe defaults and timeouts are supposed to save you. If you have never seen your app handle them, you do not know whether it does.

A set of simple experiments

Test the rules, not just the switch

Segments and overrides are where subtle bugs hide. Create a few fake identities with different traits, such as a premium user, a free user and a user from a different country, and check each one receives the flags you expect. Keep these fake identities and their expected results written down, so you can repeat the check after changing rules.

Test the rollout split

When you plan a percentage rollout, confirm the behaviour on a small scale first. Use a handful of test IDs, check that each lands consistently on one side of the split, and verify that raising the percentage only adds users to the new group and never removes anyone who already had it.

Practice reversing a change

The greatest strength of flags is fast reversal. Practise it. During a calm hour, enable a harmless test feature, then switch it off, and time how long it takes for your test app to follow. Knowing this number in advance changes how you plan launches, because you understand how long the worst moment would last.

Automate what you can

Add a small automated test to your build process that starts the app with default flags and checks the main screens still work. A second test can use a test environment with a known set of flags. Automated checks catch accidents early, such as a developer removing a default or renaming a flag without noticing.

Every request has a price, even if it is small.

Why request counts matter

Hosted flag services commonly price their plans partly by how many requests you make, and they may apply limits to protect everyone’s performance. Your plan details can change, so check your own account for the current terms. The principle, however, is stable: fewer unnecessary requests mean lower cost, lower latency and a smaller chance of hitting limits.

A simple estimate

Suppose your app has one million active users in a day, and each user opens the app four times, with one flag request each time. That is four million requests a day. If the app also refreshes flags every minute for the thirty minutes a typical session lasts, each session adds around thirty more requests, and the total climbs to well over a hundred million requests daily. Nothing is broken, yet a small decision about refresh frequency has changed the scale by a factor of thirty.

Ways to keep volume sensible

• Lengthen refresh timers to a few minutes unless a feature truly needs near-instant changes.
• Use real-time updates where offered, because one open connection can replace constant polling.
• Use local evaluation in heavy backend services so decisions need no network call.
• Avoid per-component calls: fetch once, share the result across the app.
• Cache across app launches on devices, so quick reopenings need no request.
• Turn off optional analytics reporting in places where you do not use it.

Plan for spikes

Think about the biggest day of your year: a sale, a launch or a televised event. The edge is built to absorb sudden growth, but your apps must also behave well. Before such a day, review your refresh timers, make sure defaults are safe, and confirm that your own monitoring will tell you quickly if flag calls begin to fail. Tell your Flagsmith contact in advance if you expect an unusually large event, because they may offer helpful advice.

Cost of staleness versus cost of freshness

Choosing a refresh timer is a trade. A short timer means fresher flags and more requests. A long timer means fewer requests and a longer wait before a change appears. Ask what a stale flag would cost in your case. For a decorative banner, a five-minute delay is harmless. For an emergency kill switch, you may want live updates, or a short timer on just that one part of the app.

A made-up company shows how the pieces fit together.

The story below is hypothetical. Imagine a food-delivery company called Spice Route, with customers in India, the United Kingdom and Brazil, and a mobile app, a website and many backend services. The team wants to launch a new “group order” feature without risking dinner-time orders.

What made this smooth

Nothing needed heroics. The team used the edge for speed, defaults for safety, segments for control, and markers for diagnosis. Each simple habit covered a different risk, and together they turned a nerve-racking launch into a routine one.

Serving small, frequently read data from nearby copies is one of the oldest tricks in internet engineering.

The Edge API belongs to a long family of designs that move data closer to the people who use it. Seeing the family makes the idea easier to remember. The examples below describe publicly known approaches in general terms, not claims about any company’s private systems.

The shared pattern

Every one of these systems separates a rarely changing source of truth from a widely copied serving layer. They accept that copies may lag the source slightly. In return they gain speed and the ability to survive trouble. The Flagsmith Edge API applies exactly this pattern to feature flags.

Lessons you can reuse

• Put frequently read data close to the reader.
• Keep the writing path separate from the reading path.
• Accept a small delay in return for speed and resilience.
• Plan for the source being unreachable, and let the copies keep serving.
• Always keep a sensible fallback for when the copy itself cannot be reached.

Knowing a tool’s limits is as valuable as knowing its strengths.

Not a place to edit

The Edge API serves flags. It is not the right tool for creating projects, managing team members or editing flags at scale. Those tasks belong to the dashboard and the management side of the platform. If you need to automate editing, use the proper management interfaces and tools such as Terraform, not the serving endpoints.

Not an instant global broadcast

As covered earlier, changes arrive after a short copy delay, and clients may add their own caching on top. Treat flags as “soon,” not “now.” For anything that needs strict ordering across machines, such as a database migration step, use tools designed for coordination.

Not a database for your user data

Traits exist to drive flag decisions, not to store your customer profiles. Do not treat them as a general database. Keep the facts small and relevant, and keep the real customer records in your own systems with your own protections.

Not a security boundary on its own

A flag value delivered to a browser or phone can be seen and potentially changed by the person holding the device. Do not use client-side flags to guard sensitive actions. Check permissions on your server, and use flags only for presentation and rollout decisions.

Not a substitute for testing

Flags make it easier to release carefully, but they do not remove bugs. Code behind a flag still needs tests, and both the on and the off states must work. Teams that forget this find themselves with a switch that nobody dares to flip.

Quick definitions of the words used in this guide.

A closer look at how one answer is chosen from many possible rules.

The engine is just a careful checklist

Every flag answer, wherever it is produced, comes from a small piece of logic often called the flag engine. It is not magic. It is a checklist that goes from the most general rule to the most specific one, and the most specific rule that applies is the one that wins. Understanding that order explains almost every surprising result you will ever see.

An example in numbers

Imagine a flag called “new_search.” In production, the default is off. A segment called “premium users” turns it on. A second segment called “users in India” leaves it off, and you ranked it above the premium segment. One identity, a tester named “test-user-001,” has an override that turns it on.

Notice how Chitra gets “off” even though she is premium. That is not a bug. Her country segment outranks the premium segment. When a result surprises you, writing out a table like this is the quickest way to find the reason.

Why the answer is the same everywhere

Because the same engine logic is used by the edge, by local evaluation inside server SDKs, and by the Edge Proxy, the same user with the same traits gets the same flags no matter which path answers. That consistency is deliberate. It means you can move an app from one evaluation approach to another without surprising your users.

Fairness in percentage splits

For a rollout to be fair and stable, each user needs a fixed position. The engine takes the user’s ID, combines it with the identity of the flag, and runs it through a mathematical function that always returns the same number for the same input. That number is then compared with your percentage. Because the flag is part of the input, a user who falls in the first five percent for one flag is not automatically in the first five percent for every other flag, which avoids the unfair situation where the same unlucky people always receive every experiment.

Common surprises explained

• A user keeps seeing the old version. A higher-ranked segment or an identity override is probably winning. Check both.
• A new segment seems to do nothing. The user’s traits may not have been sent with the request, so the segment cannot match.
• Two environments behave differently. Rules and segments are stored per environment, so they must be set up in each.
• A trait change takes a moment to matter. Traits are stored when sent, and the next evaluation uses them. An older cached answer on the device may need to refresh first.

What works for five engineers needs a little structure for fifty.

Why structure matters

The Edge API makes serving flags easy. That ease can tempt a growing company into creating hundreds of flags with no owners, no naming rules and no plan for removal. Each flag is a branch in your code that someone must understand and eventually delete. Unmanaged flags become flag debt, a slow build-up that makes software harder to read, test and change.

A light set of rules

Who needs what permissions

Not everyone needs the power to change production. A sensible arrangement lets most engineers view flags and edit them in development and staging, lets a smaller group change production, and reserves administrative actions, such as creating keys, for a few trusted people. This follows the old principle of least privilege: give each person only the access their job requires.

A small runbook for incidents

A runbook is a short, step-by-step guide that a tired person can follow at night. A useful flag runbook has five lines. First, look for recent flag changes on your dashboards. Second, open the audit log to see exactly what changed and who did it. Third, if a change is a plausible cause, reverse it. Fourth, watch your graphs to confirm recovery. Fifth, write a short note linking the flag, the graph and the ticket for the review afterwards.

Keep the audit log in your sights

The audit log is the official diary of every change. Make a habit of reading it during reviews, not just during emergencies. Patterns appear quickly: flags changed at odd hours, changes made without a ticket, or flags that were flipped many times in a day. Each pattern points to an improvement in process, training or tooling.

Measure the health of your flag practice

A few simple measures keep a flag practice honest. Count how many flags are older than ninety days. Count how many have no owner. Track how often production flags are changed without review, and how long it takes to reverse a flag in an emergency. You do not need fancy tools. A short table updated each quarter is enough to show whether things are improving.

A one-page cheat sheet

If you remember only a handful of rules from this guide, make them these. They fit on a single sticky note and prevent most of the trouble teams run into with edge-served flags.

• Know your half. Editing goes through the core and the dashboard. Reading goes through the edge. Do not mix them up when you plan automation.
• Pick the key by place. Public client-side key for apps and sites, secret server-side key for trusted servers only.
• Default to safe. Every flag needs a default that keeps the stable behaviour alive when no answer arrives.
• Fetch once, reuse often. Hold flags in memory, refresh on a calm timer, and never call the network inside loops.
• Always set a time limit. A slow answer should become a default, not a frozen screen.
• Expect a short delay. Allow a few seconds between saving a change and seeing it everywhere.
• Keep identities steady. Stable IDs give stable rollouts, stable overrides and fair experiments.
• Share less data. Small, coarse, non-sensitive traits only.
• Watch from your side. Track request time, error rate and fallback rate, and mark flag changes on your graphs.
• Clean as you go. Give every flag an owner and a planned removal, and sweep old ones every quarter.

Stick this list next to your team’s runbook. New joiners can read it in two minutes, and experienced engineers will find that it settles most design arguments quickly. Good habits around a fast service are what turn raw speed into a calm, dependable experience for the people who use your product, wherever in the world they happen to be.

One last piece of advice concerns patience with yourself. Nobody designs the perfect flag setup on the first attempt. Begin with a single environment, a couple of flags, safe defaults and a basic dashboard marker. Observe how the system behaves for a few weeks, note the surprises, and improve one habit at a time. Teams that grow their practice gradually end up with simpler, sturdier setups than teams that try to build everything before launch, because every addition is justified by a real need they have already seen.

Quick answers to the questions beginners ask most often.

The whole guide on one page.