Mirrors/unleash.unleash
1
0
Fork 0
mirror of https://github.com/Unleash/unleash.git synced 2025-04-10 01:16:39 +02:00
Code Issues Projects Releases Wiki Activity

Merge ccaa4fbcf4 into 038c10f612

Browse Source
This commit is contained in:
Melinda Fekete 2025-03-19 19:15:43 +00:00 committed by GitHub
commit d64cf09dfe
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
7 changed files with 96 additions and 49 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
src/lib/openapi/util/openapi-tags.ts
View File

@ -68,7 +68,7 @@ const OPENAPI_TAGS = [
{
name: 'Frontend API',
description:
'API for connecting client-side (frontend) applications to Unleash.',
'The [Frontend API](https://docs.getunleash.io/reference/front-end-api) is used for connecting client-side (frontend) applications to Unleash.',
},
{
name: 'Import/Export',

39
website/docs/reference/front-end-api.md
View File

@ -8,41 +8,28 @@ title: Frontend API
:::
The Unleash Frontend API offers a simplified workflow for connecting client-side applications to Unleash. It provides the exact same API as [Unleash Edge](https://docs.getunleash.io/reference/unleash-edge) and [Unleash Proxy - deprecated](../generated/unleash-proxy.md). The Frontend API is a quick and easy way to add Unleash to single-page applications and mobile apps.
## Overview
Compared to using Unleash Edge, using the Frontend API has both benefits and drawbacks. The benefits are:
The Unleash [Frontend API](/reference/api/unleash/frontend-api) simplifies connecting client-side applications to Unleash. It shares the same API as [Unleash Edge](https://docs.getunleash.io/reference/unleash-edge) but is best suited for development environments, low-traffic applications, or internal dashboards.
- **You don't need to configure and run Unleash Edge.** The Frontend API is part of Unleash itself and not an external process. All clients will work exactly the same as they would with Unleash Edge.
The Frontend API has a straightforward setup and since it is built directly into Unleash, you don't need to manage it. However, unlike Unleash Edge, it cannot be scaled horizontally and isn’t designed for high request volumes.
On the other hand, using the Frontend API has the following drawbacks compared to using Unleash Edge:
The Frontend API shares the same API as Unleash Edge, so you can start development with the Frontend API and transition to Unleash Edge when needed.
- **It can't handle a large number of requests per second.** Because the Frontend API is part of Unleash, you can't scale it horizontally the way you can scale Unleash Edge.
- **It sends client details to your Unleash instance.** Unleash only stores these details in its short-term runtime cache, but this can be a privacy issue for some use cases.
## Configure the Frontend API
These points make the Unleash Frontend API best suited for development purposes and applications that don’t receive a lot of traffic, such as internal dashboards. However, because the API is identical to the Unleash Edge API, you can go from one to the other at any time. As such, you can start out by using the Frontend API and switch to Unleash Edge when you need it.
### Configure cross-origin resource sharing (CORS)
## Using the Unleash Frontend API
For web and hybrid mobile apps, allow traffic from your application's domains. To update CORS settings in the Unleash Admin UI, go to **Admin > CORS origins**. Alternatively, you can update CORS using the [Admin API](/reference/api/unleash/set-cors).
When using the Frontend API in an SDK, there's three things you need to configure.
### Configure the API URL
### Cross-origin resource sharing (CORS) configuration {#cors}
Point your application to the correct API endpoint: `<your-unleash-instance>/api/frontend`.
You need to allow traffic from your application domains to use the Unleash Frontend API with web and hybrid mobile applications. You can update the Frontend API CORS settings from the Unleash UI under _admin \> CORS_ or by using the API.
### Generate an API token
### API URL
Your application needs a [frontend token](../reference/api-tokens-and-client-keys.mdx#frontend-tokens) to interact with the Frontend API.
The client needs to point to the correct API endpoint. The Frontend API is available at `<your-unleash-instance>/api/frontend`.
### Configure the refresh interval for tokens
<!-- Point to the API docs when they're published -->
### API token
The client needs a frontend [token](../reference/api-tokens-and-client-keys.mdx#frontend-tokens) to interact with the Frontend API.
### Refresh interval for tokens
Internally, Unleash creates a new Unleash client for each token it receives. Each client is configured with the project and environment specified in the token.
Each client updates its feature flag configuration at a specified refresh interval plus a random offset between 0 and 10 seconds. By default, the refresh interval is set to 10 seconds. The random offset is used to stagger incoming requests to avoid a large number of clients all querying the database simultaneously. A new, random offset is used for every update.
The refresh interval is specified in milliseconds and can be set by using the `FRONTEND_API_REFRESH_INTERVAL_MS` environment variable or by using the `frontendApi.refreshIntervalInMs` configuration option in code.
Feature flag updates occur at a default refresh interval of 10 seconds plus a random offset (0-10 seconds) to prevent simultaneous database queries. You can customize the refresh interval using the `FRONTEND_API_REFRESH_INTERVAL_MS` environment variable or the `frontendApi.refreshIntervalInMs` configuration option in the SDK.

2
website/docs/reference/rbac.md
View File

@ -92,7 +92,7 @@ You can assign the following root permissions:
|---------------------|------------------------------------|
| Change instance banners | Change instance [banners](./banners). |
| Change maintenance mode state | Change [maintenance mode](./maintenance-mode) state. |
| Update CORS settings | Update [CORS settings](./front-end-api#cors). |
| Update CORS settings | Update [CORS settings](./front-end-api#configure-cross-origin-resource-sharing-cors). |
| Read instance logs and login history | Read instance logs and [login history](./login-history.md). |
#### Integration permissions

2
website/docs/reference/sdks/index.mdx
View File

@ -12,7 +12,7 @@ Unleash provides official client SDKs for a number of programming languages. Add
<VideoContent videoUrls={["https://www.youtube.com/embed/mCXSAWzdn3I"]}/>
### Server-side SDKs:
### Server-side SDKs
Server-side clients run on your server and communicate directly with your Unleash instance to evaluate your feature flags in their respective language. We provide these official clients:

98
website/docs/understanding-unleash/unleash-overview.md
View File

@ -2,31 +2,91 @@
title: Unleash architecture
---
One of the most important aspects of the Unleash architecture is that feature flags are evaluated directly in the client SDKs that run as part of your application. This makes flag evaluations incredibly fast (we're talking nanoseconds), scalable, and resilient against network disturbances. To achieve this, Unleash incurs a small update-delay when you change your flag configurations until it is fully propagated to your application. This delay is typically a few seconds and is configurable.
Unleash is designed for privacy, speed, and resilience, enabling feature flag evaluations to happen locally within your applications. The architecture provides:
- **Fast feature flag evaluations**: Feature flags are evaluated within the [SDKs](#unleash-sdks) or [Unleash Edge](#unleash-edge), making evaluations incredibly fast (nanoseconds).
- **High reliability**: With server-side SDKs, there is no dependency on network calls during evaluation, providing high reliability.
- **Privacy and security**: No user data is shared with the Unleash instance, ensuring [privacy and security](/understanding-unleash/data-collection).
Since feature flags are evaluated locally within the [client SDKs](/reference/sdks), no user data is shared with the Unleash instance. This ensures complete privacy of your customer data.
## System Overview
If you want more details you can read about [our unique architecture](https://www.getunleash.io/blog/our-unique-architecture).
The Unleash system consists of several key components.
### Unleash Server {#unleash-server}
![A visual overview of an Unleash system as described in the following paragraph.](/img/unleash-architecture-edge.png)
Before you can connect your application to Unleash you need a Unleash server. You have a few options available:
### The Unleash API
1. **Unleash Open-Source**
- [Docker](../using-unleash/deploy/getting-started)
- [Helm Chart](https://github.com/unleash/helm-charts/)
- [GitLab](https://docs.gitlab.com/ee/operations/feature_flags.html#choose-a-client-library)
2. **Unleash Enterprise**
- [Hosted Plans](https://www.getunleash.io/plans)
- [Self-hosted](https://www.getunleash.io/blog/self-host-your-feature-toggle-system)
The Unleash API (or Unleash server) is the core service for managing feature flags, configurations, and related concepts. SDKs retrieve [feature flag](/reference/feature-toggles) configurations from the API, determining which flags are enabled and what [activation strategies](/reference/activation-strategies) apply.
### System Overview {#system-overview}
### The Unleash Admin UI
![A visual overview of an Unleash system as described in the following paragraph.](/img/unleash-architecture-edge.png 'System Overview')
A web interface for managing feature flags, defining activation strategies, viewing analytics, configuring access roles, generating API tokens, and more.
- [**Unleash API**](/reference/api/unleash) - The Unleash instance. This is where you create feature flags, configure activation strategies, and parameters, etc. The service that contains all feature flags and their configurations. Configurations declare which activation strategies to use and which parameters they should get.
- **Unleash Admin UI** - The bundled web interface for interacting with the Unleash instance. Manage flags, define strategies, look at metrics, and much more. Use the UI to [create feature flags](/how-to-create-feature-flag), [manage project access roles](../how-to/how-to-create-and-assign-custom-project-roles), [create API tokens](/reference/api-tokens-and-client-keys#create-an-api-token), and more.
- [**Unleash SDKs**](../reference/sdks) - Unleash SDKs integrate into your applications and get feature configurations from the Unleash API. Use them to check whether features are enabled or disabled and to send metrics to the Unleash API. [See all our SDKs](../reference/sdks)
- [**Unleash Edge**](../reference/unleash-edge) - The Unleash Edge sits between front-end and native applications on one side and the Unleash API on the other. It can also sit between server-side SDKs and the Unleash API as well. You can scale it independently of the Unleash API to handle large request rates without causing issues for the Unleash API. Edge has all endpoints for the client API, frontend API, and proxy API.
![A visual overview of an Unleash system as described in the following paragraph.](/img/unleash-admin-ui.png)
To be super fast (_we're talking nano-seconds_), the [client SDK](../reference/sdks) caches all feature flags and their current configuration in memory. The activation strategies are also implemented in the SDK. This makes it really fast to check if a flag is on or off because it is just a simple function operating on local state, without the need to poll data from the database.
### Unleash SDKs
Unleash provides both [server-side](/reference/sdks#server-side-sdks) and [client-side SDKs](/reference/sdks#client-side-sdks) for integrating feature flagging into your applications. SDKs fetch feature configurations from the Unleash API to check which features are enabled and what activation strategy to use for each feature.
SDKs cache all feature flag data in memory, applying activation strategies locally. This makes flag evaluation incredibly fast, as it is a simple function operating on local state, without the need to poll data from the database. This architecture results in a small delay (typically a few seconds, but configurable) when propagating configuration changes to your applications.
#### Server-side SDKs
Server-side SDKs run in backend applications and retrieve feature flag configurations via the [Client API](#client-api) or [Unleash Edge](#unleash-edge). Server-side SDKs perform the flag evaluation locally, meaning no user data is shared with the Unleash instance.
Supported languages include: [Node.js](/reference/sdks/node), [Go](/reference/sdks/go), [Java](/reference/sdks/java), [Python](/reference/sdks/python), [.NET](/reference/sdks/dotnet), [PHP](/reference/sdks/php), and more.
#### Client-side SDKs
Client-side SDKs are used in frontend and mobile applications. They communicate with Unleash through the [Frontend API](#frontend-api) or [Unleash Edge](#unleash-edge). Supported platforms include: [JavaScript](/reference/sdks/javascript-browser), [React](/reference/sdks/react), [iOS](/reference/sdks/ios-proxy), [Android](/reference/sdks/android-proxy), and more.
Client-side SDKs do not perform the flag evaluation locally, instead, they fetch all enabled feature flags for a given [Unleash Context](/reference/context). The flag evaluation happens inside [Unleash Edge](#unleash-edge) (when using Edge), or directly within your Unleash server, when using the [Frontend API](#frontend-api).
The following table outlines where flag evaluation happens with different SDK setups.
| SDK setup | Feature flag evaluation |
|------------------------------------|--------------------------------------------------|
| Server-side SDK + Client API | Performed **locally** within the SDK. |
| Server-side SDK + Unleash Edge | Performed **locally** within the SDK. |
| Client-side SDK + Frontend API | Performed by the **Unleash server**. |
| Client-side SDK + Unleash Edge | Performed by **Unleash Edge**. |
Flag evaluation relies on the [Unleash Context](/reference/context) and may involve user data. With server-side SDKs, user data remains within your application and is never shared with the Unleash server, whether you use the cloud or self-hosted version.
For client-side SDKs, you can retain all user data within your applications by either [self-hosting Unleash](/understanding-unleash/proxy-hosting#you-host-everything), or [self-hosting Unleash Edge](/understanding-unleash/proxy-hosting#unleash-hosts-the-api-you-host-edge).
### Unleash Edge
Unleash Edge is a lightweight caching layer designed to improve scalability, performance, and resilience. It sits between your SDKs and the Unleash API and handles thousands of connected SDKs without increasing the number of requests you make to your Unleash instance.
Beyond scalability, Unleash Edge also offers privacy and security benefits for client-side SDKs by performing flag evaluations without exposing sensitive data to end-users or to Unleash.
### Unleash APIs
#### Client API
The [Client API](/reference/api/unleash/client) is the API used by server-side SDKs to fetch feature flag configurations and send SDK usage metrics to Unleash.
#### Frontend API
The [Frontend API](/reference/api/unleash/frontend-api) is the API used by client-side SDKs to retrieve all enabled feature flags for a given [Unleash Context](/reference/context) and send SDK usage metrics to Unleash.
#### Admin API
The [Admin API](/reference/api/unleash) is an API layer for managing all aspects of your Unleash instance, including creating, updating, and deleting resources, such as feature flags, activation strategies, and environments. This API is used by the [Unleash Admin UI](#the-unleash-admin-ui) and other tools and [integrations](/reference/integrations).
| API | Used by | Available endpoints |
|---------------|---------|---|
| Client API | Server-side SDKs | Get all enabled feature flags for a given context, register an SDK, send SDK usage metrics. |
| Frontend API | Client-side SDKs | Get a feature flag by name, get all feature flags, register an SDK, send SDK usage metrics. |
| Admin API | Admin UI, internal tooling, third-party integrations | Access and manage all resources within Unleash, such as context, environments, events, metrics, and users.
## Get started with Unleash
To integrate Unleash, you first need an [Unleash server](#the-unleash-api). You can choose from:
- Unleash Enterprise:
- [Cloud-hosted plans](https://www.getunleash.io/pricing)
- [Self-hosted plans](https://www.getunleash.io/pricing)
- Open-source deployment options:
- [Docker](../using-unleash/deploy/getting-started)
- [Helm Chart](https://github.com/unleash/helm-charts/)
- [GitLab](https://docs.gitlab.com/ee/operations/feature_flags.html#choose-a-client-library)
For a deeper dive into Unleash’s architecture, check out this [blog post](https://www.getunleash.io/blog/our-unique-architecture).

2
website/docs/using-unleash/troubleshooting/cors.md
View File

@ -2,5 +2,5 @@
title: My requests are being blocked by CORS
---
1. Make sure you've configured CORS access in Unleash admin UI settings as defined in the [Unleash CORS Policy docs](/reference/front-end-api#cors). These settings can be changed in the Unleash Dashboard under **Settings -> CORS Origins** or by using the [API](/reference/api/unleash/set-ui-config). Allowing all origins (using a single asterisk) will address this matter and is a great starting point when troubleshooting the behavior.
1. Make sure you've configured CORS access in Unleash admin UI settings as defined in the [Unleash CORS Policy docs](/reference/front-end-api#configure-cross-origin-resource-sharing-cors). These settings can be changed in the Unleash Dashboard under **Settings -> CORS Origins** or by using the [API](/reference/api/unleash/set-ui-config). Allowing all origins (using a single asterisk) will address this matter and is a great starting point when troubleshooting the behavior.
1. When receiving "**No 'Access-Control-Policy' header is present on the requested resource**", using the command `curl -I https://<host>/<endpoint>` will allow us to verify that the response includes the header `Access-Control-Allow-Origin: *`.

BIN
website/static/img/unleash-admin-ui.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 436 KiB