diff --git a/404.html b/404.html index ba4ca48f31..97df3bf0b1 100644 --- a/404.html +++ b/404.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
Skip to main content

Page Not Found

We could not find what you were looking for.

Please contact the owner of the site that linked you to the original URL and let them know their link is broken.

- + \ No newline at end of file diff --git a/assets/js/0833ee16.2c85723b.js b/assets/js/0833ee16.df6347be.js similarity index 98% rename from assets/js/0833ee16.2c85723b.js rename to assets/js/0833ee16.df6347be.js index d698bc99f7..a62e31a8fb 100644 --- a/assets/js/0833ee16.2c85723b.js +++ b/assets/js/0833ee16.df6347be.js @@ -1 +1 @@ -"use strict";(self.webpackChunkwebsitev_2=self.webpackChunkwebsitev_2||[]).push([[14583],{75590:(e,t,n)=>{n.r(t),n.d(t,{assets:()=>i,contentTitle:()=>l,default:()=>d,frontMatter:()=>r,metadata:()=>s,toc:()=>p});var a=n(87462),o=(n(67294),n(3905));const r={title:"Svelte",slug:"/reference/sdks/svelte",custom_edit_url:"https://github.com/Unleash/proxy-client-svelte/edit/main/README.md"},l=void 0,s={unversionedId:"generated/sdks/client-side/svelte",id:"generated/sdks/client-side/svelte",title:"Svelte",description:"This document was generated from the README in the Svelte GitHub repository.",source:"@site/docs/generated/sdks/client-side/svelte.md",sourceDirName:"generated/sdks/client-side",slug:"/reference/sdks/svelte",permalink:"/reference/sdks/svelte",draft:!1,editUrl:"https://github.com/Unleash/proxy-client-svelte/edit/main/README.md",tags:[],version:"current",frontMatter:{title:"Svelte",slug:"/reference/sdks/svelte",custom_edit_url:"https://github.com/Unleash/proxy-client-svelte/edit/main/README.md"},sidebar:"documentation",previous:{title:"React",permalink:"/reference/sdks/react"},next:{title:"Vue",permalink:"/reference/sdks/vue"}},i={},p=[{value:"Initialize the client",id:"initialize-the-client",level:2},{value:"Connection options",id:"connection-options",level:3},{value:"Check feature toggle status",id:"check-feature-toggle-status",level:2},{value:"Check variants",id:"check-variants",level:2},{value:"Defer rendering until flags fetched",id:"defer-rendering-until-flags-fetched",level:2},{value:"Updating context",id:"updating-context",level:2},{value:"Deferring client start",id:"deferring-client-start",level:2},{value:"Use unleash client directly",id:"use-unleash-client-directly",level:2}],c={toc:p};function d(e){let{components:t,...n}=e;return(0,o.kt)("wrapper",(0,a.Z)({},c,n,{components:t,mdxType:"MDXLayout"}),(0,o.kt)("admonition",{title:"Generated content",type:"info"},(0,o.kt)("p",{parentName:"admonition"},"This document was generated from the README in the ",(0,o.kt)("a",{parentName:"p",href:"https://github.com/Unleash/proxy-client-svelte"},"Svelte GitHub repository"),".")),(0,o.kt)("admonition",{type:"tip"},(0,o.kt)("p",{parentName:"admonition"},"To connect to Unleash from a client-side context, you'll need to use the ",(0,o.kt)("a",{parentName:"p",href:"/reference/front-end-api"},"Unleash front-end API")," (",(0,o.kt)("a",{parentName:"p",href:"/how-to/how-to-create-api-tokens"},"how do I create an API token?"),") or the ",(0,o.kt)("a",{parentName:"p",href:"/reference/unleash-proxy"},"Unleash proxy")," (",(0,o.kt)("a",{parentName:"p",href:"/reference/api-tokens-and-client-keys#proxy-client-keys"},"how do I create client keys?"),").")),(0,o.kt)("h1",{id:"installation"},"Installation"),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre",className:"language-bash"},"npm install @unleash/proxy-client-svelte\n# or\nyarn add @unleash/proxy-client-svelte\n")),(0,o.kt)("h1",{id:"how-to-use"},"How to use"),(0,o.kt)("h2",{id:"initialize-the-client"},"Initialize the client"),(0,o.kt)("p",null,"Depending on your needs and specific use-case, prepare one of:"),(0,o.kt)("ul",null,(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://docs.getunleash.io/reference/front-end-api"},"Front-end API")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://docs.getunleash.io/reference/unleash-edge"},"Unleash Edge")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("a",{parentName:"li",href:"https://docs.getunleash.io/reference/unleash-proxy"},"Unleash Proxy"))),(0,o.kt)("p",null,"And a respective frontend token (or, if you're using the Unleash Proxy, one of your proxy's designated client keys, previously known as proxy secrets)."),(0,o.kt)("p",null,"Import the provider like this in your entrypoint file (typically index.svelte):"),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre",className:"language-svelte"}," - + @@ -28,7 +28,7 @@
Skip to main content

Client Specification 1.0

This document attempts to guide developers in implementing an Unleash Client SDK.

System Overview​

Unleash is composed of three parts:

  • Unleash API - The service holding all feature toggles and their configurations. Configurations declare which activation strategies to use and which parameters they should get.
  • Unleash UI - The dashboard used to manage feature toggles, define new strategies, look at metrics, etc.
  • Unleash SDK - Used by clients to check if a feature is enabled or disabled. The SDK also collects metrics and sends them to the Unleash API. Activation Strategies are also implemented in the SDK. Unleash currently provides official SDKs for Java and Node.js

system_overview

To be super fast, the client SDK caches all feature toggles and their current configuration in memory. The activation strategies are also implemented in the SDK. This makes it really fast to check if a toggle is on or off because it is just a simple function operating on local state, without the need to poll data from the database.

The Basics​

All client implementations should strive to have a consistent and straightforward user API. It should be a simple method, called isEnabled, to check if a feature toggle is enabled or not. The method should return a boolean value, true or false.

unleash.isEnabled('myAwesomeToggle');

The basic isEnabled method should also accept a default value. This should be used if the client does not know anything about a particular toggle. If the user does not specify a default value, false should be returned for unknown feature toggles.

Calling unleash with default value:

boolean value = unleash.isEnabled("unknownFeatureToggle", false);
//value==false because default value was used.

Implementation of isEnabled​

A feature toggle is defined as:

{
  "name": "Feature.B",
  "description": "lorem ipsum",
  "enabled": true,
  "strategies": [
    {
      "name": "ActiveForUserWithId",
      "parameters": {
        "userIdList": "123,221,998"
      }
    },
    {
      "name": "GradualRolloutRandom",
      "parameters": {
        "percentage": "10"
      }
    }
  ],
  "strategy": "ActiveForUserWithId",
  "parameters": {
    "userIdList": "123,221,998"
  }
}

A simple demo of the isEnabled function in JavaScript style (most of the implementation will likely be more functional):

function isEnabled(name, unleashContext = {}, defaultValue = false) {
  const toggle = toggleRepository.get(name);
  let enabled = false;

  if (!toggle) {
    return defaultValue;
  } else if (!toggle.isEnabled) {
    return false;
  } else {
    for (let i = 0; i < toggle.strategies.length; i++) {
      let strategyDef = toggle.strategies[i];
      let strategyImpl = strategyImplRepository.get(strategyDef.name);
      if (strategyImpl.isEnabled(toggle.parameters, unleashContext)) {
        return true;
      }
    }
    return false;
  }
}

Activation Strategies​

Activation strategies are defined and configured in the unleash-service. It is up to the client to provide the actual implementation of each activation strategy.

Unleash also ships with a few built-in strategies, and expects client SDK's to implement these. Read more about these activation strategies. For the built-in strategies to work as expected the client should also allow the user to define an unleash-context. The context should be possible to pass in as part of the isEnabled call.

Extension points​

Client implementation should also provide a defined interface to make it easier for the user to implement their own activation strategies, and register those in the Unleash client.

Fetching feature toggles (polling)​

The client implementation should fetch toggles in the background as regular polling. In a thread-based environment, such as Java, this needs to be done in a separate thread. The default poll interval should be 15 seconds, and it should also be configurable.

Client registration​

On start-up, the clients should register with the Unleash server. The registration request must include the required fields specified in the API documentation.

Metrics​

Clients are expected to send metrics back to Unleash API at regular intervals. The metrics are a list of used toggles and how many times they evaluated to yes or no in at the time of requesting the metrics. Read more about how to send metrics in the Metrics API documentation.

Backup Feature Toggles​

The SDK also persists the latest known state to a local file on the instance where the client is running. It will store a local copy every time the client receives changes from the API. Having a local backup of the latest known state minimises the consequences of clients not being able to talk to the Unleash API on startup. This is necessary due to network unreliability.

- + \ No newline at end of file diff --git a/contributing.html b/contributing.html index 2bc6e50b6a..9fab2a8424 100644 --- a/contributing.html +++ b/contributing.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
Skip to main content

Contributing to Unleash

Learn how to contribute to unleash.

- + \ No newline at end of file diff --git a/contributing/ADRs.html b/contributing/ADRs.html index 487f8c305e..fbc8319e3c 100644 --- a/contributing/ADRs.html +++ b/contributing/ADRs.html @@ -20,7 +20,7 @@ - + @@ -29,7 +29,7 @@
Skip to main content

ADR Overview

Introduction​

Architectural decision records are a record of design decisions we have made in the past because we belived they would help our code quality over time. Any ADR can be challenged, but two conditions must be met to change an ADR:

  1. The proposed solution must provide a tangible benefit in terms of code quality.
  2. The benefits of the proposed solution must outweigh the effort of retroactively changing the entire codebase. One such example is the decision to re-write Unleash to TypeScript.

Overarching ADRs​

These ADRs describe decisions that concern the entire codebase. They apply to back-end code, front-end code, and code that doesn't neatly fit into either of those categories.

Back-end ADRs​

We are in the process of defining ADRs for the back end. At the time of writing we have created the following ADRS:

Front-end ADRs​

We have created a set of ADRs to help guide the development of the front end:

- + \ No newline at end of file diff --git a/contributing/ADRs/back-end/POST-PUT-api-payload.html b/contributing/ADRs/back-end/POST-PUT-api-payload.html index f4a9d8208c..111646c238 100644 --- a/contributing/ADRs/back-end/POST-PUT-api-payload.html +++ b/contributing/ADRs/back-end/POST-PUT-api-payload.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
Skip to main content

ADR: POST/PUT API payload

Background​

Whenever we receive a payload in our backend for POST or PUT requests we need to take into account backwards compatibility. When we add a new field to an existing API payload, clients using the previous version of the payload will not know about that new field. This means that we need to make sure that the new field is optional. If we make the field required, clients using the previous version of the payload will override the value of the new field with an empty value or null.

Example: adding new setting field to project settings​

Project settings on Unleash 5.3:

curl --location --request PUT 'http://localhost:4242/api/admin/projects/default' \
--header 'Authorization: INSERT_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "id": "default",
  "name": "Default",
  "description": "Default project",
  "defaultStickiness": "default",
  "mode": "open"
}'

New version of project settings (Unleash 5.6):

curl --location --request PUT 'http://localhost:4242/api/admin/projects/default' \
--header 'Authorization: INSERT_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "id": "default",
  "name": "Default",
  "description": "Default project",
  "defaultStickiness": "default",
  "featureLimit": 2
}'

Pay attention to the new field feature limit. If a customer updates Unleash to 5.6 but their integration still does not send that field, it may result in the unwanted behavior of setting that field to empty in the database, in case the server assumes that not sending the field means setting it to empty / null.

This bug can easily be an oversight but can be prevented by following some rules when designing the API payload.

Decision​

When receiving a body from a request we need to take into account 3 possible cases:

  1. The field has a value
  2. The field is undefined or not part of the payload
  3. The field is null
  • If the field has a value, we need to update or set that value in the DB.
  • If the field is undefined or not part of the payload, we need to leave the value in the DB as it is.
  • If the field is null, we need to remove the value from the DB (set it as null on the DB).
- + \ No newline at end of file diff --git a/contributing/ADRs/back-end/breaking-db-changes.html b/contributing/ADRs/back-end/breaking-db-changes.html index 1cf21562d2..6caf076c33 100644 --- a/contributing/ADRs/back-end/breaking-db-changes.html +++ b/contributing/ADRs/back-end/breaking-db-changes.html @@ -20,7 +20,7 @@ - + @@ -30,7 +30,7 @@
Skip to main content

ADR: Breaking DB changes

Background​

During the evolution of a feature different clients may use different version of code e.g. behind a feature flag. If the code relies on breaking DB changes (column delete, table rename, deleting DB entries etc.) it may lead to errors.

The very same problem occurs when you apply a breaking migration just before the new version of the application starts e.g. during a zero-downtime deployment (whatever strategy you use). The code is still running against the old schema as the migration takes a few seconds to apply.

Decision​

First please make sure to avoid breaking DB changes in the first place if possible.

If breaking change is inevitable please use the "expand/contract" pattern.

In the "expand phase":

  • maintain old and new DB schema in parallel
  • maintain code that works with old and new DB schema
  • keep it for 2 minor releases to give all clients a chance to upgrade the code
  • with a fallback of 2 version we can also downgrade in this range without running down migrations

In the "contract phase":

  • remove the old schema when you know that no client is using the old version

Action for a code reviewer:

  • when you spot a migration with ALTER table DROP COLUMN or ALTER table RENAME TO please raise a flag if the "expand phase" was missed
- + \ No newline at end of file diff --git a/contributing/ADRs/back-end/naming.html b/contributing/ADRs/back-end/naming.html index 1f72d323ad..6621460158 100644 --- a/contributing/ADRs/back-end/naming.html +++ b/contributing/ADRs/back-end/naming.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
Skip to main content

ADR: Naming

Background​

In the codebase, we have found a need to have a common way of naming things in order to ensure consistency. It's important that files are named after the contents of the file to ensure that it's easy to search for files. You should be able to find the file you need in the command line without the help of advanced IDEs. This can easily be solved by proper naming. It's also crucial that the naming is consistent across the project, if we are using different naming conventions in different places, it will be hard to navigate the codebase.

Decision​

We have decided to use a naming convention where the files are named after the main class that it contains. Example:

feature-toggle-service.ts

class FeatureToggleService {
  ...
}

The reason for this decision is to remove mental clutter and free up capacity to easily navigate the codebase. Knowing that a file is named after the class that it contains allows you to quickly scan a file without watching for a context where the class is used in order to understand what it is.

- + \ No newline at end of file diff --git a/contributing/ADRs/back-end/preferred-export.html b/contributing/ADRs/back-end/preferred-export.html index 4fc9a84a75..bfeff6cdcc 100644 --- a/contributing/ADRs/back-end/preferred-export.html +++ b/contributing/ADRs/back-end/preferred-export.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
Skip to main content

ADR: Preferred export

Background​

In the codebase, we have discovered that default exports create multiple problems. One is that you can rename the component when importing it, which can cause confusion. Another is that it is harder to find the component when you are looking for it, as you have to look for the file name instead of the component name (solved by ADR for naming, but still relevant).

Decision​

We have decided to use named exports. This will allow us to eliminate the possiblity of exporting a component and renaming it in another file. It also allows us easy access to advanced refactors across the project, because renaming in one place will propagate to all the other places where that import is referenced. This resolves the issues described in the background without any significant downsides.

- + \ No newline at end of file diff --git a/contributing/ADRs/back-end/specificity-db-columns.html b/contributing/ADRs/back-end/specificity-db-columns.html index 7f34c3129f..58e4d38f57 100644 --- a/contributing/ADRs/back-end/specificity-db-columns.html +++ b/contributing/ADRs/back-end/specificity-db-columns.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
Skip to main content

ADR: Specificity in database column references

Background​

We recently experienced an issue where a database migration that introduced a new column resulted in ambiguity errors in our application, which highlighted the need for clearer SQL query standards. Currently, our queries often reference columns without specifying their parent tables, leading to potential ambiguity in complex queries that join multiple tables. This issue becomes more pronounced during database schema changes and migrations, where ambiguity in column references can lead to hard-to-anticipate runtime errors.

Decision​

To mitigate these risks, we will adopt a standard of explicitly specifying the full table name or alias for each column in our SQL queries. This standard is not just about improving readability, but is crucial for avoiding ambiguity in queries, especially when performing joins between tables. The decision to use the full table name or an alias will be left to the discretion of the developer, with a focus on maximizing clarity and maintainability.

Example: Preferred vs. discouraged syntax​

To clarify the standards set out in the ADR, here's a quick comparison of the preferred syntax against the discouraged syntax, using hypothetical tables and columns:

1. Preferred syntax: Explicit table naming

const rows = await this.db
    .select(
        'u.id', 
        'u.name', 
        'u.email',
        'o.description',
    )
    .from('users as u')
    .join('orders as o', 'o.user_id', 'u.id')
    .where('o.status', 'active')
    .orderBy('o.created_at', 'desc')

Why preferred: Clearly indicates that id, name, and email are columns from the users table (aliased as u), and that description, status and created_at are from the orders table (aliased as o). This prevents ambiguity, especially useful in JOINs.

Note: Aliases (u for users, o for orders) are used here for brevity and readability, but they are optional. The key aspect is specifying the table for each column.

2. Discouraged syntax: Implicit table naming

const rows = await this.db
    .select(
        'id', 
        'name', 
        'email',
        'description',
    )
    .from('users')
    .join('orders', 'orders.user_id', 'users.id')
    .where('status', 'active')
    .orderBy('created_at', 'desc')

Why discouraged: Without specifying the table for each column, it becomes unclear which table each column belongs to. This ambiguity, especially in tables with identically named columns, can lead to runtime errors that are difficult to anticipate, particularly in queries involving joins.

Advantages​

The primary benefits of this approach are:

  1. Clarity and reduced ambiguity: By explicitly specifying table names for each column, we eliminate ambiguity about which table a column belongs to. This is particularly beneficial in complex queries involving multiple tables and joins. This also reduces the risk of ambiguity errors during database migrations or schema changes.

  2. Ease of maintenance and adaptability to changes: During database migrations or schema changes, specifically referenced columns make it easier to identify and update relevant queries. This reduces the risk of overlooking changes that might affect query behavior.

  3. Improved readability in complex queries: In queries involving multiple tables and joins, explicitly specifying table names makes the query more readable and understandable, facilitating easier debugging and review, while ensuring consistency across the codebase.

Concerns​

The adoption of this practice comes with minimal concerns:

  1. Slight increase in verbosity: The queries will be slightly longer due to the addition of table names in columns. However, the benefits in clarity and maintainability far outweigh this minor increase in verbosity.

  2. Initial adaptation curve: There might be a brief period of adjustment as developers adapt to this new standard. However, given its straightforward nature, this learning curve is expected to be minimal.

Conclusion​

The adoption of explicit table name specification in our SQL queries is a strategic decision aimed at improving the clarity, maintainability, and reliability of our database interactions. This practice will ensure that our queries remain robust and clear, especially in the context of evolving database schemas and complex query scenarios. We will gradually implement this standard in our existing codebase by following the Girl Scout Rule. This change aligns with our commitment to writing clean, understandable, and maintainable code, thereby enhancing the overall quality of our software development processes.

- + \ No newline at end of file diff --git a/contributing/ADRs/front-end/component-naming.html b/contributing/ADRs/front-end/component-naming.html index 962199e1bf..7e20e98067 100644 --- a/contributing/ADRs/front-end/component-naming.html +++ b/contributing/ADRs/front-end/component-naming.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
Skip to main content

ADR: Component naming and file naming

Background​

In the codebase, we have found a need to have a common way of naming components so that components can be (a) easily searched for, (b) easily identified as react components and (c) be descriptive in what they do in the codebase.

Decision​

We have decided to use a naming convention for components that uppercases the first letter of the component. This also extends to the filename of the component. The two should always be the same:

// Do:
// MyComponent.ts

const MyComponent = () => {};

// Don't:
// someRandomName.ts

const MyComponent = () => {};

The reason for this decision is to remove mental clutter and free up capacity to easily navigate the codebase. Knowing that a component name has the same name as the filename will remove any doubts about the file contents quickly and in the same way follow the React standard of uppercase component names.

Deviations​

In some instances, for simplicity we might want to create internal components or child components for a larger component. If these child components are small enough in size and it makes sense to keep them in the same file as the parent (AND they are used in no other external components) it's fine to keep in the same file as the parent component.

- + \ No newline at end of file diff --git a/contributing/ADRs/front-end/handling-tables.html b/contributing/ADRs/front-end/handling-tables.html index de22c0009c..276c6d8196 100644 --- a/contributing/ADRs/front-end/handling-tables.html +++ b/contributing/ADRs/front-end/handling-tables.html @@ -20,7 +20,7 @@ - + @@ -34,7 +34,7 @@ between the definitions of the client side and server side powered tables.

Decision​

We have decided to favor consistency over one-off simplicity. Using react-table comes at a cost but allows to change between client and server side data handling with lesser effort. It allows to revert decisions to client side and makes the migration to server side data handling easier.

- + \ No newline at end of file diff --git a/contributing/ADRs/front-end/interface-naming.html b/contributing/ADRs/front-end/interface-naming.html index 2611d950c4..131d7712ea 100644 --- a/contributing/ADRs/front-end/interface-naming.html +++ b/contributing/ADRs/front-end/interface-naming.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
Skip to main content

ADR: Interface naming

Background​

In the codebase, we have found a need to have a common way of naming interfaces in order to ensure consistency.

Decision​

We have decided to use a naming convention of appending the letter I in front of interfaces to signify that we are in fact using an interface. For props, we use IComponentNameProps.

// Do:
interface IMyInterface {}
interface IMyComponentNameProps {}

// Don't:
interface MyInterface {}
interface MyComponentName {}

The reason for this decision is to remove mental clutter and free up capacity to easily navigate the codebase. Knowing that an interface is prefixed with I allows you to quickly scan a file without watching for a context where the interface is used in order to understand what it is.

- + \ No newline at end of file diff --git a/contributing/ADRs/front-end/preferred-component-props-usage.html b/contributing/ADRs/front-end/preferred-component-props-usage.html index 5937df02af..cc1049ad31 100644 --- a/contributing/ADRs/front-end/preferred-component-props-usage.html +++ b/contributing/ADRs/front-end/preferred-component-props-usage.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
Skip to main content

ADR: Preferred component props usage

Background​

In the codebase, we have found a need to standardise how to use props, in order to easily be able to figure out what a component is doing and what properties it is given without having to look up the interface.

Decision​

We have decided to use props destructuring inline in components in order to quickly display what properties a component is using.

// Do:
const MyComponent = ({ name, age, occupation }: IComponentProps) => {
    return (
        <div>
            <p>{age}</p>
            <p>{name}</p>
            <p>{occupation}</p>
        </>
    )
};

// Don't:
function MyComponent(props) {
       return (
        <div>
            <p>{props.age}</p>
            <p>{props.name}</p>
            <p>{props.occupation}</p>
        </>
    )
}

The reason for this decision is to remove mental clutter and free up capacity to easily navigate the codebase. In addition, when components grow, the ability to look at the signature and instantly know what dependencies this component uses gives you an advantage when scanning the codebase.

- + \ No newline at end of file diff --git a/contributing/ADRs/front-end/preferred-data-fetching-method.html b/contributing/ADRs/front-end/preferred-data-fetching-method.html index 21e7b640ab..0e0db99b54 100644 --- a/contributing/ADRs/front-end/preferred-data-fetching-method.html +++ b/contributing/ADRs/front-end/preferred-data-fetching-method.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
Skip to main content

ADR: Preferred data fetching method

Background​

We have found a need to standardise how we fetch data from APIs, in order to reduce complexity and simplify the data fetching process.

Decision​

We have decided to remove redux from our application and fetch all of our data via a third party library called useSWR (SWR stands for stale-while-revalidate and is a common cache strategy).

// Do:
// useSegments.ts

import useSWR from 'swr';
import { useCallback } from 'react';
import { formatApiPath } from 'utils/formatPath';
import handleErrorResponses from '../httpErrorResponseHandler';
import { ISegment } from 'interfaces/segment';
import useUiConfig from 'hooks/api/getters/useUiConfig/useUiConfig';
import { IFlags } from 'interfaces/uiConfig';

export interface UseSegmentsOutput {
    segments?: ISegment[];
    refetchSegments: () => void;
    loading: boolean;
    error?: Error;
}

export const useSegments = (strategyId?: string): UseSegmentsOutput => {
    const { uiConfig } = useUiConfig();

    const { data, error, mutate } = useSWR(
        [strategyId, uiConfig.flags],
        fetchSegments
    );

    const refetchSegments = useCallback(() => {
        mutate().catch(console.warn);
    }, [mutate]);

    return {
        segments: data,
        refetchSegments,
        loading: !error && !data,
        error,
    };
};

export const fetchSegments = async (
    strategyId?: string,
    flags?: IFlags
): Promise<ISegment[]> => {
    if (!flags?.SE) {
        return [];
    }

    return fetch(formatSegmentsPath(strategyId))
        .then(handleErrorResponses('Segments'))
        .then(res => res.json())
        .then(res => res.segments);
};

const formatSegmentsPath = (strategyId?: string): string => {
    return strategyId
        ? formatApiPath(`api/admin/segments/strategies/${strategyId}`)
        : formatApiPath('api/admin/segments');
};

// Don't:
const MyComponent = () => {
    useEffect(() => {
        const getData = () => {
            fetch(API_URL)
                .then(res => res.json())
                .then(setData);
        };
        getData();
    }, []);
};
- + \ No newline at end of file diff --git a/contributing/ADRs/front-end/preferred-data-mutation-method.html b/contributing/ADRs/front-end/preferred-data-mutation-method.html index 248044d157..3c2277eb76 100644 --- a/contributing/ADRs/front-end/preferred-data-mutation-method.html +++ b/contributing/ADRs/front-end/preferred-data-mutation-method.html @@ -20,7 +20,7 @@ - + @@ -29,7 +29,7 @@
Skip to main content

ADR: Preferred data mutation method

Background​

Because our product is open-core, we have complexities and needs for our SaaS platform that are not compatible with the needs of our open-source product. We have found a need to standardise how we fetch data from APIs, in order to reduce complexity and simplify the data fetching process.

Decision​

We have decided to standardise data-fetching and error handling by implementing a top level useAPI hook that will take care of formatting the request in the correct way adding the basePath if unleash is hosted on a subpath, wrap with error handlers and return the data in a consistent way.

Example:

import { ITagPayload } from 'interfaces/tags';
import useAPI from '../useApi/useApi';

export const useTagTypesApi = () => {
    const { makeRequest, createRequest, errors, loading } = useAPI({
        propagateErrors: true,
    });

    const createTag = async (payload: ITagPayload) => {
        const path = `api/admin/tag-types`;
        const req = createRequest(path, {
            method: 'POST',
            body: JSON.stringify(payload),
        });

        try {
            const res = await makeRequest(req.caller, req.id);

            return res;
        } catch (e) {
            throw e;
        }
    };

    const validateTagName = async (name: string) => {
        const path = `api/admin/tag-types/validate`;
        const req = createRequest(path, {
            method: 'POST',
            body: JSON.stringify({ name }),
        });
        try {
            const res = await makeRequest(req.caller, req.id);
            return res;
        } catch (e) {
            throw e;
        }
    };
    const updateTagType = async (tagName: string, payload: ITagPayload) => {
        const path = `api/admin/tag-types/${tagName}`;
        const req = createRequest(path, {
            method: 'PUT',
            body: JSON.stringify(payload),
        });

        try {
            const res = await makeRequest(req.caller, req.id);
            return res;
        } catch (e) {
            throw e;
        }
    };

    const deleteTagType = async (tagName: string) => {
        const path = `api/admin/tag-types/${tagName}`;
        const req = createRequest(path, { method: 'DELETE' });

        try {
            const res = await makeRequest(req.caller, req.id);
            return res;
        } catch (e) {
            throw e;
        }
    };

    return {
        createTag,
        validateTagName,
        updateTagType,
        deleteTagType,
        errors,
        loading,
    };
};
- + \ No newline at end of file diff --git a/contributing/ADRs/front-end/preferred-export.html b/contributing/ADRs/front-end/preferred-export.html index f86aae9073..c00cbd26ae 100644 --- a/contributing/ADRs/front-end/preferred-export.html +++ b/contributing/ADRs/front-end/preferred-export.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
Skip to main content

ADR: Preferred export

Background​

We have seen a need to standardize how to export from files in the project, in order to achieve consistency and avoid situations where we can have a component default exported as one name and renamed as something else in a different file. For example:

// Problem example
// File A

const MyComponent = () => {

}

export default MyComponent;

// File B
import NewName from '../components/MyComponent/MyComponent.tsx';

The above can cause massive confusion and make it hard to navigate the codebase.

Decision​

We have decided to standardise exports on named exports. This will allow us to eliminate the possiblity of exporting a component and renaming it in another file.

// Do:
export const MyComponent = () => {};

// Don't:
const MyComponent = () => {};

export default MyComponent;

The reason for this decision is to remove mental clutter and free up capacity to easily navigate the codebase. If you can always deduce that the component is named as it is defined, then finding that component becomes a lot easier. This will ensure that we remove unnecessary hurdles to understand and work within the codebase.

- + \ No newline at end of file diff --git a/contributing/ADRs/front-end/preferred-folder-structure.html b/contributing/ADRs/front-end/preferred-folder-structure.html index de5576a368..c89da90be6 100644 --- a/contributing/ADRs/front-end/preferred-folder-structure.html +++ b/contributing/ADRs/front-end/preferred-folder-structure.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
Skip to main content

ADR: Preferred folder structure

Background​

Folder structure is important in how easy it is to navigate and reason about the codebase. It's important to have a clear structure that is easy to understand and follow, while grouping related files together in such a way that is easy to find and remove.

Decision​

We have decided to create tree-like folder structure that mimics as closely as possible the relationship of the React components in the project. This has a number of benefits:

  • If you are looking for a component, you can easily find it by looking at the folder structure.
  • If you need to delete a component, you can be sure that all of the files connected to that component will be deleted if you delete the folder. This is supremely important, because it allows us to get rid of dead code easily and without having to worry about the consequences of deleting a file and worrying about whether it's used somewhere else.

Folder structure example:​

ProfilePage
  ProfilePage.tsx
  ProfilePage.styles.ts
  ProfileSettings
    ProfileSettings.tsx
    ProfileSettings.styles.ts
  ProfilePicture
    ProfilePicture.tsx
    ProfilePicture.styles.ts

Now you can clearly see that if you need to delete the ProfilePage component, you can simply delete the ProfilePage folder and all of the files connected to that component will be deleted.

If you experience that you need to create a component that is used in multiple places, the component should be moved to the closest possible ancestor. If this is not possible, the component should be moved to the common folder.

- + \ No newline at end of file diff --git a/contributing/ADRs/front-end/preferred-form-architecture.html b/contributing/ADRs/front-end/preferred-form-architecture.html index 802228ebda..79a375d0f2 100644 --- a/contributing/ADRs/front-end/preferred-form-architecture.html +++ b/contributing/ADRs/front-end/preferred-form-architecture.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
Skip to main content

ADR: Preferred form architecture

Background​

Forms can be tricky. In software, we often want to write DRY components, repeating as little as possible. Yet we also want a clear separation of concerns. Forms represent a challenge in this way because you have to choose which principle is the most important. You can't both have it DRY and completely separated.

Decision​

We have decided to architecture our forms in the following way:

  • Create a hook that contains all the logic for the form. This hook will return a form object that contains all the form state and functions to update the state.
  • Create a reusable form component that does not contain any logic
  • Create separate Create and Edit components that use the form component and the form hook to create the form and implements it's own logic for submitting the form.

In this way, we keep as much of the form as possible DRY, but we avoid passing state internally in the form so the form doesn't need to know whether it is in create or edit mode. This allows us to keep one thing in mind when working, and not have to worry about dual states of the component.

- + \ No newline at end of file diff --git a/contributing/ADRs/front-end/preferred-function-type.html b/contributing/ADRs/front-end/preferred-function-type.html index c4dab0046f..77f2a2ae8b 100644 --- a/contributing/ADRs/front-end/preferred-function-type.html +++ b/contributing/ADRs/front-end/preferred-function-type.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
Skip to main content

ADR: Preferred function type

Background​

In the codebase, we have found a need to standardise function types in order to keep the codebase recognizible across different sections, and to encourage / discourage certain patterns.

Decision​

We have decided to use arrow functions across the board in the project. Both for helper functions and for react components.

// Do:
const myFunction = () => {};
const MyComponent = () => {};

// Don't:
function myFunction() {}
function MyComponent() {}

The reason for this decision is to remove mental clutter and free up capacity to easily navigate the codebase. In addition, using arrow functions allows you to avoid the complexity of losing the scope of this for nested functions, and keeps this stable without any huge drawbacks. Losing hoisting is an acceptable compromise.

- + \ No newline at end of file diff --git a/contributing/ADRs/front-end/preferred-styles-import-placement.html b/contributing/ADRs/front-end/preferred-styles-import-placement.html index c9135f3f91..8d7f53e0a0 100644 --- a/contributing/ADRs/front-end/preferred-styles-import-placement.html +++ b/contributing/ADRs/front-end/preferred-styles-import-placement.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
Skip to main content

ADR: preferred styles import placement

Background​

SUPERSEDED BY ADR: Preferred styling method

In the codebase, we have found a need to standardise where to locate the styles import. When using CSS modules, the styles import placement matters for the priority of the styles if you are passing through styles to other components. IE:

// import order matters, because the useStyles in MyComponent now
// is after the useStyles import it will not take precedence if it has
// a styling conflict.
import useStyles from './SecondComponent.styles.ts';
import MyComponent from '../MyComponent/MyComponent.tsx';

const SecondComponent = () => {
    const styles = useStyles();

    return <MyComponent className={styles.overrideStyles} />
}

Decision​

We have decided to always place style imports as the last import in the file, so that any components that the file may use can safely be overriden with styles from the parent component.

// Do:
import MyComponent from '../MyComponent/MyComponent.tsx';

import useStyles from './SecondComponent.styles.ts';

const SecondComponent = () => {
    const styles = useStyles();

    return <MyComponent className={styles.overrideStyles} />;
};

// Don't:
import useStyles from './SecondComponent.styles.ts';
import MyComponent from '../MyComponent/MyComponent.tsx';

const SecondComponent = () => {
    const styles = useStyles();

    return <MyComponent className={styles.overrideStyles} />;
};

The reason for this decision is to remove the posibillity for hard to find bugs, that are not obvious to detect and that might be time consuming to find a solution to.

- + \ No newline at end of file diff --git a/contributing/ADRs/front-end/preferred-styling-method.html b/contributing/ADRs/front-end/preferred-styling-method.html index 4678b50e77..bb99756bba 100644 --- a/contributing/ADRs/front-end/preferred-styling-method.html +++ b/contributing/ADRs/front-end/preferred-styling-method.html @@ -20,7 +20,7 @@ - + @@ -31,7 +31,7 @@ external interop package to maintain compatability with the latest version. The preferred path forward is to use styled components which is supported natively in @material/ui and sparingly use the sx prop available on all mui components.

Consequences: code sharing​

With makeStyles it was common to reuse CSS fragments via library utilities. In the styled components approach we use themeable functions and object literals 

import { Theme } from '@mui/material';

export const focusable = (theme: Theme) => ({
    color: theme.palette.primary.main,
});

export const flexRow = {
    display: 'flex',
    alignItems: 'center',
};

Usage:

const StyledLink = styled(Link)(({ theme }) => ({
    ...focusable(theme),
}));

<IconButton sx={focusable}/>
- + \ No newline at end of file diff --git a/contributing/ADRs/front-end/sdk-generator.html b/contributing/ADRs/front-end/sdk-generator.html index 8910cd5328..37bf2e4698 100644 --- a/contributing/ADRs/front-end/sdk-generator.html +++ b/contributing/ADRs/front-end/sdk-generator.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
Skip to main content

ADR: OpenAPI SDK Generator

Background​

In our current frontend setup we have a lot of code that can be generated out of the OpenAPI schema. Types have not been updated in a while, and even some new features rely on hard-coded types instead of auto-generated files in src/openapi. Fetchers and actions in the frontend involve custom-built code that is grouped in the src/hooks/api folder. There is a separation between getters and actions. Getters use the SWR library. API actions (POST/PUT/DELETE) are grouped by feature and are exposed to components reliant on useAPI hook.

Decisions​

  • We will use the Orval package to generate the typescript types for our SDK.
  • We will consider using Orval to generate the HTTP getters and actions for our SDK in the future, but will first carefully test this approach in new features under development to weed out edge cases.
  • We will deprecate src/interfaces related to API calls and use src/openapi models instead.

Advantages​

SDK generated out of it will be better than what we have right now. It will help reduce the risk of duplication and inconsistencies in our SDK, as it will be generated from a single source of truth.

  • We retain the flexibility of previous solution, because we can implement our own fetcher function, and substitute response and error type generics. See https://orval.dev/guides/custom-client
  • It supports anyOf and oneOf schema, which the previous generator did not support.
  • If we decide to use Orval to generate the HTTP getters and actions for our SDK, it will reduce the amount of boilerplate code required when working with the new APIs.

Concerns​

  • We will need to ensure that we keep our OpenAPI specification up-to-date, as any changes in the specification will be reflected in the generated SDK. We need an enterprise version with all experimental endpoints enabled to get complete output.
  • Orval is well-maintained, but it appears to have just 1 core contributor. SDK is a very important thing and should be reliable.
  • We can revert to writing some API calls by hand if this approach is not flexible enough, but this can cause issues negating the benefits of code generation.

Alternative packages considered​

  • @openapitools/openapi-generator - does not offer as many customization options as Orval. It struggles with anyOf and oneOf types. It fails
  • rapini: This package is less flexible and less actively maintained than Orval, and we therefore decided against it.
  • @openapi-codegen - does not generate SWR hooks
- + \ No newline at end of file diff --git a/contributing/ADRs/overarching/domain-language.html b/contributing/ADRs/overarching/domain-language.html index 3647783dd9..82b4977113 100644 --- a/contributing/ADRs/overarching/domain-language.html +++ b/contributing/ADRs/overarching/domain-language.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
Skip to main content

ADR: Domain language

Background​

In the codebase, we have seen the need to define a domain language that we use to refer to features, methods to keep it consistent across the codebase. This ADR will contain a growing list of domain language used to keep the consistency across the codebase.

Decision​

We have decided to use the same domain language for the features we develop. Each feature will have it's own domain language to keep it consistent across the codebase.

Change requests domain language​

  • Change request: An entity referring to the overarching data structure of a change request. A change request contains changes, and can be approved or rejected.
  • Change: A term referring to a single change within a change request
  • Changes: A term referring to a group of changes within a change request
  • Discard: A term used for deleting a single change of a change request, or discarding an entire change request.
  • Pending: A pending change request is one that has not yet been applied or discarded. In other words, it is in one of these three states:
    1. Draft
    2. In review
    3. Approved
  • Closed: A closed change request has either been applied or cancelled and can no longer be changed. Change requests that are either Applied or Cancelled are considered closed.
- + \ No newline at end of file diff --git a/contributing/ADRs/overarching/separation-request-response-schemas.html b/contributing/ADRs/overarching/separation-request-response-schemas.html index f0eee57c8a..9190a81547 100644 --- a/contributing/ADRs/overarching/separation-request-response-schemas.html +++ b/contributing/ADRs/overarching/separation-request-response-schemas.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
Skip to main content

ADR: Separation of request and response schemas

Background​

During the updating of our OpenAPI documentation, we have encountered issues related to the scope and strictness of our schemas for requests and responses. Currently, we are reusing the same schema for both request and response, which has led to situations where the schemas are either too broad for a response or too strict for a request. This has caused difficulties in accurately defining the expected data structures for API interactions.

Decision​

After careful consideration and discussion, it has been decided to separate the request and response schemas to address the challenges we have encountered. By creating distinct schemas for requests and responses, we aim to improve the flexibility and precision of our API documentation.

Advantages​

Separating the schemas will allow us to establish more precise and constrained response types while enabling more forgiving request types. This approach will facilitate better alignment between the expected data structures and the actual data transmitted in API interactions.

The separation of request and response schemas will provide the following benefits:

  1. Enhanced clarity and correctness: With dedicated schemas for requests and responses, we can define the precise structure and constraints for each interaction. This will help prevent situations where the schemas are overly permissive or restrictive, reducing ambiguity and ensuring that the code handling the requests and responses is more reliable and easier to understand. By separating the schemas, we can define specific and precise structures for requests and responses, minimizing the use of undefined values and improving the overall correctness of the codebase and API implementation. The client knows exactly what data to send in the requests, and the server knows what to expect in the responses, ensuring that both parties are aligned in terms of data structures and expectations.

  2. Improved maintainability: By avoiding the reuse of schemas between requests and responses, we can modify and update them independently. This decoupling of schemas will simplify maintenance efforts and minimize the risk of unintended side effects caused by changes in one context affecting the other.

  3. Flexibility for future enhancements: Separating request and response schemas lays the foundation for introducing additional validation or transformation logic specific to each type of interaction. This modularity will enable us to incorporate future enhancements, such as custom validation rules or middleware, with ease.

Concerns​

While this decision brings several benefits, we acknowledge the following concerns that may arise from the separation of request and response schemas:

  1. Increased schema maintenance: By having separate schemas for requests and responses, there will be a need to maintain and update two sets of schemas instead of a single shared schema. This could potentially increase the maintenance overhead and introduce the possibility of inconsistencies between the two schemas.

  2. Data duplication and redundancy: With the separation of schemas, there might be instances where certain data fields or structures are duplicated between the request and response schemas. This redundancy could lead to code duplication and increase the risk of inconsistencies if changes are not carefully synchronized between the two schemas.

Conclusion​

By implementing the separation of request and response schemas, we aim to improve the robustness and maintainability of our API documentation. This decision will empower developers to build more reliable integrations by providing clearer guidelines for both request and response data structures.

Furthermore, this separation of schemas brings valuable benefits to our internal development process. It allows us to write more robust code and reduces the need for extensive manipulation of incoming requests to fit the correct shapes. By clearly defining the structure and constraints for each interaction, we minimize the likelihood of bugs and make the code significantly easier to reason about and work with.

While a big bang migration replacing all schemas at once is not feasible, we will follow the Boy Scout Rule and aim to complete the migration to separated schemas by the release of version 6.0. This means that as developers make changes or additions to the code, they will incorporate the separation of schemas, gradually updating the existing codebase over time. This approach ensures a smooth transition to the separated schemas, allowing us to continually improve the code handling requests and responses, reducing reliance on undefined values and promoting clarity, correctness, and maintainability throughout the development process.

Overall, this approach will facilitate better communication, reduce confusion, and enhance the overall developer experience when interacting with our APIs, while providing the aforementioned benefits of more robust code, correctness and improved maintainability.

- + \ No newline at end of file diff --git a/contributing/backend/overview.html b/contributing/backend/overview.html index a24a9fbd4c..eb8a5841a8 100644 --- a/contributing/backend/overview.html +++ b/contributing/backend/overview.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
Skip to main content

Back end

The backend is written in nodejs/typescript. It's written as a REST API following a CSR (controller, service, repository/store) pattern. The following ADRs are defined for the backend:

ADRs​

We have created a set of ADRs to help guide the development of the backend:

Requirements​

Before developing on this project you will need two things:

  • PostgreSQL 14.x or newer
  • Node.js 14.x or newer
yarn install
yarn dev

PostgreSQL​

To run and develop unleash, you need to have PostgreSQL database (PostgreSQL v14.x or newer) locally.

Unleash currently also work with PostgreSQL v14+, but this might change in a future feature release, and we have stopped running automatic integration tests below PostgreSQL v12. The current recommendation is to use a role with Owner privileges since Unleash uses Postgres functions to simplify our database usage.

Create a local unleash databases in postgres​

$ psql postgres <<SQL
CREATE USER unleash_user WITH PASSWORD 'password';
CREATE DATABASE unleash WITH OWNER unleash_user;
CREATE DATABASE unleash_test WITH OWNER unleash_user;
ALTER DATABASE unleash_test SET timezone TO 'UTC';
SQL

Then set env vars:

(Optional as unleash will assume these as default values).

export DATABASE_URL=postgres://unleash_user:password@localhost:5432/unleash
export TEST_DATABASE_URL=postgres://unleash_user:password@localhost:5432/unleash_test

PostgreSQL with docker​

If you don't want to install PostgreSQL locally, you can spin up an Docker instance. We have created a script to ease this process: scripts/docker-postgres.sh

Start the application​

In order to start the application you will need Node.js v14.x or newer installed locally.

// Install dependencies
yarn install

// Start Unleash in development
yarn dev

// Unleash UI
http://localhost:3000

// API:
http://localhost:3000/api/

// Execute tests in all packages:
yarn test

Database changes​

We use database migrations to track database changes. Never change a migration that has been merged to main. If you need to change a migration, create a new migration that reverts the old one and then creates the new one.

Making a schema change​

To run migrations, you will set the environment variable for DATABASE_URL

export DATABASE_URL=postgres://unleash_user:password@localhost:5432/unleash

Use db-migrate to create new migrations file.

> yarn run db-migrate create YOUR-MIGRATION-NAME

All migrations require one up and one down method. There are some migrations that will maintain the database integrity, but not the data integrity and may not be safe to run on a production database.

Example of a typical migration:

/* eslint camelcase: "off" */
'use strict';

exports.up = function(db, cb) {
  db.createTable(
    'examples',
    {
      id: { type: 'int', primaryKey: true, notNull: true },
      created_at: { type: 'timestamp', defaultValue: 'now()' },
    },
    cb,
  );
};

exports.down = function(db, cb) {
  return db.dropTable('examples', cb);
};

Test your migrations:

> yarn run db-migrate up
> yarn run db-migrate down

Publishing / Releasing new packages​

Please run yarn test checks before publishing.

Run npm run publish to start the publishing process.

npm run publish:dry

- + \ No newline at end of file diff --git a/contributing/developer-guide.html b/contributing/developer-guide.html index c5dd7b0e95..c143f1b1ea 100644 --- a/contributing/developer-guide.html +++ b/contributing/developer-guide.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
Skip to main content

Developer guide

Introduction​

This repository contains two main parts. The backend and the frontend of unleash. The backend is a Node.js application that is built using TypeScript. The frontend is a React application that is built using TypeScript. The backend specific code can be found in the src lib folder. The frontend specific code can be found in the frontend folder.

Development philosophy​

The development philosophy at unleash is centered at delivering high quality software. We do this by following a set of principles that we believe will help us achieve this goal. We believe that these principles will also help us deliver software that is easy to maintain and extend, serving as our north star.

We believe that the following principles will help us achieve our goal of delivering high quality software:

  • We test our code always

Software is difficult. Being a software engineer is about acknowledging our limits, and taking every precaution necessary to avoid introducing bugs. We believe that testing is the best way to achieve this. We test our code always, and prefer automation over manual testing.

  • We strive to write code that is easy to understand and maintain

We believe code is a language. Written code is a way to communicate intent. It's about explaining to the reader what this code does, in the shortest amount of time possible. As such, writing clean code is supremely important to us. We believe that this contributes to keeping our codebase maintainable, and helps us maintain speed in the long run.

  • We think about solutions before comitting

We don't jump to implementation immediately. We think about the problem at hand, and try to examine the impact that this solution may have in a multitude of scenarios. As our product core is open source, we need to balance the solutions and avoid implementations that may be cumbersome for our community. The need to improve our paid offering must never come at the cost of our open source offering.

Required reading​

The following resources should be read before contributing to the project:

- + \ No newline at end of file diff --git a/contributing/frontend/overview.html b/contributing/frontend/overview.html index f57a02dfe9..984359279f 100644 --- a/contributing/frontend/overview.html +++ b/contributing/frontend/overview.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
Skip to main content

Front end

Frontend overview​

The frontend is written in react/typescript. It's is a single page application that communicates with the backend via a REST API. The frontend is built using vite and served by the backend.

ADRs​

We have created a set of ADRs to help guide the development of the frontend:

- + \ No newline at end of file diff --git a/feature-flag-tutorials.html b/feature-flag-tutorials.html index cf7ba6d002..be358eb16a 100644 --- a/feature-flag-tutorials.html +++ b/feature-flag-tutorials.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
Skip to main content

Feature Flag Tutorials

Tutorials to implement feature flags with your framework.

- + \ No newline at end of file diff --git a/feature-flag-tutorials/flutter/a-b-testing.html b/feature-flag-tutorials/flutter/a-b-testing.html index 35c7594f1e..06db50bf62 100644 --- a/feature-flag-tutorials/flutter/a-b-testing.html +++ b/feature-flag-tutorials/flutter/a-b-testing.html @@ -20,7 +20,7 @@ - + @@ -29,7 +29,7 @@
Skip to main content

A/B Testing in Flutter using Unleash and Mixpanel

note

This article is a contribution by Ayush Bherwani as a part of the Community Content Program. You can also suggest a topic by opening an issue, or Write for Unleash as a part of the Community Content Program.

After successfully integrating the first feature flag in the Unsplash sample app, let’s talk about how you can use Unleash to perform experimentation, also known as A/B testing, in Flutter to ship features more confidently.

For this article, we’ll integrate feature flags for A/B testing to experiment with “like image” feature user experience. As an overview, the app is quite simple, with two screens displaying images and image details respectively. The behavior of the “image details” feature is controlled through an Unleash instance. You can check out the previous article, “How to set up feature flags in Flutter” for an overview of the code structure and implementation. For those who want to skip straight to the code, you can find it on GitHub.

Here’s a screenshot of the application: Unsplash App built on Flutter

Setup variants in Unleash​

In your Unleash instance, create a new feature flag called likeOptionExperiment. Choose the toggle type called Experiment and enable the impression data. By default, the flag will be set to false.

Set Up Variant in Unleash

Now that you have created your feature toggle, let’s create two new variants “gridTile'' and “imageDetails” respectively. These variants will help you position your “like image” button.

Succesfully setting up variant in Unleash

Below is a screenshot of experimentation in action based on the likeOptionExperiment flag and corresponding variants.

Unsplash App built on Flutter

Setup Mixpanel​

For analytics and metrics, we’ll use Mixpanel to track user behavior and usage patterns. We have chosen Mixpanel because it offers a user-friendly setup and in-depth user analytics and segmentation. Given that the project follows clean architecture and Test-Driven Development (TDD) principles, you’ll want to create an abstract layer to interact with the Mixpanel.

Whenever a user opens the app, we track like-variant if likeOptionExperiment is enabled to tag them with their assigned variant (gridTile or imageDetails). The stored variant in Mixpanel can be used later to analyze how each variant impacts user behavior to like an image.

Whenever a user interacts with the LikeButton, we track trackLikeEventForExperimentation, along with their assigned variants. By correlating the trackLikeEventForExperimentation with the like-variant, you can effectively measure the impact of a variant on user behavior and make data-driven decisions. To learn how to correlate and generate reports, see the Mixpanel docs. 

abstract class MixpanelConfig {
 /// ...

 /// Helps you get the metrics of experimentation to analysis
 /// the different position of the share image button.
 void trackLikeEventForExperimentation({
   required LikeButtonPosition likeButtonPosition,
   required String photoId,
 });

 /// Help you get the variant based on which we can create funnel
 /// for analytics.
 void trackLikeVariant(LikeButtonPosition likeButtonPosition);
}

class MixpanelConfigImpl implements MixpanelConfig {
 final TargetPlatformExtended targetPlatformExtended;

 MixpanelConfigImpl(this.targetPlatformExtended);

 Mixpanel get mixpanel {
   return ServiceLocator.getIt<Mixpanel>();
 }

 /// ...

 @override
 void trackLikeEventForExperimentation({
   required LikeButtonPosition likeButtonPosition,
   required String photoId,
 }) {
   if (targetPlatformExtended.isMobile) {
     mixpanel.track('like-experimentation', properties: {
       "variant": describeEnum(likeButtonPosition),
       "photoId": photoId,
     });
   }
 }

 @override
 void trackLikeVariant(LikeButtonPosition likeButtonPosition) {
   if (targetPlatformExtended.isMobile) {
     mixpanel.track('like-variant', properties: {
       "variant": describeEnum(likeButtonPosition),
     });
   }
 }
}

Once you have your configuration in place, the next step is to create MixPanel and MixpanelConfig and add it to your service locator class. Make sure that you have a Mixpanel API key.

class ServiceLocator {
 ServiceLocator._();

 static GetIt get getIt => GetIt.instance;

 static Future<void> initialize() async { 
   /// ...

   final unleash = UnleashClient(
     url: Uri.parse('http://127.0.0.1:4242/api/frontend'),
     clientKey: dotenv.env["UNLEASH_API_KEY"] as String,
     appName: 'unplash_demo',
   );

   await unleash.start();

   getIt.registerLazySingleton(() => unleash);
   getIt.registerLazySingleton<UnleashConfig>(
     () => UnleashConfigImpl(getIt()),
   );

   getIt.registerLazySingleton<WebPlatformResolver>(
     () => WebPlatformResolverImpl(),
   );


   final TargetPlatformExtended targetPlatformExtended =
       TargetPlatformExtendedImpl(getIt());

   getIt.registerLazySingleton<TargetPlatformExtended>(
     () => targetPlatformExtended,
   );

   if (targetPlatformExtended.isMobile) {
     final mixPanel = await Mixpanel.init(
       dotenv.env["MIXPANEL_KEY"] as String,
       trackAutomaticEvents: false,
     );

     getIt.registerLazySingleton(() => mixPanel);
   }

   getIt.registerLazySingleton<MixpanelConfig>(
     () => MixpanelConfigImpl(getIt()),
   );

   /// ...
 }
}

Integration in Flutter​

Let’s dive into how you can use these variants in your Flutter application.

You’ll have to modify UnleashConfig which helps you test the Unleash functionalities in isolation from the rest of the app.

const String isImageDetailsEnabledToggleKey = "isImageDetailsEnabled";
const String likeOptionExperimentKey = "likeOptionExperiment";

/// Helps determine the position of like button
/// [gridTile] will be used to position like image button
/// on [ImageTile].
/// [imageDetails] will be used to position like image button
/// inside the [ImageDetails] page.
enum LikeButtonPosition { gridTile, imageDetails }

abstract class UnleashConfig {
 /// ...
 bool get isLikeOptionExperimentEnabled;
 LikeButtonPosition get likeButtonPosition;
}

class UnleashConfigImpl extends UnleashConfig {
 final UnleashClient unleash;

 UnleashConfigImpl(this.unleash);

 /// ...

 @override
 bool get isLikeOptionExperimentEnabled =>
     unleash.isEnabled(likeOptionExperimentKey);

 @override
 LikeButtonPosition get likeButtonPosition {
   final variant = unleash.getVariant(likeOptionExperimentKey);
   return LikeButtonPosition.values.byName(variant.name);
 }
}

After updating UnleashConfig you may want to create a _trackLikeExperimentationVariant method which you can call in initState of “HomePage” to get the variant details. 

void _trackLikeExperimentationVariant() {
   final unleashConfig = ServiceLocator.getIt<UnleashConfig>();
   final mixpanelConfig = ServiceLocator.getIt<MixpanelConfig>();
   if (unleashConfig.isLikeOptionExperimentEnabled) {
     mixpanelConfig.trackLikeVariant(unleashConfig.likeButtonPosition);
   }
 }

You’ll create a new widget “LikeButton'' which can be utilized for both variants. Make sure to use MixpanelConfig to track user engagement for analytics purposes. 

class LikeButton extends StatelessWidget {
 final ValueNotifier<bool> isLikedNotifier;
 /// Used to track the variant option for the mixpanel event.
 final LikeButtonPosition likeButtonPosition;
 final String photoId;

 const LikeButton({
   super.key,
   required this.isLikedNotifier,
   required this.likeButtonPosition,
   required this.photoId,
 });


 /// Event fired to track the user engagement on liking an image
 void _fireMixpanelEvent() {
   final mixpanelConfig = ServiceLocator.getIt<MixpanelConfig>();
   mixpanelConfig.trackLikeEventForExperimentation(
     likeButtonPosition: likeButtonPosition,
     photoId: photoId,
   );
 }

 @override
 Widget build(BuildContext context) {
   return ValueListenableBuilder<bool>(
     valueListenable: isLikedNotifier,
     builder: (context, isLiked, child) {
       return IconButton(
         padding: EdgeInsets.zero,
         visualDensity: VisualDensity.compact,
         iconSize: 20,
         isSelected: isLiked,
         splashColor: Colors.red,
         onPressed: () {
           isLikedNotifier.value = !isLikedNotifier.value;
           _fireMixpanelEvent();
         },
         selectedIcon: const Icon(
           CupertinoIcons.heart_fill,
           color: Colors.redAccent,
         ),
         icon: const Icon(CupertinoIcons.heart),
       );
     },
   );
 }
}

Once you have created LikeButton, the next step is to use the LikeButtonPosition to add the button in the ImageTile widget, and ImageDetails page.

For ImageTile make sure the button is only visible if isLikeOptionExperiment is enabled and LikeButtonPosition is gridTile.

class ImageTile extends StatelessWidget {
 final UnsplashImage image;
 final UnleashConfig unleashConfig;

 const ImageTile({
   super.key,
   required this.image,
   required this.unleashConfig,
 });

 bool get isFooterEnabled {
   return unleashConfig.isLikeOptionExperimentEnabled &&
       unleashConfig.likeButtonPosition == LikeButtonPosition.gridTile;
 }

 Widget tileGap() => const SizedBox(height: 4);

 @override
 Widget build(BuildContext context) {
   return CachedNetworkImage(
     imageUrl: image.url,
     cacheManager: ServiceLocator.getIt<DefaultCacheManager>(),
     imageBuilder: (context, provider) {
       return Column(
         children: [
           /// Some more widgets
           if (isFooterEnabled) ...[
             ImageTileFooter(image: image),
           ],
         ],
       );
     },
   );
 }
}

For ImageDetailsPage make sure the button is only visible if isLikeOptionExperiment is enabled and LikeButtonPosition is imageDetails.

@RoutePage()
class ImageDetailsPage extends StatefulWidget {
 final String id;

 const ImageDetailsPage({
   super.key,
   required this.id,
 });

 @override
 State<ImageDetailsPage> createState() => _ImageDetailsPageState();
}

class _ImageDetailsPageState extends State<ImageDetailsPage> {
 /// ...
 late final MixpanelConfig mixPanelConfig;
 late final ValueNotifier<bool> isLikedNotifier;
 late final UnleashConfig unleashConfig;

 @override
 void initState() {
   super.initState();
   /// ...
   mixPanelConfig = ServiceLocator.getIt<MixpanelConfig>();
   isLikedNotifier = ValueNotifier<bool>(false);
   unleashConfig = ServiceLocator.getIt<UnleashConfig>();
   /// ...
   _fetchImageDetails();
 }

 /// ...

 void _fetchImageDetails() {
   bloc.add(FetchImageDetailsEvent(widget.id));
 }

 bool get isLikeButtonVisible {
   return unleashConfig.isLikeOptionExperimentEnabled &&
       unleashConfig.likeButtonPosition == LikeButtonPosition.imageDetails;
 }

 @override
 Widget build(BuildContext context) {
   return Scaffold(
     appBar: AppBar(
       leading: IconButton(
         onPressed: () {
           Navigator.of(context).pop();
         },
         icon: const Icon(
           CupertinoIcons.xmark,
         ),
       ),
       actions: [
         if (isLikeButtonVisible) ...[
           LikeButton(
             isLikedNotifier: isLikedNotifier,
             photoId: widget.id,
             likeButtonPosition: LikeButtonPosition.imageDetails,
           ),
         ]
       ],
     ),
     body: /// Body widget;
 }
}

Now that you have your pieces clubbed, you can toggle the likeOptionExperiment flag to enable the experimentation of the “like image” feature in the application.

Voila! Your experimentation is enabled for your feature. You’ve also ensured that users can access the “like image” feature depending on the state of the flag and variant.

Analytics​

Once your experimentation is up and running, you can visit the Mixpanel dashboard to create a funnel and get insights on the user engagement and conversion rate for different variants.

Below is a funnel screenshot for “like image” experimentation:

Mixpanel Analytics for A/B Testing in Unleash for the Flutter Demo

Conclusion​

A/B testing is a low-risk, high-returns approach that can help you make data-driven decisions for your feature releases to increase user engagement, minimize the risk, and increase conversion rates. As a developer, it helps you be confident in your releases by addressing the issues users face and reducing the bounce rates during experimentation with the help of data.

Some of the best practices for experimentation include:

  • You should be open to the results and avoid any hypotheses.
  • You should define the metrics for the success of the experimentation before you run the tests. Keep your success metrics simple and narrowed for better results.
  • Select a group of adequate size for the test to yield definitive results.
  • You should avoid running multiple tests simultaneously, as it may not give reasonable outcomes.

That’s it for today. I hope you found this helpful. Want to dive deep into the code used for this article? It’s all on GitHub.

- + \ No newline at end of file diff --git a/feature-flag-tutorials/nextjs/implementing-feature-flags.html b/feature-flag-tutorials/nextjs/implementing-feature-flags.html index 36291db517..0c0147c723 100644 --- a/feature-flag-tutorials/nextjs/implementing-feature-flags.html +++ b/feature-flag-tutorials/nextjs/implementing-feature-flags.html @@ -20,7 +20,7 @@ - + @@ -30,7 +30,7 @@
Skip to main content

How to Implement Feature Flags in Next.js using Unleash

note

This article is a contribution by Kafilat Adeleke as a part of the Community Content Program. You can also suggest a topic by opening an issue, or Write for Unleash as a part of the Community Content Program.

Imagine turning on and off features in your web application without redeploying your code. Sounds too good to be true? It's possible with feature flags and Next.js, a powerful framework for building fast and scalable web applications using React.

Feature flags are a powerful technique that allows you to toggle features on and off dynamically without redeploying your code. This can help you to deliver faster and safer web applications, as you can test new features in production, perform gradual rollouts, and revert changes quickly if something goes wrong.

Next.js provides features such as:

  • Server-side rendering
  • Static site generation
  • Code splitting
  • Dynamic routing
  • TypeScript support
  • CSS modules support
  • And many more

With Next.js, you can create hybrid applications that can use both static and dynamic pages. Static pages are pre-rendered at build time and served from a CDN, which makes them fast and secure. Dynamic pages are rendered on-demand by a Node.js server, which allows you to use data from any source and handle user interactions. You can also use incremental static regeneration to update static pages without rebuilding your entire application.

However, one of the challenges of using Next.js is that it requires you to rebuild your application every time you want to change something in your code. This can be time-consuming and risky, especially if you want to test new features in production or perform gradual rollouts. Therefore, you need a way to toggle features on and off dynamically without redeploying your code. This is where feature flags come in.

Unleash is an open-source, easy-to-use feature management platform that supports Next.js and other frameworks. With Unleash, you can create and manage feature flags from a user-friendly dashboard and use them in your code with a simple API. Unleash also provides advanced features such as segmentation, strategies, and integrations.

In this tutorial, you will learn how to use feature flags in a Next.js application that displays random activities to users using Unleash. We will use the @unleash/nextjs package, which provides easy integration of Unleash feature flags in a Next.js application. Note: If you only need a very simple setup for feature flags in your Next.js application, like toggling a feature on and off for all users, use the Vercel Edge Config. You can avoid making requests to the Unleash API from your application and instead use the edge config to inject the feature flag values into your pages. Next.js Feature Flag Architecture Diagram

Setup Unleash​

Before you proceed, ensure you have an Unleash instance running. Run the following commands in the terminal:

wget getunleash.io/docker-compose.yml
docker-compose up -d

This will start Unleash in the background. Once Unleash is running, you can access it at http://localhost:4242.

Username: admin
Password: unleash4all

Create a New Feature​

Create a new feature flag in your Unleash instance named "activity".

Create a new feature flag in Unleash

Integrating Unleash in Nextjs​

To get started with Next.js and Unleash, you need to create a Next.js project and add the @unleash/nextjs package as a dependency.

You can run the following commands in your terminal to do this:

npx create-next-app activity-app
cd activity-app
npm install @unleash/nextjs

To make feature flags available to our Next.js application, we will wrap it with the FlagProvider component from the @unleash/nextjs package. This component will initialize the Unleash SDK and provide access to feature flags throughout our application. We will do this by adding it to our pages/_app.tsx file.

import type { AppProps } from "next/app"
import { FlagProvider } from "@unleash/nextjs/client"

export default function App({ Component, pageProps }: AppProps) {
  return (
    <FlagProvider>
      <Component {...pageProps} />
    </FlagProvider>
  )
}

Next, we will use the Bored API to retrieve a random activity and then use the useFlag feature to determine whether the activity is displayed or not.

import { useEffect, useState } from "react"
import { useFlag } from "@unleash/nextjs/client"

const Activity = () => {
  const [activityData, setActivityData] = useState({})

  const showActivity = useFlag("activity")

  useEffect(() => {
    const fetchActivity = async () => {
      try {
        const response = await fetch("https://www.boredapi.com/api/activity/")
        const data = await response.json()
        setActivityData(data)
      } catch (error) {
        console.error("Error fetching activity:", error)
      }
    }

    if (showActivity) {
      fetchActivity()
    }
  }, [showActivity])

  return (
    <div className="bg-gray-100 min-h-screen flex items-center justify-center">
      <div className="bg-white p-8 rounded shadow-lg">
        <h1 className="text-3xl font-bold mb-4">
          Here is an activity for you!
        </h1>
        {showActivity ? (
          <>
            <p className="mb-2">Activity: {activityData.activity}</p>
            <p className="mb-2">Participants: {activityData.participants}</p>
            <p>Price: ${activityData.price}</p>
          </>
        ) : (
          <p>Activity not available</p>
        )}
      </div>
    </div>
  )
}

export default Activity

Our feature flag can now be used to control whether or not activity is displayed. If we toggle on the gradual roll out:

Gradual Rollout

The activity is displayed:

Activity Successful

If we toggle it off:

Toggle Off

No activity is displayed:

Activity Successful

To configure access to Unleash beyond localhost development, follow these steps:

  • Self-host Unleash or run an instance on Unleash Cloud.

  • Get an API key from the Unleash dashboard.

  • Store the API key in your Vercel Project Environment Variable, which secures it and makes it accessible in your code.

Conclusion​

Feature flags are a powerful tool for managing features in web applications. This tutorial showed us how to use feature flags with Next.js and Unleash. We have seen how to create and manage feature flags in the Unleash dashboard, and how to use them in our Next.js code with the @unleash/nextjs library. We have also seen how to test our feature flags by toggling them on and off in the Unleash dashboard.

Unleash is a powerful and easy-to-use feature management platform that can help you deliver faster and safer web applications with Next.js and other frameworks. If you are not already using feature flags in your Next.js applications, I encourage you to try Unleash and see how it can improve your development workflow.

- + \ No newline at end of file diff --git a/feature-flag-tutorials/react.html b/feature-flag-tutorials/react.html index de9fe80521..2fa0039575 100644 --- a/feature-flag-tutorials/react.html +++ b/feature-flag-tutorials/react.html @@ -20,7 +20,7 @@ - + @@ -32,7 +32,7 @@ Since Yarn is required in order to run the app, make sure you have it installed globally. If you do not, run the command below.

npm install yarn@latest -g

In your app's directory, begin installing the dependencies and then run the app:

yarn
yarn dev

Note: We recommend using the default ports that exist in the app's configurations, which are explained in the README for it to point to. In order to ensure those function as expected, make sure no other apps are running on your machine that also port to localhost:3000 and localhost:3001.

In your browser at http://localhost:3000, you will be directed to the sign-in page of the Cypress Real World App. Utilize one of the pre-existing user accounts from the database to sign in.

Username: Allie2
Password: s3cret

For more detailed instructions on the setup process for this app, review the README.

It’s time to pull in your newly created feature flag in your app. Run the following command to install the Unleash React SDK in your repo:

yarn add @unleash/proxy-client-react unleash-proxy-client

Once Unleash has been installed, open up a code editor like VSCode to view your React repo.

In src/index.tsx, import the <FlagProvider>:

import { FlagProvider } from "@unleash/proxy-client-react";

Paste in a configuration object:

const config = {
 url: "http://localhost:4242/api/frontend", // Your local instance Unleash API URL
 clientKey: "<client_key>", // Your client-side API token
 refreshInterval: 15, // How often (in seconds) the client should poll the proxy for updates
 appName: "cypress-realworld-app", // The name of your application. It's only used for identifying your application
};

In the Router section of this file, wrap the FlagProvider around the existing <App /> component:

<FlagProvider config={config}>
  <App />
</FlagProvider>

Next, replace the <client_key> string in the config object with the API token you generated. You can do this by copying the API token into your clipboard from the API Access view table and pasting it into the code.

This configuration object is used to populate the FlagProvider component that comes from Unleash and wraps around the application, using the credentials to target the specific feature flag you created for the project.

You can check our documentation on API tokens and client keys for more specifics and see additional use-cases in our Client-Side SDK with React documentation.

5. Use the feature flag to rollout a notifications badge​

In a real world use case for your feature flag, you can gradually rollout new features to a percentage of users by configuring the flag's strategy.

In this case, we want to rollout a new notifications badge that will appear in the top navigation bar so users can see the latest updates from transactions between contacts. This will require us to modify the visibility of a React component that is rendered in our app.

In src/components/NavBar.tsx, import the useFlag feature:

import { useFlag } from "@unleash/proxy-client-react";

Within the NavBar component in the file, define and reference the flag you created.

const notificationsBadgeEnabled = useFlag("newNotificationsBadge");

This flag will be used to conditionally render the notification icon Badge that is pulled in from Material-UI. If the flag is enabled, the notification badge will display to users and will route them to the Notifications view.

Find the Badge component in the file and wrap it in a boolean operator:

{notificationsBadgeEnabled && (
 <Badge
   badgeContent={allNotifications?.length}
   data-test="nav-top-notifications-count"
   classes={{ badge: classes.customBadge }}
 >
   <NotificationsIcon />
 </Badge>
)}

Note: Ensure you have the correct format in your file or the Prettier formatter will display an error.

6. Verify the toggle experience​

In your Unleash instance, you can toggle your feature flag on or off to verify that the different UI experiences load accordingly.

Unleash turn on feature flag

Enabling the flag will result in being able to see the notifications icon in the top menu of the app.

Notification icon badge visible

If you disable the flag, this results in a view of a navigation menu without the notification badge for all users.

Notification icon badge not visible

You've successfully implemented a feature flag using best practices to control the release of a notifications feature in a real world app!

Conclusion​

In this tutorial, we installed Unleash locally, created a new feature flag, installed Unleash into a React app, and toggled the visibility of a notifications feature within a real world open source project!

- + \ No newline at end of file diff --git a/feature-flag-tutorials/react/examples.html b/feature-flag-tutorials/react/examples.html index 8842fa3549..25cf396872 100644 --- a/feature-flag-tutorials/react/examples.html +++ b/feature-flag-tutorials/react/examples.html @@ -3,7 +3,7 @@ -React Feature Flag Examples | Unleash +React Feature Flag Examples | Unleash @@ -20,15 +20,15 @@ - +
-
Skip to main content

React Feature Flag Examples

In our React tutorial, we implemented a simple on/off feature flag that could turned on and off. In the real world, many feature flag use cases have more nuance than this. This document will walk you through some common examples of using feature flags in React with some of those more advanced use cases in mind.

Applications evolve, and teams must manage all aspects of this evolution, including the flags used to control the application. We built multiple features into Unleash to address the complexities of releasing code and managing feature flags along the way:

  1. Gradual rollouts
  2. Canary deployments
  3. A/B testing
  4. Feature flag metrics & reporting
  5. Feature flag audit logs
  6. Change management & feature flag approvals
  7. Flag automation & workflow integration
  8. Common usage examples of React feature flags

Gradual Rollouts for React Apps​

It’s common to use feature flags to roll out changes to a percentage of users. Flags allow you to monitor your application and infrastructure for undesired behavior (such as errors, memory bottlenecks, etc.) and to see if the changes improve the outcomes for your application (to increase sales, reduce support requests, etc.)

Doing a gradual rollout for a React-based application with Unleash is very straightforward. To see this in action, follow our How to Implement Feature Flags in React tutorial, which implements a notification feature using feature flags.

Once you have completed the tutorial, you can modify the basic setup to adjust the percentage of users who experience this feature with a gradual rollout. The percentage of users split between the notification feature being visible or not is cached so their user experience will remain consistent.

Navigate to the Gradual Rollout form in Unleash by using the "Edit strategy" button.

The &quot;edit strategy&quot; button uses a pencil icon and is located on every strategy.

Adjust the percentage of users to 50% or whichever value you choose, and refresh your app in the browser to see if your user has the new feature experience.

Gradual rollout form

You can achieve this same result using our API with the following code: 

curl --location --request PUT 'http://localhost:4242/api/admin/projects/default/features/newNotificationsBadge/environments/development/strategies/{STRATEGY_ID}' \
    --header 'Authorization: INSERT_API_KEY' \
    --header 'Content-Type: application/json' \
    --data-raw '{
  "name": "flexibleRollout",
  "title": "",
  "constraints": [],
  "parameters": {
    "rollout": "50",
    "stickiness": "default",
    "groupId": "newNotificationsBadge"
  },
  "variants": [],
  "segments": [],
  "disabled": false
}'

Learn more about gradual rollouts in our docs.

Canary Deployments in React​

What is a canary deployment?​

Canary releases are a way to test and release code in different environments for a subset of your audience, which determines which features or versions of the platform people have access to.

Why use canary deployments?​

Canary deployments are a safer and more gradual way to make changes in software development. They help find any abnormalities and align with the agile process for faster releases and quick reversions.

How to leverage feature flags for canary deployments in React?​

Unleash has a few ways to help manage canary deployments for React apps at scale:

  • Using a gradual rollout (which we implemented in a previous section) would be a simple use case but would reduce the amount of control you have over who gets the new feature.

  • Using either constraints or segments (which are a collection of constraints) for a subset of your users to get the new feature vs. the old feature, for more control than a gradual rollout

  • Strategy variants are used to do the same canary deployment, but can be scaled to more advanced cases. For example, if you have 2+ new features and are testing to see if they are better than the old one, you can use variants to split your population of users and conduct an A/B test with them.

Let’s walk through how to utilize strategy constraints in our React app through the Unleash platform.

Configure strategy constraints for canary deployments​

We will build a strategy constraint on top of our existing gradual rollout strategy. This will allow us to target a subset of users to rollout to.

In Unleash, start from the feature flag view and edit your Gradual Rollout strategy from your development environment.

Gradual Rollout configure strategy constraint image

This will take you to the gradual rollout form. Click on the ‘Add constraint’ button.

Add constraint button image

Let’s say we are experimenting with releasing the notifications feature for a limited time. We want to release it to all users, capture some usage data to compare it to the old experience, and then automatically turn it off.

We can configure the constraint in the form to match these requirements:

Create constraint image

  • The context field is set to currentTime
  • The operator is set to DATE_BEFORE
  • The date time is set (to any time) in the future

Once you’ve filled out the proper constraint fields, click ‘Done’ and save the strategy.

Graduall rollout with constraint image

Your release process is now configured with a datetime-based strategy constraint.

Alternatively, you can send an API command to apply the same requirements:

curl --location --request PUT 'http://localhost:4242/api/admin/projects/default/features/newNotificationsBadge/environments/development/strategies/806ebcbd-bb03-4713-8081-7dca3905e612' \
    --header 'Authorization: INSERT_API_KEY' \
    --header 'Content-Type: application/json' \
    --data-raw '{
  "name": "flexibleRollout",
  "title": "",
  "constraints": [
    {
      "value": "2024-02-27T17:00:00.000Z",
      "values": [],
      "inverted": false,
      "operator": "DATE_BEFORE",
      "contextName": "currentTime",
      "caseInsensitive": false
    }
  ],
  "parameters": {
    "rollout": "50",
    "stickiness": "default",
    "groupId": "newNotificationsBadge"
  },
  "variants": [],
  "segments": [],
  "disabled": false
}'

Read our documentation for more context on the robustness of strategy constraint configurations and use cases.

A/B Testing in React​

A/B testing is a common way for teams to test out how users interact with two or more versions of a new feature that is released. At Unleash, we call these variants.

We can expose a particular version of the feature to select user bases when a flag is enabled. From there, a way to use the variants is to view the performance metrics and see which is more efficient.

We can create several variations of this feature to release to users and gather performance metrics to determine which one yields better results. While teams may have different goals for measuring performance, Unleash enables you to configure strategy for the feature variants within your application/service and the platform.

In the context of our React tutorial, we have a notifications badge feature that displays in the top navigation menu. To implement feature flag variants for an A/B Test in React, we will set up a variant in the feature flag and use an announcement icon from Material UI to render a different version.

In Unleash, navigate to the feature flag’s Variants tab and click ‘Add variant’.

Add variant image

In the Variants form, add two variants that will reference the different icons we will render in our app. Name them ‘notificationsIcon’ and ‘announcementsIcon’.

Note: We won’t use any particular payload from these variants other than their default returned objects. For this example, we can keep the variant at 50% weight for each variant, meaning there is a 50% chance that a user will see one icon versus the other. You can adjust the percentages based on your needs, such as making one icon a majority of users would see by increasing its weight percentage. Learn more about feature flag variant properties.

Variant form image

Once you click 'Save variants' at the bottom of the form, your view will display the list of variants in the development environment with their respective metadata.

Variant added image

Alternatively, we can create new variants via an API command below:

curl --location --request PATCH 'http://localhost:4242/api/admin/projects/default/features/newNotificationsBadge/environments/development/variants' \
    --header 'Authorization: INSERT_API_KEY' \
    --header 'Content-Type: application/json' \
    --data-raw '[
  {
    "op": "replace",
    "path": "/1/name",
    "value": "announcementsIcon"
  },
  {
    "op": "replace",
    "path": "/0/name",
    "value": "notificationsIcon"
  }
]'

Now that we have configured our feature flag variants, we can reference them in the React code.

In NavBar.tsx, import the Announcements icon at the top of the file from Material UI, just like the Notifications icon.

Announcement as AnnouncementsIcon,

The full import line now looks like this:

import {
 Menu as MenuIcon,
 Notifications as NotificationsIcon,
 Announcement as AnnouncementsIcon,
 AttachMoney as AttachMoneyIcon,
} from "@material-ui/icons";

Unleash has a built-in React SDK hook called useVariant to retrieve variant data and perform different tasks against them.

Next, import the useVariant hook from the React SDK:

import { useFlag, useVariant } from "@unleash/proxy-client-react";

useVariant returns the name of the specific flag variant your user experiences, if it’s enabled, and if the overarching feature flag is enabled as well.

Within the NavBar component itself, we will:

  • Reference the flag that holds the variants
  • Reference the two variants to conditionally check that their enabled status for rendering

Next, we can modify what is returned in the NavBar component to account for the two variants the user might see on render.

Previously, we toggled the NotificationsIcon component based on whether or not the feature flag was enabled. We’ll take it one step further and conditionally display the icon components based on the feature flag’s variant status:

With our new variants implemented, 50% of users will see the announcements icon. The differences in the UI would look like this:

Compare icons in UI image

We have successfully configured our flag variants and implemented them into our React app for A/B testing in our development environment. Next, we can take a look at how Unleash can track the results of A/B testing and provide insights with data analytics.

Feature Flag Analytics and Reporting in React​

Shipping code is one thing, but monitoring your applications is another aspect of managing code that developers have to account for. Some things to consider would be:

  • Security concerns
  • Performance metrics
  • Tracking user behavior

Unleash was built with all of these considerations in mind as part of our feature flag management approach. You can use feature flag events to send impression data to an analytics tool you choose to integrate. For example, a new feature you’ve released could be causing more autoscaling in your service resources than expected and you either can view that in your Analytics tool or get notified from a Slack integration. Our impression data gives developers a full view of the activity that could raise any alarms.

We make it easy to get our data, your application, and an analytics tool connected so you can collect, analyze, and report relevant data for your teams.

Let’s walk through how to enable impression data for the feature flag we created from the React tutorial and capture the data in our app for analytics usage.

Enable feature flag impression data​

At the flag level in Unleash, navigate to the Settings view.

Edit Settings image

In the Settings view, click on the edit button. This will take us to the ‘Edit Feature toggle’ form.

Enable impression data image

Turn on the impression data and hit ‘Save’. Events will now be emitted every time the feature flag is triggered.

You can also use our API command to enable the impression data:

curl --location --request PATCH 'http://localhost:4242/api/admin/projects/default/features/newNotificationsBadge' \
    --header 'Authorization: INSERT_API_KEY' \
    --header 'Content-Type: application/json' \
    --data-raw '[
  {
    "op": "replace",
    "path": "/impressionData",
    "value": true
  }
]'

Capture impression data for flag analytics​

Next, let’s configure our React app to capture the impression events that are emitted when our flag is triggered. To do this, we can import the useUnleashClient hook from the React SDK into our app. This hook allows us to interact directly with the Unleash client to listen for events and log them.

In NavBar.tsx, pull in useUnleashClient. Our updated import line should look like this:

import { useFlag, useVariant, useUnleashClient } from "@unleash/proxy-client-react";

Next, within the NavBar component itself, call useUnleashClient and wrap a useEffect hook around our function calls to grab impression data with this code snippet:

 const unleashClient = useUnleashClient();

 useEffect(() => {
   unleashClient.start();

   unleashClient.on("ready", () => {
     const enabledImpression = unleashClient.isEnabled("newNotificationsBadge");
     console.log(enabledImpression);
   });

   unleashClient.on("impression", (impressionEvent: object) => {
     console.log(impressionEvent);
     // Capture the event here and pass it internal data lake or analytics provider
   });
 }, [unleashClient]);

This code snippet starts the Unleash client, checks that our flag is enabled, and then stores impression events for your use.

Note: We are passing in unleashClient into the dependency array in useEffect to prevent the app from unnecessarily mounting the component if the state of the data it holds has not changed.

Our flag impression data is now being logged!

In your browser, you can view the output for isEnabled:

{
    "eventType": "isEnabled",
    "eventId": "b4455218-4a88-43aa-8712-b99186f46548",
    "context": {
        "sessionId": 386689528,
        "appName": "cypress-realworld-app",
        "environment": "default"
    },
    "enabled": true,
    "featureName": "newNotificationsBadge",
    "impressionData": true
}

And the console.log for getVariant returns:

{
    "eventType": "getVariant",
    "eventId": "c41aa58b-d2c7-45cf-b668-7267f465e01a",
    "context": {
        "sessionId": 386689528,
        "appName": "cypress-realworld-app",
        "environment": "default"
    },
    "enabled": true,
    "featureName": "newNotificationsBadge",
    "impressionData": true,
    "variant": "announcementsIcon"
}

You can find more information on isEnabled and getVariant in our impression data docs.

Now that the application is capturing impression events, you can configure the correct data fields and formatting to send to any analytics tool or data warehouse you use.

Application Metrics & Monitoring​

Under the Metrics tab, you can see the general activity of the Cypress Real World App from our React tutorial in the development environment over different periods of time. If the app had a production environment enabled, we would also be able to view the amount of exposure and requests the app is receiving over time.

Metrics view image

Our metrics are great for understanding user traffic. You can get a better sense of:

  • What time(s) of the day or week are requests the highest?
  • Which feature flags are the most popular?

Another use case for reviewing metrics is verifying that the right users are being exposed to your feature based on how you’ve configured your strategies and/or variants.

Take a look at our Metrics API documentation to understand how it works from a code perspective.

Feature Flag Audit Logs in React​

Because a Feature Flag service controls the way an application behaves in production, it can be highly important to have visibility into when changes have been made and by whom. This is especially true in highly regulated environments, such as health care, insurance, banking, and others. In these cases (or similar), you might find audit logging useful for:

  1. Organizational compliance
  2. Change control

Fortunately, this is straightforward in Unleash Enterprise.

Unleash provides the data to log any change that has happened over time, at the flag level from a global level. In conjunction with Unleash, tools like Splunk can help you combine logs and run advanced queries against them. Logs are useful for downstream data warehouses or data lakes.

In our React tutorial application, we can view Event logs to monitor the changes to flag strategies and statuses we have made throughout our examples, such as:

  • When the newNotificationsBadge flag was created
  • How the gradual rollout strategy was configured
  • When and how the variants were created and configured

Events log image

You can also retrieve event log data by using an API command below:

curl -L -X GET '<your-unleash-url>/api/admin/events/:featureName' \
-H 'Accept: application/json' \
-H 'Authorization: <API_KEY_VALUE>'

Read our documentation on Event logs and APIs to learn more.

Change Management & Feature Flag Approvals in React​

Unleash makes it easy to toggle a feature. But the more users you have, the more risk with unexpected changes occurring. That’s why we implemented an approval workflow within Unleash Enterprise for making a change to a feature flag. This functions similar to GitHub's pull requests, and models a Git review workflow. You could have one or more approvals required to reduce risk of someone changing something they shouldn’t. It helps development teams to have access only to what they need. For example, you can use Unleash to track changes to your React feature flag’s configuration.

In Unleash Enterprise, we have a change request feature in your project settings to manage your feature flag approvals. When someone working in a project needs to update the status of a flag or strategy, they can follow our approval workflow to ensure that one or more team members review the change request.

Project settings

We have several statuses that indicate the stages a feature flag could be in as it progresses through the workflow. This facilitates collaboration on teams while reducing risk in environments like production. For larger scale change management, you can ensure the correct updates are made while having full visibility into who made the request for change and when.

Change requests

Learn more about how to configure your change requests and our project collaboration mode.

Flag Automation & Workflow Integration for React Apps​

An advanced use case for leveraging feature flags at scale is flag automation in your development workflow. Many organizations use tools like Jira for managing projects and tracking releases across teams. Our Jira integration helps to manage feature flag lifecycles associated with your projects.

It’s common for teams to have a development phase, QA/testing and then a release to production. Let’s say the changes we’ve made in our React tutorial project need to go through a typical development workflow. The Unleash Jira plugin can connect to your Jira server or cloud to create feature flags automatically during the project creation phase. As your code progresses through development and Jira tickets are updated, the relevant flag can turn on in a development environment. The next stage could be canary deployments for testing code quality in subsequent environments to certain groups, like a QA team or beta users. The flag could be automatically turned on in QA and rollout and/or rollout to target audiences in production.

Here’s how this can be done via our API:

  1. Enable a flag.
curl -L -X POST '<your-unleash-url>/api/admin/projects/:projectId/features/:featureName/environments/:environment/on' \
-H 'Accept: application/json' \
-H 'Authorization: <API_KEY_VALUE>'

Review our API docs on flag enablement.

  1. Update a flag.
curl -L -X PUT '<your-unleash-url>/api/admin/projects/:projectId/features/:featureName' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: <API_KEY_VALUE>' \
--data-raw '{
 "description": "Controls disabling of the comments section in case of an incident",
 "type": "kill-switch",
 "stale": true,
 "archived": true,
 "impressionData": false
}'

And the required body field object would look like this:

{
 "description": "Controls disabling of the comments section in case of an incident",
 "type": "kill-switch",
 "stale": true,
 "archived": true,
 "impressionData": false
}

Review our API docs on updating feature flags.

  1. Archive a flag.
curl -L -X DELETE '<your-unleash-url>/api/admin/projects/:projectId/features/:featureName' \
-H 'Authorization: <API_KEY_VALUE>'

Review API docs on archiving flags.

Common Usage Examples of React Feature Flags​

To take full advantage of our React SDK, we’ve compiled a list of the most common functions to call in a React app.

FunctionDescriptionParametersOutput
useFlagdetermines whether or not the flag is enabledfeature flag name (string)true, false (boolean)
useVariantreturns the flag variant that the user falls intofeature flag name (string)flag and flag variant data (object)
useUnleashClientlistens to client events and performs actions against themnone
useUnleashContextretrieves information related to current flag request for you to updatenone
useFlagsretrieves a list of all flags within your projectnonean array of each flag object data
useFlagsStatusretrieves status information of al flags within your project; tells you whether they have been successfully fetched and whether there were any errorsnonean object of flag data

useFlag example​

const newFeature = useFlag(“newFeatureFlag”);

// output
true

useVariant example​

const variant = useVariant(“newFeatureFlag”);

// output
{ enabled: true, feature_enabled: true, name: “newVariant” }

useUnleashClient example​

const unleashClient = useUnleashClient();

unleashClient.start();

unleashClient.on(“ready”, () => {
const impressionEnabled = unleashClient.isEnabled(“newFeatureFlag”);
    // do something here
});

unleashClient.on(“impression”, (events) => { 
    console.log(events);
    // do something with impression data here
});

useUnleashContext example​

 const updateContext = useUnleashContext();

 useEffect(() => {
   // context is updated with userId
   updateContext({ userId });
 }, [userId]);

Read more on Unleash Context and the fields you can request and update.

useFlags example​

const allFlags = useFlags();

// output
[
  {
    name: 'string',
    enabled: true,
    variant: {
      name: 'string',
      enabled: false,
    },
    impressionData: false,
  },
  {
    name: 'string',
    enabled: true,
    variant: {
      name: 'string',
      enabled: false,
    },
    impressionData: false,
  },
];

useFlagsStatus example​

const flagsStatus = useFlagsStatus();

// output
{ flagsReady: true, flagsError: null }

Additional Examples​

Many additional use cases exist for React, including deferring client start, usage with class components, React Native, and more, all of which can be found in our React SDK documentation.

- +
Skip to main content

React Feature Flag Examples

In our React tutorial, we implemented a simple on/off feature flag that could be turned on and off. In the real world, many feature flag use cases have more nuance than this. This document will walk you through some common examples of using feature flags in React with some of those more advanced use cases in mind.

Applications evolve, and teams must manage all aspects of this evolution, including the flags used to control the application. We built multiple features into Unleash to address the complexities of releasing code and managing feature flags along the way:

  1. Gradual rollouts
  2. Canary deployments
  3. A/B testing
  4. Feature flag metrics & reporting
  5. Feature flag audit logs
  6. Change management & feature flag approvals
  7. Flag automation & workflow integration
  8. Common usage examples of React feature flags

Gradual Rollouts for React Apps​

It’s common to use feature flags to roll out changes to a percentage of users. Flags allow you to monitor your application and infrastructure for undesired behavior (such as errors, memory bottlenecks, etc.) and to see if the changes improve the outcomes for your application (to increase sales, reduce support requests, etc.)

Doing a gradual rollout for a React-based application with Unleash is very straightforward. To see this in action, follow our How to Implement Feature Flags in React tutorial, which implements a notification feature using feature flags.

Once you have completed the tutorial, you can modify the basic setup to adjust the percentage of users who experience this feature with a gradual rollout. The percentage of users split between the notification feature being visible or not is cached so their user experience will remain consistent.

Navigate to the Gradual Rollout form in Unleash by using the "Edit strategy" button.

The &quot;edit strategy&quot; button uses a pencil icon and is located on every strategy.

Adjust the percentage of users to 50% or whichever value you choose, and refresh your app in the browser to see if your user has the new feature experience.

Gradual rollout form

You can achieve this same result using our API with the following code: 

curl --location --request PUT 'http://localhost:4242/api/admin/projects/default/features/newNotificationsBadge/environments/development/strategies/{STRATEGY_ID}' \
    --header 'Authorization: INSERT_API_KEY' \
    --header 'Content-Type: application/json' \
    --data-raw '{
  "name": "flexibleRollout",
  "title": "",
  "constraints": [],
  "parameters": {
    "rollout": "50",
    "stickiness": "default",
    "groupId": "newNotificationsBadge"
  },
  "variants": [],
  "segments": [],
  "disabled": false
}'

Learn more about gradual rollouts in our docs.

Canary Deployments in React​

What is a canary deployment?​

Canary releases are a way to test and release code in different environments for a subset of your audience, which determines which features or versions of the platform people have access to.

Why use canary deployments?​

Canary deployments are a safer and more gradual way to make changes in software development. They help find any abnormalities and align with the agile process for faster releases and quick reversions.

How to leverage feature flags for canary deployments in React?​

Unleash has a few ways to help manage canary deployments for React apps at scale:

  • Using a gradual rollout (which we implemented in a previous section) would be a simple use case but would reduce the amount of control you have over who gets the new feature.

  • Using either constraints or segments (which are a collection of constraints) for a subset of your users to get the new feature vs. the old feature, for more control than a gradual rollout

  • Strategy variants are used to do the same canary deployment, but can be scaled to more advanced cases. For example, if you have 2+ new features and are testing to see if they are better than the old one, you can use variants to split your population of users and conduct an A/B test with them.

Let’s walk through how to utilize strategy constraints in our React app through the Unleash platform.

Configure strategy constraints for canary deployments​

We will build a strategy constraint on top of our existing gradual rollout strategy. This will allow us to target a subset of users to rollout to.

In Unleash, start from the feature flag view and edit your Gradual Rollout strategy from your development environment.

Gradual Rollout configure strategy constraint image

This will take you to the gradual rollout form. Click on the ‘Add constraint’ button.

Add constraint button image

Let’s say we are experimenting with releasing the notifications feature for a limited time. We want to release it to all users, capture some usage data to compare it to the old experience, and then automatically turn it off.

We can configure the constraint in the form to match these requirements:

Create constraint image

  • The context field is set to currentTime
  • The operator is set to DATE_BEFORE
  • The date time is set (to any time) in the future

Once you’ve filled out the proper constraint fields, click ‘Done’ and save the strategy.

Graduall rollout with constraint image

Your release process is now configured with a datetime-based strategy constraint.

Alternatively, you can send an API command to apply the same requirements:

curl --location --request PUT 'http://localhost:4242/api/admin/projects/default/features/newNotificationsBadge/environments/development/strategies/806ebcbd-bb03-4713-8081-7dca3905e612' \
    --header 'Authorization: INSERT_API_KEY' \
    --header 'Content-Type: application/json' \
    --data-raw '{
  "name": "flexibleRollout",
  "title": "",
  "constraints": [
    {
      "value": "2024-02-27T17:00:00.000Z",
      "values": [],
      "inverted": false,
      "operator": "DATE_BEFORE",
      "contextName": "currentTime",
      "caseInsensitive": false
    }
  ],
  "parameters": {
    "rollout": "50",
    "stickiness": "default",
    "groupId": "newNotificationsBadge"
  },
  "variants": [],
  "segments": [],
  "disabled": false
}'

Read our documentation for more context on the robustness of strategy constraint configurations and use cases.

A/B Testing in React​

A/B testing is a common way for teams to test out how users interact with two or more versions of a new feature that is released. At Unleash, we call these variants.

We can expose a particular version of the feature to select user bases when a flag is enabled. From there, a way to use the variants is to view the performance metrics and see which is more efficient.

We can create several variations of this feature to release to users and gather performance metrics to determine which one yields better results. While teams may have different goals for measuring performance, Unleash enables you to configure strategy for the feature variants within your application/service and the platform.

In the context of our React tutorial, we have a notifications badge feature that displays in the top navigation menu. To implement feature flag variants for an A/B Test in React, we will set up a variant in the feature flag and use an announcement icon from Material UI to render a different version.

In Unleash, navigate to the feature flag’s Variants tab and click ‘Add variant’.

Add variant image

In the Variants form, add two variants that will reference the different icons we will render in our app. Name them ‘notificationsIcon’ and ‘announcementsIcon’.

Note: We won’t use any particular payload from these variants other than their default returned objects. For this example, we can keep the variant at 50% weight for each variant, meaning there is a 50% chance that a user will see one icon versus the other. You can adjust the percentages based on your needs, such as making one icon a majority of users would see by increasing its weight percentage. Learn more about feature flag variant properties.

Variant form image

Once you click 'Save variants' at the bottom of the form, your view will display the list of variants in the development environment with their respective metadata.

Variant added image

Alternatively, we can create new variants via an API command below:

curl --location --request PATCH 'http://localhost:4242/api/admin/projects/default/features/newNotificationsBadge/environments/development/variants' \
    --header 'Authorization: INSERT_API_KEY' \
    --header 'Content-Type: application/json' \
    --data-raw '[
  {
    "op": "replace",
    "path": "/1/name",
    "value": "announcementsIcon"
  },
  {
    "op": "replace",
    "path": "/0/name",
    "value": "notificationsIcon"
  }
]'

Now that we have configured our feature flag variants, we can reference them in the React code.

In NavBar.tsx, import the Announcements icon at the top of the file from Material UI, just like the Notifications icon.

Announcement as AnnouncementsIcon,

The full import line now looks like this:

import {
 Menu as MenuIcon,
 Notifications as NotificationsIcon,
 Announcement as AnnouncementsIcon,
 AttachMoney as AttachMoneyIcon,
} from "@material-ui/icons";

Unleash has a built-in React SDK hook called useVariant to retrieve variant data and perform different tasks against them.

Next, import the useVariant hook from the React SDK:

import { useFlag, useVariant } from "@unleash/proxy-client-react";

useVariant returns the name of the specific flag variant your user experiences, if it’s enabled, and if the overarching feature flag is enabled as well.

Within the NavBar component itself, we will:

  • Reference the flag that holds the variants
  • Reference the two variants to conditionally check that their enabled status for rendering

Next, we can modify what is returned in the NavBar component to account for the two variants the user might see on render.

Previously, we toggled the NotificationsIcon component based on whether or not the feature flag was enabled. We’ll take it one step further and conditionally display the icon components based on the feature flag’s variant status:

With our new variants implemented, 50% of users will see the announcements icon. The differences in the UI would look like this:

Compare icons in UI image

We have successfully configured our flag variants and implemented them into our React app for A/B testing in our development environment. Next, we can take a look at how Unleash can track the results of A/B testing and provide insights with data analytics.

Feature Flag Analytics and Reporting in React​

Shipping code is one thing, but monitoring your applications is another aspect of managing code that developers have to account for. Some things to consider would be:

  • Security concerns
  • Performance metrics
  • Tracking user behavior

Unleash was built with all of these considerations in mind as part of our feature flag management approach. You can use feature flag events to send impression data to an analytics tool you choose to integrate. For example, a new feature you’ve released could be causing more autoscaling in your service resources than expected and you either can view that in your Analytics tool or get notified from a Slack integration. Our impression data gives developers a full view of the activity that could raise any alarms.

We make it easy to get our data, your application, and an analytics tool connected so you can collect, analyze, and report relevant data for your teams.

Let’s walk through how to enable impression data for the feature flag we created from the React tutorial and capture the data in our app for analytics usage.

Enable feature flag impression data​

At the flag level in Unleash, navigate to the Settings view.

Edit Settings image

In the Settings view, click on the edit button. This will take us to the ‘Edit Feature toggle’ form.

Enable impression data image

Turn on the impression data and hit ‘Save’. Events will now be emitted every time the feature flag is triggered.

You can also use our API command to enable the impression data:

curl --location --request PATCH 'http://localhost:4242/api/admin/projects/default/features/newNotificationsBadge' \
    --header 'Authorization: INSERT_API_KEY' \
    --header 'Content-Type: application/json' \
    --data-raw '[
  {
    "op": "replace",
    "path": "/impressionData",
    "value": true
  }
]'

Capture impression data for flag analytics​

Next, let’s configure our React app to capture the impression events that are emitted when our flag is triggered. To do this, we can import the useUnleashClient hook from the React SDK into our app. This hook allows us to interact directly with the Unleash client to listen for events and log them.

In NavBar.tsx, pull in useUnleashClient. Our updated import line should look like this:

import { useFlag, useVariant, useUnleashClient } from "@unleash/proxy-client-react";

Next, within the NavBar component itself, call useUnleashClient and wrap a useEffect hook around our function calls to grab impression data with this code snippet:

 const unleashClient = useUnleashClient();

 useEffect(() => {
   unleashClient.start();

   unleashClient.on("ready", () => {
     const enabledImpression = unleashClient.isEnabled("newNotificationsBadge");
     console.log(enabledImpression);
   });

   unleashClient.on("impression", (impressionEvent: object) => {
     console.log(impressionEvent);
     // Capture the event here and pass it internal data lake or analytics provider
   });
 }, [unleashClient]);

This code snippet starts the Unleash client, checks that our flag is enabled, and then stores impression events for your use.

Note: We are passing in unleashClient into the dependency array in useEffect to prevent the app from unnecessarily mounting the component if the state of the data it holds has not changed.

Our flag impression data is now being logged!

In your browser, you can view the output for isEnabled:

{
    "eventType": "isEnabled",
    "eventId": "b4455218-4a88-43aa-8712-b99186f46548",
    "context": {
        "sessionId": 386689528,
        "appName": "cypress-realworld-app",
        "environment": "default"
    },
    "enabled": true,
    "featureName": "newNotificationsBadge",
    "impressionData": true
}

And the console.log for getVariant returns:

{
    "eventType": "getVariant",
    "eventId": "c41aa58b-d2c7-45cf-b668-7267f465e01a",
    "context": {
        "sessionId": 386689528,
        "appName": "cypress-realworld-app",
        "environment": "default"
    },
    "enabled": true,
    "featureName": "newNotificationsBadge",
    "impressionData": true,
    "variant": "announcementsIcon"
}

You can find more information on isEnabled and getVariant in our impression data docs.

Now that the application is capturing impression events, you can configure the correct data fields and formatting to send to any analytics tool or data warehouse you use.

Application Metrics & Monitoring​

Under the Metrics tab, you can see the general activity of the Cypress Real World App from our React tutorial in the development environment over different periods of time. If the app had a production environment enabled, we would also be able to view the amount of exposure and requests the app is receiving over time.

Metrics view image

Our metrics are great for understanding user traffic. You can get a better sense of:

  • What time(s) of the day or week are requests the highest?
  • Which feature flags are the most popular?

Another use case for reviewing metrics is verifying that the right users are being exposed to your feature based on how you’ve configured your strategies and/or variants.

Take a look at our Metrics API documentation to understand how it works from a code perspective.

Feature Flag Audit Logs in React​

Because a Feature Flag service controls the way an application behaves in production, it can be highly important to have visibility into when changes have been made and by whom. This is especially true in highly regulated environments, such as health care, insurance, banking, and others. In these cases (or similar), you might find audit logging useful for:

  1. Organizational compliance
  2. Change control

Fortunately, this is straightforward in Unleash Enterprise.

Unleash provides the data to log any change that has happened over time, at the flag level from a global level. In conjunction with Unleash, tools like Splunk can help you combine logs and run advanced queries against them. Logs are useful for downstream data warehouses or data lakes.

In our React tutorial application, we can view Event logs to monitor the changes to flag strategies and statuses we have made throughout our examples, such as:

  • When the newNotificationsBadge flag was created
  • How the gradual rollout strategy was configured
  • When and how the variants were created and configured

Events log image

You can also retrieve event log data by using an API command below:

curl -L -X GET '<your-unleash-url>/api/admin/events/:featureName' \
-H 'Accept: application/json' \
-H 'Authorization: <API_KEY_VALUE>'

Read our documentation on Event logs and APIs to learn more.

Change Management & Feature Flag Approvals in React​

Unleash makes it easy to toggle a feature. But the more users you have, the more risk with unexpected changes occurring. That’s why we implemented an approval workflow within Unleash Enterprise for making a change to a feature flag. This functions similar to GitHub's pull requests, and models a Git review workflow. You could have one or more approvals required to reduce risk of someone changing something they shouldn’t. It helps development teams to have access only to what they need. For example, you can use Unleash to track changes to your React feature flag’s configuration.

In Unleash Enterprise, we have a change request feature in your project settings to manage your feature flag approvals. When someone working in a project needs to update the status of a flag or strategy, they can follow our approval workflow to ensure that one or more team members review the change request.

Project settings

We have several statuses that indicate the stages a feature flag could be in as it progresses through the workflow. This facilitates collaboration on teams while reducing risk in environments like production. For larger scale change management, you can ensure the correct updates are made while having full visibility into who made the request for change and when.

Change requests

Learn more about how to configure your change requests and our project collaboration mode.

Flag Automation & Workflow Integration for React Apps​

An advanced use case for leveraging feature flags at scale is flag automation in your development workflow. Many organizations use tools like Jira for managing projects and tracking releases across teams. Our Jira integration helps to manage feature flag lifecycles associated with your projects.

It’s common for teams to have a development phase, QA/testing and then a release to production. Let’s say the changes we’ve made in our React tutorial project need to go through a typical development workflow. The Unleash Jira plugin can connect to your Jira server or cloud to create feature flags automatically during the project creation phase. As your code progresses through development and Jira tickets are updated, the relevant flag can turn on in a development environment. The next stage could be canary deployments for testing code quality in subsequent environments to certain groups, like a QA team or beta users. The flag could be automatically turned on in QA and rollout and/or rollout to target audiences in production.

Here’s how this can be done via our API:

  1. Enable a flag.
curl -L -X POST '<your-unleash-url>/api/admin/projects/:projectId/features/:featureName/environments/:environment/on' \
-H 'Accept: application/json' \
-H 'Authorization: <API_KEY_VALUE>'

Review our API docs on flag enablement.

  1. Update a flag.
curl -L -X PUT '<your-unleash-url>/api/admin/projects/:projectId/features/:featureName' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: <API_KEY_VALUE>' \
--data-raw '{
 "description": "Controls disabling of the comments section in case of an incident",
 "type": "kill-switch",
 "stale": true,
 "archived": true,
 "impressionData": false
}'

And the required body field object would look like this:

{
 "description": "Controls disabling of the comments section in case of an incident",
 "type": "kill-switch",
 "stale": true,
 "archived": true,
 "impressionData": false
}

Review our API docs on updating feature flags.

  1. Archive a flag.
curl -L -X DELETE '<your-unleash-url>/api/admin/projects/:projectId/features/:featureName' \
-H 'Authorization: <API_KEY_VALUE>'

Review API docs on archiving flags.

Common Usage Examples of React Feature Flags​

To take full advantage of our React SDK, we’ve compiled a list of the most common functions to call in a React app.

FunctionDescriptionParametersOutput
useFlagdetermines whether or not the flag is enabledfeature flag name (string)true, false (boolean)
useVariantreturns the flag variant that the user falls intofeature flag name (string)flag and flag variant data (object)
useUnleashClientlistens to client events and performs actions against themnone
useUnleashContextretrieves information related to current flag request for you to updatenone
useFlagsretrieves a list of all flags within your projectnonean array of each flag object data
useFlagsStatusretrieves status information of al flags within your project; tells you whether they have been successfully fetched and whether there were any errorsnonean object of flag data

useFlag example​

const newFeature = useFlag(“newFeatureFlag”);

// output
true

useVariant example​

const variant = useVariant(“newFeatureFlag”);

// output
{ enabled: true, feature_enabled: true, name: “newVariant” }

useUnleashClient example​

const unleashClient = useUnleashClient();

unleashClient.start();

unleashClient.on(“ready”, () => {
const impressionEnabled = unleashClient.isEnabled(“newFeatureFlag”);
    // do something here
});

unleashClient.on(“impression”, (events) => { 
    console.log(events);
    // do something with impression data here
});

useUnleashContext example​

 const updateContext = useUnleashContext();

 useEffect(() => {
   // context is updated with userId
   updateContext({ userId });
 }, [userId]);

Read more on Unleash Context and the fields you can request and update.

useFlags example​

const allFlags = useFlags();

// output
[
  {
    name: 'string',
    enabled: true,
    variant: {
      name: 'string',
      enabled: false,
    },
    impressionData: false,
  },
  {
    name: 'string',
    enabled: true,
    variant: {
      name: 'string',
      enabled: false,
    },
    impressionData: false,
  },
];

useFlagsStatus example​

const flagsStatus = useFlagsStatus();

// output
{ flagsReady: true, flagsError: null }

Additional Examples​

Many additional use cases exist for React, including deferring client start, usage with class components, React Native, and more, all of which can be found in our React SDK documentation.

+ \ No newline at end of file diff --git a/how-to.html b/how-to.html index 44b418bc50..4460bba16b 100644 --- a/how-to.html +++ b/how-to.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
Skip to main content

How-to guides

Step-by-step recipes for you to follow.

- + \ No newline at end of file diff --git a/how-to/api.html b/how-to/api.html index dac1d941e0..dd67307d2c 100644 --- a/how-to/api.html +++ b/how-to/api.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
Skip to main content

How-to: Unleash API

Learn how to work with the Unleash API

- + \ No newline at end of file diff --git a/how-to/env.html b/how-to/env.html index bc6d280867..fdc5e86cd6 100644 --- a/how-to/env.html +++ b/how-to/env.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
Skip to main content

How-to: environments

Environments how-to guides.

- + \ No newline at end of file diff --git a/how-to/how-to-add-feature-flag-naming-patterns.html b/how-to/how-to-add-feature-flag-naming-patterns.html index 4afb5def15..413beec677 100644 --- a/how-to/how-to-add-feature-flag-naming-patterns.html +++ b/how-to/how-to-add-feature-flag-naming-patterns.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
Skip to main content

How to add feature flag naming patterns

Availability

Feature flag naming patterns is an in-development, enterprise-only feature.

This short guide will show you how to add feature flag naming patterns to a project.

Prerequisites​

  • You must be using an Unleash Enterprise instance.
  • You must have permissions to edit project settings for the project you want to add feature flag naming patterns to.

Step 1: Navigate to project settings​

Navigate to the project settings page for the project you want to add feature flag naming patterns to.

Step 2: Add a feature flag naming pattern​

Use the "feature flag naming pattern" section of the project settings form to add a feature flag naming pattern, plus the optional example and/or description.

When you've entered your data, save the changes.

The &quot;feature flag naming pattern&quot; part of the form. Input fields for pattern, example, and description

- + \ No newline at end of file diff --git a/how-to/how-to-add-sso-azure-saml.html b/how-to/how-to-add-sso-azure-saml.html index 244d47c28f..287faf6c04 100644 --- a/how-to/how-to-add-sso-azure-saml.html +++ b/how-to/how-to-add-sso-azure-saml.html @@ -20,7 +20,7 @@ - + @@ -32,7 +32,7 @@ Azure: The list of claims used by the SAML setup, including the optional claims for given name and surname

URLs and formats

Make sure to replace URLs with the public URL for your Unleash instance. This will require correct region prefix and the instance name.

The correct format is: https://[region].app.unleash-hosted.com/[instanceName]/auth/saml/callback

d) Sections 3 and 4: Azure AD setup details {#azure-details}

You will need some details from section 3 and 4 of the SAML setup form to configure the integration within Unleash. These details are:

Section 3 contains a download link for the Federation Metadata XML file. Section 4 lists the Azure AD identifier and the login URL
Within the Federation Metadata XML file, find the `X509Certificate` tag. You'll need the content within that tag.

Step 3: Configure SAML 2.0 provider in Unleash​

In order to configure SSO with SAML with your Unleash enterprise you should navigate to the Single-Sign-On configuration section and choose the "SAML 2.0" tab.

Unleash: sso-config screen

Use the values from the previous section to fill out the form:

  1. In the entity ID field, add the Azure AD identifier. It should look a little like this https://sts.windows.net/**[identifier]**.
  2. In the single sign-on URL field, add the login URL. It should look something like https://login.microsoftonline.com/**[identifier]**/saml2
  3. In the X.509 certificate field, add the content of the X509Certificate tag from the federation metadata XML.

Optionally, you may also choose to “Auto-create users”. This will make Unleash automatically create new users on the fly the first time they sign-in to Unleash with the given SSO provider (JIT). If you decide to automatically create users in Unleash you must also provide a list of valid email domains separated by commas. You must also decide which root Unleash role they will be assigned. Without this enabled you will need to manually add users to Unleash before SSO will work for their accounts and Unleash.

Unleash: SAML 2.0 filled out with entity ID, Single Sign-On URL, and X.509 certificate and auto-creating users for users with the &#39;@getunleash.ai&#39; and &#39;@getunleash.io&#39; emaiil domains.

Validate​

If everything is set up correctly, you should now be able to sign in with the SAML 2.0 option. You can verify that this works by logging out of Unleash: the login screen should give you the option to sign in with SAML 2.0.

You can also test the integration in Azure by using the "test single sign on" step in the SAML setup wizard.

The SAML setup wizard contains a step that lets you test your SAML 2.0 integration. You can use this to verify that everything is configured correctly within Azure.

Group Syncing​

Optionally, you can sync groups from Azure AD to Unleash to map them to groups in Unleash.

a) Add a group claim in Azure In section 2 (Attributes and claims) of the Azure SAML set-up, select the option to "Add a group claim".

Check the box to "Customize the name of the group claim" and update the "Name" to something simple, such as "groups".

Azure AD only supports sending a maximum of 150 groups in the SAML response. If you're using Azure AD and have users that are present in more than 150 groups, you'll need to add a filter in this section to the group claim to ensure that only the groups you want to sync are sent to Unleash.

Azure: section 2, attributes and claims, adding a group claim with the name &#39;group&#39;

b) Unleash SSO Setup In the Unleash Admin SSO section, enable the option to "Enable Group Syncing".

Add the same "Name" you used from the previous section (eg. "groups") as the "Group Field JSON Path".

Unleash: SAML 2.0 SSO setup, enabled group syncing with the Group Field JSON Path as &#39;groups&#39;

Note that Azure only supports sending up to 150 groups. If you have more groups than this, you can setup a filter in Azure to only send the relevant groups to Unleash.

Unleash: SAML 2.0 setup, filtering groups by name

- + \ No newline at end of file diff --git a/how-to/how-to-add-sso-google.html b/how-to/how-to-add-sso-google.html index db039ff0a7..d90b582538 100644 --- a/how-to/how-to-add-sso-google.html +++ b/how-to/how-to-add-sso-google.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
Skip to main content

[Deprecated] How to add SSO with Google

Deprecation notice

Single Sign-on via the Google Authenticator provider has been removed in Unleash v5 (deprecated in v4). We recommend using OpenID Connect instead. If you're running a self hosted version of Unleash and you need to temporarily re-enable Google SSO, you can do so by setting the GOOGLE_AUTH_ENABLED environment variable to true. If you're running a hosted version of Unleash, you'll need to reach out to us and ask us to re-enable the flag. Note that this code will be removed in a future release and this is not safe to depend on.

Introduction​

In this guide we will do a deep dive on the Single-Sign-On (SSO) using Google Authentication. Unleash supports other identity providers and protocols, have a look at all available Single-Sign-On options

Basic configuration​

Step 1: Sign-in to Unleash​

In order to configure SSO you will need to log in to the Unleash instance with a user that have "Admin" role. If you are self-hosting Unleash then a default user will be automatically created the first time you start Unleash:

  • username: admin
  • password: unleash4all

Step 2: Navigate to SSO configuration​

In order to configure SSO with Google with your Unleash enterprise you should navigate to the Single-Sign-On configuration section and choose the "Google" tab.

sso-config

Step 3: Google Authentication​

Navigate to https://console.developers.google.com/apis/credentials

  1. Click Create credentials
  2. Choose Oauth Client Id
  3. Choose Application Type: web application
  4. Add https://[unleash.hostname.com]/auth/google/callback as an authorized redirect URI.

You will then get a Client ID and a Client Secret that you will need in the next step.

Google OAuth: Secret

Step 4: Configure Unleash​

Log in to Unleash and navigate to Admin menu -> Single-Sign-on -> Google.

First insert the Client Id and Client Secret from step 3.

You must also specify the hostname Unleash is running on. If Unleash is running on localhost you should specify the port as well (localhost:4242).

If you want to allow everyone in your organization to access Unleash, and have Unleash auto-create users you can enable this option. You should then also specify which email domains you want to allow logging in to Unleash.

Remember to click “Save” to store your settings.

Google OAuth: Secret

Step 5: Verify​

Log out of Unleash and sign back in again. You should now be presented with the “SSO Authentication Option”. Click the button and follow the sign-in flow. If all goes well you should be successfully signed in to Unleash. If something is not working you can still sign-in with username and password.

Verify SSO

- + \ No newline at end of file diff --git a/how-to/how-to-add-sso-open-id-connect.html b/how-to/how-to-add-sso-open-id-connect.html index fd4dec3a6b..22c0bf00e0 100644 --- a/how-to/how-to-add-sso-open-id-connect.html +++ b/how-to/how-to-add-sso-open-id-connect.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
Skip to main content

How to add SSO with OpenID Connect

Availability

The Single-Sign-On capability is only available for customers on the Enterprise subscription. Check out the Unleash plans for details.

Introduction​

In this guide we will do a deep dive on the Single-Sign-On (SSO) using the OpenID Connect protocol and connect it with Okta as IdP. Unleash supports other identity providers and protocols, have a look at all available Single-Sign-On options

Basic configuration​

Step 1: Sign-in to Unleash​

In order to configure SSO you will need to log in to the Unleash instance with a user that have "Admin" role. If you are self-hosting Unleash then a default user will be automatically created the first time you start Unleash:

  • username: admin
  • password: unleash4all

Step 2: Navigate to SSO configuration​

Unleash enterprise supports multiple authentication providers, and we provide in depth guides for each of them. To find them navigate to "Admin" => "Single-Sign-On" section.

admin-authentication

Step 3: Okta with OpenID Connect​

Open a new tab/window in your browser and sign in to your Okta account. We will need to create a new Application which will hold the settings we need for Unleash.

a) Create new Okta application

Navigate to “Admin/Applications” and click the “Add Apps” button.

Okta: Add Apps

Then click “Create Application” and choose a new “OIDC - OpenID Connect” application, and choose application type "Web Application" and click create.

Okta: Create Apps

b) Configure Application Integration

Give you application a name. And set the Sign-in redirect URI to:

https://[region].app.unleash-hosted.com/[instanceName]/auth/oidc/callback

(In a self-hosted scenario the URL must match your UNLEASH_URL configuration)

You can also configure the optional Sign-out redirect URIs: https://[region].app.unleash-hosted.com/[instanceName]/

Okta: Configure OpenID Connect

Save your new application and you will get the required details you need to configure the Unleash side of things:

Okta: Configure OpenID Connect

c) Configure OpenID Connect provider in Unleash

Navigate to Unleash and insert the details (Discover URL, Client Id and Client Secret) into Unleash.

Please note that the Discover URL must be a valid URL and must include the https:// prefix. For example: https://dev-example-okta.com is a valid discovery URL.

You may also choose to “Auto-create users”. This will make Unleash automatically create new users on the fly the first time they sign-in to Unleash with the given SSO provider (JIT). If you decide to automatically create users in Unleash you must also provide a list of valid email domains. You must also decide which root Unleash role they will be assigned (Editor role will be the default).

Unleash: Configure OpenID Connect

Step 4: Verify​

Log out of Unleash and sign back in again. You should now be presented with the "Sign in with OpenID Connect" option. Click the button and follow the sign-in flow. If all goes well you should be successfully signed in to Unleash.

(If something is not working you can still sign-in with username and password).

Verify SSO

Success!

- + \ No newline at end of file diff --git a/how-to/how-to-add-sso-saml-keycloak.html b/how-to/how-to-add-sso-saml-keycloak.html index c341ca4a9e..7c60f71ad8 100644 --- a/how-to/how-to-add-sso-saml-keycloak.html +++ b/how-to/how-to-add-sso-saml-keycloak.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
Skip to main content

How to add SSO with SAML 2.0 Keycloak

Availability

The Single-Sign-On capability is only available for customers on the Enterprise subscription. Check out the Unleash plans for details.

Introduction​

In this guide we will do a deep dive on the Single-Sign-On (SSO) integration with SAML 2.0 and connect it with Keycloak as IdP. Unleash supports other identity providers and protocols, have a look at all available Single-Sign-On options

Basic configuration​

Step 1: Sign-in to Unleash​

In order to configure SSO you will need to log in to the Unleash instance with a user that have "Admin" role. If you are self-hosting Unleash then a default user will be automatically created the first time you start Unleash:

  • username: admin
  • password: unleash4all

Step 2: Navigate to SSO configuration​

In order to configure SSO with SAML with your Unleash enterprise you should navigate to the Single-Sign-On configuration section and choose the "SAML 2.0" tab.

sso-config

Step 3: Keycloak with SAML 2.0​

Open to the Keycloak dashboard and navigate to “Clients” and click “Add Client” button. Give it a unique clientId (e.g. unleash), use the “saml” protocol and specify the following SAML Endpoint:

https://<unleash.hostname.com>/auth/saml/callback

Keycloak: Add client

a) Change “Name ID format to “email” Unleash expects an email to be sent from the SSO provider so make sure Name ID format is set to email, see a). also you must give the IDP Initiated SSO URL Name, we have chosen to call it “unleash”, see 2). This gives us the Sign-on URL we will need in our Unleash configuration later.

Keycloak: step 2

b) Copy the Keycloak Entity ID an Signing key

Navigate to “Realm Settings” and open the “SAML 2.0 Identity Provider Metadata”. You will need copy the entityID (a) and the X509Certificate (B). These will be required when configuring SAML 2.0 in Unleash.

Keycloak: step 3

Step 4: Configure SAML 2.0 Authentication provider in Unleash​

Go back to Unleash Admin Dashboard and navigate to Admin Menu -> Single-Sign-On -> SAML. Fill in the values captured in the step 3.

  • Entity ID (3b a)
  • Single Sing-On URL (3a b)
  • Certificate (3b b)

You may also choose to “auto create users”. This will make Unleash automatically create new users on the fly first time they sign-in to Unleash with the given SSO provider. You may also limit the auto-creation to certain email domains, shown in the example below.

Keycloak: step 4

Step 5: Validate​

You have now successfully configured Unleash to use SAML 2.0 together with Keycloak as an IdP. Please note that you also must assign users to the application defined in Keycloak to actually be able to log-in to Unleash.

Try signing out of Unleash. If everything is configured correctly you should be presented with the option to sign in with SAML 2.0.

- + \ No newline at end of file diff --git a/how-to/how-to-add-sso-saml.html b/how-to/how-to-add-sso-saml.html index a6c87223be..c5725b3567 100644 --- a/how-to/how-to-add-sso-saml.html +++ b/how-to/how-to-add-sso-saml.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
Skip to main content

How to add SSO with SAML 2.0 Okta

Availability

The Single-Sign-On capability is only available for customers on the Enterprise subscription. Check out the Unleash plans for details.

Introduction​

In this guide we will do a deep dive on the Single-Sign-On (SSO) integration with SAML 2.0 and connect it with Okta as IdP. Unleash support other identity providers and protocols, have a look at all available Single-Sign-On options

Basic configuration​

Step 1: Sign-in to Unleash​

In order to configure SSO you will need to log in to the Unleash instance with a user that have "Admin" role. If you are self-hosting Unleash then a default user will be automatically created the first time you start Unleash:

  • username: admin
  • password: unleash4all

Step 2: Navigate to SSO configuration​

In order to configure SSO with SAML with your Unleash enterprise you should navigate to the Single-Sign-On configuration section and choose the "SAML 2.0" tab.

sso-config

Step 3: Create an application in Okta​

Open a new tab/window in your browser and sign in to your Okta account. We will need to create a new Application which will hold the settings we need for Unleash.

a) Navigate to “Admin -> Applications” and click the “Add Application” button.

Okta: Add Apps

b) Click “Create New App and choose a new “SAML 2.0” application and click create

Okta: Create Application

c) Configure SAML 2.0

Unleash expects an email to be sent from the SSO provider so make sure Name ID format is set to email. Also you must give the IdP Initiated SSO URL Name, we have chosen to call it “unleash-enterprise”. This gives us the Sign-on URL we will need in our Unleash configuration later.

In addition you may provide the following attributes:

  • firstName
  • lastName

(These will be used to enrich the user data in Unleash).

Okta: Configure SAML

Please make sure to replace URLs with the public URL for your Unleash instance. This will require correct region prefix and the instance name. The example above uses region="us" and instance-name="ushosted".

The correct format is: https://[region].app.unleash-hosted.com/[instanceName]/auth/saml/callback

d) Get the Okta Setup Instructions

Click the “View Setup Instructions” to get the necessary configuration required for Unleash.

Okta: Setup Instructions

Step 4: Configure SAML 2.0 provider in Unleash​

Go back to Unleash Admin Dashboard and navigate to Admin Menu -> Single-Sign-On -> SAML. Fill in the values captured in the "Get the Okta Setup Instructions" step.

You may also choose to “Auto-create users”. This will make Unleash automatically create new users on the fly the first time they sign-in to Unleash with the given SSO provider (JIT). If you decide to automatically create users in Unleash you must also provide a list of valid email domains. You must also decide which root Unleash role they will be assigned (Editor role will be the default).

Unleash: SAML 2.0

Step 5: Validate​

You have now successfully configured Unleash to use SAML 2.0 together with Okta as an IdP. Please note that you also must assign users to the application defined in Okta to actually be able to log-in to Unleash.

Try signing out of Unleash. If everything is configured correctly you should be presented with the option to sign in with SAML 2.0.

Single-Sign-Out​

Available from Unleash Enterprise 4.1.0

You may also configure Unleash to to perform Single-Sign-Out. By enabling single-sign-out Unleash will redirect the user back to IdP as part of the sign-out process. You may optionally also sign the sign-out request (required by multiple IdP's such as Okta).

Step 1: Generate private key & public certificate​

(This step is only required if you intend to sign the sign-out requests).

Before you can configure single-sign-out support with Okta you are required to generate a Private Key together with a public certificate for that key. We recommend to use SHA256 certificates.

To create a public certificate and private key pair, use the proceeding commands. They work in Linux® and Mac® terminals.

openssl genrsa -out private.pem 2048
openssl req -new -x509 -sha256 -key private.pem -out cert.pem -days 1095

Answer the promoted questions, and when you complete all the steps you should end up with two files:

  • private.pem - Private certificate, required by Unleash in order to sign requests.
  • cert.pem - Public certificate, required by the IdP in order to validate requests from Unleash.

Step 2: Configure sign-out url in Okta​

Login in to Okta and navigate to your Applications. Select the "Unleash" application you created, click on "General" and then "Edit SAML Settings".

SAML 2.0 Okta edit



Next, navigate to "Configure SAML" and click "show Advanced Settings" and check the Enable Single Logout option.



SAML 2.0 Okta sing-out config



Please make sure to replace URLs with the public URL for your Unleash instance. This will require correct region prefix and the instance name. The example above uses region="us" and instance-name="ushosted".

The correct format is: https://[region].app.unleash-hosted.com/[instanceName]/auth/saml/logout/done

You need to fill out the following options:

  • Single Logout Url: https://[region].app.unleash-hosted.com/[instanceName]/auth/saml/logout/done
  • SP Issuer: https://[region].app.unleash-hosted.com/[instanceName]

Next upload the public Certificate you generated in the previous step (cert.pem) and save the Okta SAML settings. Upon completion of this step you should be provided with the ability to view setup instructions and now you should be provided with a "Identity Provider Single Logout URL"

SAML 2.0 Okta sing-out url

Step 3: Configure Single-Sign-Out in Unleash​

Go back to Unleash Admin Dashboard and navigate to Admin Menu -> Single-Sign-On -> SAML. Fill in the values captured in the "Single Logout URL" from Okta.

In the "Service Provide X.509 Certificate" field you should insert the value of your private key (private-pem). This is required in order to make Unleash able to sign logout requests.

SAML 2.0 Okta sing-out config

After you save these settings users will now be redirected to your IdP (Okta) and back to Unleash again after successfully signing out.

- + \ No newline at end of file diff --git a/how-to/how-to-add-strategy-constraints.html b/how-to/how-to-add-strategy-constraints.html index 17b2b703d1..1034579d10 100644 --- a/how-to/how-to-add-strategy-constraints.html +++ b/how-to/how-to-add-strategy-constraints.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
Skip to main content

How to add strategy constraints

Availability

Before Unleash 4.16, strategy constraints were only available to Unleash Pro and Enterprise users. From 4.16 onwards, they're available to everyone.

This guide shows you how to add strategy constraints to your feature toggles via the admin UI. For information on how to interact with strategy constraints from an Unleash client SDK, visit the specific SDKs documentation or see the relevant section in the strategy constraints documentation.

Prerequisites​

You'll need to have an existing feature toggle with a defined strategy to add a constraint. The rest of this guide assumes you have a specific strategy that you're working with.

Step 1: Open the constraints menu​

On the strategy you're working with, find and select the "edit strategy" button.

A feature toggle with one strategy. The &quot;edit strategy&quot; button is highlighted.

On the "edit strategy" screen, select the "add constraint" button to open the constraints menu.

A feature toggle strategy view showing a button labeled with add constraints.

Step 2: Add and configure the constraint​

Refer to the constraint structure section of the strategy constraints reference for a thorough explanation of the constraint fields.

  1. From the "Context Field" dropdown, select the context field you would like to constrain the strategy on and choose the constraint operator you want.
  2. Define the values to use for this constraint. The operator you selected decides whether you can define one or multiple values and what format they can have.
  3. Save the constraint first.

A strategy constraint form with a constraint set to &quot;useid&quot;. The &quot;values&quot; input is a text input containing the values &quot;41&quot;, &quot;932&quot;, &quot;822&quot;.

Step 3: Save the strategy​

A feature toggle strategy view showing a button at the end of the form labeled with save strategy.

How to update existing constraints​

To update an existing constraint, find the constraint in the "edit strategy" screen and use the constraint's "edit" button.

A strategy form showing an existing constraint with existing values and 2 buttons, the &quot;edit&quot; button is highlighted.

- + \ No newline at end of file diff --git a/how-to/how-to-add-users-to-unleash.html b/how-to/how-to-add-users-to-unleash.html index e4be70d4a6..28c488e1f2 100644 --- a/how-to/how-to-add-users-to-unleash.html +++ b/how-to/how-to-add-users-to-unleash.html @@ -20,7 +20,7 @@ - + @@ -30,7 +30,7 @@
Skip to main content

How to add new users to your Unleash instance

This feature was introduced in Unleash v4 for Unleash Open-Source.

You can add new users to Unleash in Admin > Users.

  1. From the top-line menu – click on the “Settings Wheel” then click on “Users”. A visual representation of the current step: the Unleash Admin UI with the steps highlighted.

  1. To add a new user to your Unleash instance, use the "new user" button: The Unleash users page with the &#39;add new user&#39; button being pointed to.

  2. Fill out the required fields in the "create user" form. Refer to the predefined roles overview for more information on roles.

    A form titled &quot;Add team member&quot;. It has the fields &quot;full name&quot;, &quot;email&quot;, and &quot;role&quot;. The role field is a radio button set with roles called &quot;admin&quot;, &quot;editor&quot;, and &quot;viewer&quot;.

    If you have configured an email server the user will receive the invite link in her inbox, otherwise you should share the magic invite link to Unleash presented in the confirmation dialogue.

- + \ No newline at end of file diff --git a/how-to/how-to-capture-impression-data.html b/how-to/how-to-capture-impression-data.html index 609f915084..c2addf5598 100644 --- a/how-to/how-to-capture-impression-data.html +++ b/how-to/how-to-capture-impression-data.html @@ -20,7 +20,7 @@ - + @@ -32,7 +32,7 @@ The steps below will use extracts from said documentation.

After initializing the library, you'll probably also want to identify the current user, so that events can be correlated properly:

Identify the user.
posthog.identify(userId);

Capture and transform the event​

Attach an event listener to Unleash that listens for "impression" events. Inside the listener, transform the event data to the format you want and send it to your analytics service.

Capture, transform, and send impression data.
// listen for impression events
unleash.on("impression", (event) => {

    // capture and transform events
    posthog.capture(event.eventType, {
        ...event.context,
        distinct_id: event.context?.userId,
        featureName: event.featureName,
        enabled: event.enabled,
        variant: event.variant,
    });

});

Posthog expects an object with a distinct_id property that it uses to correlate data. Additionally, you can add whatever properties you want, such as the feature toggle name, its state and/or variant, or the whole Unleash context. The posthog.capture method sends the event data to your Posthog instance.

- + \ No newline at end of file diff --git a/how-to/how-to-clone-environments.html b/how-to/how-to-clone-environments.html index 0259e0fd59..fb50088908 100644 --- a/how-to/how-to-clone-environments.html +++ b/how-to/how-to-clone-environments.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
Skip to main content

How to clone environments

availability

Environment cloning was made available in Unleash 4.19.

Environment cloning enables Unleash admins to duplicate existing environments, including all feature toggles strategies and their state.

Step 1: Navigate to the environments page​

Navigate to the Environments page in the admin UI (available at the URL /environments). Use the navigation menu item "Configure" and select "Environments".

The admin UI navigation &quot;Configure&quot; submenu with the Environments item highlighted.

Step 2: Select an environment to clone​

Select an environment to clone. On the right side, open the actions submenu and select "Clone".

The &quot;production&quot; environment actions submenu with the Clone option highlighted.

Step 3: Fill in the clone environment form​

Give your new environment a name. The name must be unique and cannot be the same as the original environment. The name is pre-filled with a suggestion, but you can change it to whatever you like.

Select an environment type, which projects should have their environment configuration cloned, and whether to keep the existing user permissions for the new environment.

The clone environment form filled with some example data, and the Clone environment button highlighted at the bottom.

You can optionally generate an API token for the new environment right away. Select which projects the token should have access to, and the token will be generated when you submit the form.

The clone environment form with the API Token section highlighted and the Generate an API token now option selected

The token details with the &quot;Copy Token&quot; element highlighted.

You can always create API tokens for the new environment by following the Generating an API token guide.

- + \ No newline at end of file diff --git a/how-to/how-to-create-and-assign-custom-project-roles.html b/how-to/how-to-create-and-assign-custom-project-roles.html index 9f211c7ba5..bb086a117d 100644 --- a/how-to/how-to-create-and-assign-custom-project-roles.html +++ b/how-to/how-to-create-and-assign-custom-project-roles.html @@ -20,7 +20,7 @@ - + @@ -36,7 +36,7 @@ A project overview with the &#39;access&#39; tab highlighted.
  • This step depends on whether the user has already been added to the project or not:
    • - + \ No newline at end of file diff --git a/how-to/how-to-create-and-assign-custom-root-roles.html b/how-to/how-to-create-and-assign-custom-root-roles.html index d18ed6f0b4..05a0b57f9a 100644 --- a/how-to/how-to-create-and-assign-custom-root-roles.html +++ b/how-to/how-to-create-and-assign-custom-root-roles.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    How to create and assign custom root roles

    availability

    Custom root roles were introduced in Unleash 5.4 and are only available in Unleash Enterprise.

    This guide takes you through how to create and assign custom root roles. Custom root roles allow you to fine-tune access rights and permissions to root resources in your Unleash instance.

    Creating custom root roles​

    Step 1: Navigate to the custom root roles page​

    Navigate to the roles page in the admin UI (available at the URL /admin/roles). Use the settings button in the navigation menu and select "roles".

    The admin UI admin menu with the Roles item highlighted.

    Step 2: Click the "new root role" button.​

    Use the "new root role" button to open the "new root role" form.

    The &quot;root roles&quot; table with the &quot;new root role&quot; button highlighted.

    Step 3: Fill in the root role form​

    Give the root role a name, a description, and the set of permissions you'd like it to have. For a full overview of all the options, consult the custom root roles reference documentation.

    The root role form filled with some example data, and the &quot;add role&quot; button highlighted at the bottom.

    Assigning custom root roles​

    You can assign custom root roles just like you would assign any other predefined root role. Root roles can be assigned to users, service accounts, and groups.

    - + \ No newline at end of file diff --git a/how-to/how-to-create-and-display-banners.html b/how-to/how-to-create-and-display-banners.html index fabbf4129f..fee47f9a4b 100644 --- a/how-to/how-to-create-and-display-banners.html +++ b/how-to/how-to-create-and-display-banners.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    How to create and display banners

    Availability

    Banners were introduced as a beta feature in Unleash 5.6 and are only available in Unleash Enterprise. We plan to make this feature generally available to all Enterprise users in Unleash 5.7.

    This guide takes you through how to create and display banners.

    Creating banners​

    Step 1: Navigate to the banners page​

    Navigate to the banners page in the admin UI (available at the URL /admin/banners). Use the settings button in the navigation menu and select "banners".

    The admin UI admin menu with the Banners item highlighted.

    Step 2: Use the "new banner" button​

    Use the "new banner" button to open the "new banner" form.

    The &quot;banners&quot; table with the &quot;new banner&quot; button highlighted.

    Step 3: Fill in the banner form​

    Choose whether the banner should be enabled right away. If enabled, the banner will be visible to all users in your Unleash instance. Select the banner type, icon, and write the message that you'd like to see displayed on the banner. The message and dialog fields support Markdown. Optionally, you can also configure a banner action for user interactivity. For a full overview of all the banner options, consult the banners reference documentation.

    You'll be able to preview the banner at the top as you fill in the form.

    Once you're satisfied, use the "add banner" button to create the banner.

    The banner form filled with some example data, and the &quot;add banner&quot; button highlighted at the bottom.

    Displaying banners​

    You can choose whether a banner is currently displayed to all users of your Unleash instance by toggling the "enabled" switch on the banner table.

    Alternatively, you can edit the banner by using the "edit" button on the banner table and then toggle the "banner status" switch.

    The &quot;banners&quot; table with some example data, and the &quot;enable&quot; switch highlighted.

    - + \ No newline at end of file diff --git a/how-to/how-to-create-and-manage-user-groups.html b/how-to/how-to-create-and-manage-user-groups.html index 1a7bed126f..982fc21dfb 100644 --- a/how-to/how-to-create-and-manage-user-groups.html +++ b/how-to/how-to-create-and-manage-user-groups.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    How to create and manage user groups

    availability

    User groups are available to Unleash Enterprise users since Unleash 4.14.

    This guide takes you through how to use user groups to manage permissions on your projects. User groups allow you to manage large groups of users more easily than assigning roles directly to those users. Refer to the section on user groups in the RBAC documentation for more information.

    Creating user groups​

    1. Navigate to groups by using the admin menu (the gear icon) and selecting the groups option.

    The Unleash Admin UI with the steps highlighted to navigate to groups.

    1. Navigate to new group.

    The groups screen with the new group button highlighted.

    1. Give the group a name, an optional description, an optional root role, and select the users you'd like to be in the group.

    The new group screen with the users drop down open and highlighted.

    1. Review the details of the group and save them if you're happy.

    The new group screen with the users selected and the save button highlighted.

    Managing users within a group​

    1. Navigate to groups by using the admin menu (the gear icon) and selecting the groups option.

    The Unleash Admin UI with the steps highlighted to navigate to groups.

    1. Select the card of the group you want to edit.

    The manage groups with a pointer to a group card.

    1. Remove users by using the remove user button (displayed as a bin).

    The manage group page with the remove user button highlighted.

    1. Confirm the remove.

    The manage group page with the confirm user removal dialog shown.

    1. Add users by selecting the add button.

    The groups page shown with the add user button highlighted.

    1. Find the user you'd like to add to the group and select them.

    The groups page shown with a user selected.

    1. Review the group users and save when you're happy.

    The edit groups page shown with the save button highlighted.

    Assigning groups to projects​

    1. Navigate to projects

    The landing page with the projects navigation link highlighted.

    1. Select the project you want to manage.

    The projects page with a project highlighted.

    1. Navigate to the access tab and then use the assign user/group button.

    The project page with the access tab and assign button highlighted.

    1. Find your group in the drop down.

    The access sidepane for a project with a group selected.

    1. Select the role that the group should have in this project. You can review the list of permissions that the group users will gain by having this role before confirming.

    The access sidepane for a project with a role selected.

    - + \ No newline at end of file diff --git a/how-to/how-to-create-api-tokens.html b/how-to/how-to-create-api-tokens.html index 9833216c7f..8574691128 100644 --- a/how-to/how-to-create-api-tokens.html +++ b/how-to/how-to-create-api-tokens.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    How to create API Tokens

    Permissions

    Creating API tokens requires you to have the CREATE_API_TOKEN permission. This means that, as of now, only instance admins can create API tokens.

    All users can see tokens with CLIENT level access, but only instance admins can see tokens with ADMIN level access.

    Unleash SDKs use API tokens to authenticate to the Unleash API. Unleash supports different types of API tokens, each with different levels of access and privileges. Refer to the API tokens and client keys article for complete overview of the different token types.

    Step 1: Navigate to the API token creation form​

    Navigate to the API access page in the admin UI (available at the URL /admin/api). Use the navigation menu item "Configure" and select "API access".

    The admin UI navigation &quot;Configure&quot; submenu with the API access item highlighted.

    On the API access page, use the "New API token" button to navigate to the token creation form.

    The API access page with the &quot;New API token&quot; button highlighted.

    Step 2: Fill in the API token form​

    API token creation form.

    Fill in the form with the desired values for the token you want to create. Refer to the API tokens and client keys article for a detailed explanation of what all the fields mean.

    Using API tokens​

    When you have created the API token, it will be listed on the API access page. If you have the required permissions to see the token, you can copy it for easy use in your applications.

    API access token table with a &quot;copy token&quot; button highlighted.

    - + \ No newline at end of file diff --git a/how-to/how-to-create-feature-toggles.html b/how-to/how-to-create-feature-toggles.html index 28d2ae839e..51a8fec71c 100644 --- a/how-to/how-to-create-feature-toggles.html +++ b/how-to/how-to-create-feature-toggles.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    How to create a feature flag

    Feature flags or feature toggles?

    This document uses feature flags and feature toggles interchangeably. Some people prefer flag; others prefer toggle. We use both - they are synonyms for us.

    Feature Flags (or Feature toggles in the UI) are the foundation of Unleash. They are at the core of everything we do and are a fundamental building block in any feature management system. This guide shows you how to create feature flags in Unleash and how to add any optional constraints, segments, variants, and more. Links to learn more about these concepts will be scattered throughout the text.

    You can perform every action both via the UI and the admin API. This guide includes screenshots to highlight the relevant UI controls and links to the relevant API methods for each step.

    This guide is split into three sections:

    1. Prerequisites: you need these before you can create a flag.
    2. Required steps: all the required steps to create a flag and activate it in production.
    3. Optional steps: optional steps you can take to further target and configure your feature flag and its audience.

    Prerequisites​

    To perform all the steps in this guide, you will need:

    • A running Unleash instance
    • A project to hold the flag
    • A user with an editor or admin role OR a user with the following permissions inside the target project:
    roles

    Refer to the documentation on role-based access control for more information about the available roles and their permissions.

    Required steps​

    This section takes you through the required steps to create and activate a feature toggle. It assumes that you have all the prerequisites from the previous section done.

    Step 1: Create a toggle​

    API: create a toggle

    Use the Admin API endpoint for creating a feature toggle. The payload accepts all the same fields as the Admin UI form. The Admin UI also displays the corresponding cURL command when you use the form.

    In the project that you want to create the toggle in, use the "new feature toggle" button and fill the form out with your desired configuration. Refer to the feature toggle reference documentation for the full list of configuration options and explanations.

    Step 2: Add a strategy​

    API: Add a strategy

    Use the API for adding a strategy to a feature toggle. You can find the configuration options for each strategy in the activation strategy reference documentation.

    Decide which environment you want to enable the toggle in. Select that environment and add an activation strategy. Different activation strategies will act differently as described in the activation strategy documentation. The configuration for each strategy differs accordingly. After selecting a strategy, complete the steps to configure it.

    Step 3: Enable the toggle​

    API: Enable a toggle

    Use the API for enabling an environment for a toggle and specify the environment you'd like to enable.

    Use the environments toggles to switch on the environment that you chose above. Depending on the activation strategy you added in the previous step, the toggle should now evaluate to true or false depending on the Unleash context you provide it.

    Optional steps​

    These optional steps allow you to further configure your feature toggles to add optional payloads, variants for A/B testing, more detailed user targeting and exceptions/overrides.

    Add constraints and segmentation​

    Constraints and segmentation allow you to set filters on your strategies, so that they will only be evaluated for users and applications that match the specified preconditions. Refer to the strategy constraints and segments reference documentation for more information.

    To add constraints and segmentation, use the "edit strategy" button for the desired strategy.

    Constraints​

    info

    Constraints aren't fixed and can be changed later to further narrow your audience. You can add them either when you add a strategy to a toggle or at any point thereafter.

    API: Add constraints

    You can either add constraints when you add the strategy or PUT or PATCH the strategy afterwards

    In the strategy configuration screen for the strategy that you want to configure, use the "add constraint" button to add a strategy constraint.

    Segments​

    info

    This can be done after you have created a strategy.

    API: add segments

    Use the API for adding segments to a strategy to add segments to your strategy.

    In the strategy configuration screen for the strategy that you want to configure, use the "select segments" dropdown to add segments.

    Add variants​

    info

    This can be done at any point after you've created your toggle.

    API: add variants

    Use the update variants endpoint. The payload should be your desired variant configuration.

    Variants give you the ability to further target your users and split them into groups of your choosing, such as for A/B testing. On the toggle overview page, select the variants tab. Use the "new variant" button to add the variants that you want.

    1. Prior to Unleash 4.21, "create/edit variants" was a project-level permission instead of an environment-level permission.↩
    - + \ No newline at end of file diff --git a/how-to/how-to-create-personal-access-tokens.html b/how-to/how-to-create-personal-access-tokens.html index 40979455c7..e5aa0c6e2d 100644 --- a/how-to/how-to-create-personal-access-tokens.html +++ b/how-to/how-to-create-personal-access-tokens.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    How to create Personal Access Tokens

    availability

    Personal access tokens are planned to be released in Unleash 4.17.

    Personal access tokens are a tool to enable a user to use the Admin API as themselves with their own set of permissions, rather than using an admin token. See how to use the Admin API for more information.

    Step 1: Navigate to the personal access tokens page​

    Open the user profile pane in the admin UI and select the view user profile menu item (available at the URL /profile).

    The admin UI navigation &quot;user profile&quot; menu with the view user profile menu item selected.

    Select the "Personal Access Tokens" menu item.

    The user profile page with the &quot;Personal Access Tokens&quot; menu item highlighted.

    Step 2: Navigate to New Token​

    Navigate to "New Token".

    The New Token element highlighted.

    Step 3: Fill in the create personal API token form and create it​

    Give your token a description and optionally set an expiry date. By default the expiry date is set to 30 days.

    The New Token form with the description text box and create element highlighted.

    Step 4: Save your token​

    Once your new token is created, the popup will display the new token details. You must save your token somewhere outside of Unleash, you won't be able to access it again.

    The token created popup with the &quot;Copy Token&quot; element highlighted.

    Your personal access token can now be used in place of an admin token.

    - + \ No newline at end of file diff --git a/how-to/how-to-create-project-api-tokens.html b/how-to/how-to-create-project-api-tokens.html index 92ce634766..674c424a74 100644 --- a/how-to/how-to-create-project-api-tokens.html +++ b/how-to/how-to-create-project-api-tokens.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    How to create Project API Tokens

    Permissions

    Creating Project API tokens requires you to have the CREATE_PROJECT_API_TOKEN permission.

    Unleash SDKs use API tokens to authenticate to the Unleash API. Unleash supports different types of API tokens, each with different levels of access and privileges. Refer to the API tokens and client keys article for complete overview of the different token types.

    Step 1: Navigate to the API token creation form​

    Navigate to the Project API access page in the admin UI (available at the URL /admin/projects/<project-name>/api-access). Use the navigation tab "Project Settings" and select "API access".

    The Project overview &quot;Project settings&quot; submenu with the API access item highlighted.

    On the API access page, use the "New API token" button to navigate to the token creation form.

    The Project API access page with the &quot;New API token&quot; button highlighted.

    Step 2: Fill in the API token form​

    Project API token creation form.

    Fill in the form with the desired values for the token you want to create. Refer to the API tokens and client keys article for a detailed explanation of what all the fields mean.

    Using Project API tokens​

    When you have created the Project API token, it will be listed on the Project API access page. If you have the required permissions to see the token (READ_PROJECT_API_TOKEN), you can copy it for easy use in your applications.

    API access token table with a &quot;copy token&quot; button highlighted.

    - + \ No newline at end of file diff --git a/how-to/how-to-create-service-accounts.html b/how-to/how-to-create-service-accounts.html index 931421b9aa..901c369f2a 100644 --- a/how-to/how-to-create-service-accounts.html +++ b/how-to/how-to-create-service-accounts.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    How to create service accounts

    availability

    Service accounts is an enterprise feature available from Unleash 4.21 onwards.

    Service accounts enable Unleash admins to create accounts that act as users and respect the same set of permissions, however they do not have a password and cannot log in to the Unleash UI. Instead, they are intended to be used to access the Unleash API programatically.

    Step 1: Navigate to the service accounts page​

    Navigate to the service accounts page in the admin UI (available at the URL /admin/service-accounts). Use the settings button in the navigation menu and select "service accounts".

    The admin UI navigation settings submenu with the Service accounts item highlighted.

    Step 2: Click the "new service account" button​

    Use the "new service account" button to open the "new service account" form.

    The &quot;service accounts&quot; table with the &quot;new service account&quot; button highlighted.

    Step 3: Fill in the service account form​

    Give your new service account a name. After leaving the name field, the username field is pre-filled with a suggestion based on the name you entered, but you can change it to whatever you like.

    Select a root role for your service account, which will define what your new service account will be allowed to do. The roles that you can assign to service accounts are the same ones that are available for regular users.

    The service account form filled with some example data, and the &quot;add service account&quot; button highlighted at the bottom.

    You can optionally generate a token for the new service account right away. Give your token a description and optionally set an expiry date. By default the expiry date is set to 30 days. The token will be generated when you submit the form.

    The service account form with the token section highlighted and the &quot;generate a token now&quot; option selected

    The token details with the &quot;copy token&quot; element highlighted.

    Managing service account tokens​

    You can later manage service account tokens by editing the respective service account. This allows you to add new tokens to that service account or delete existing ones.

    The service account table with the &quot;edit&quot; button highlighted.

    The service account form with the tokens table highlighted

    - + \ No newline at end of file diff --git a/how-to/how-to-define-custom-context-fields.html b/how-to/how-to-define-custom-context-fields.html index 8a8416e97f..15fdff7c85 100644 --- a/how-to/how-to-define-custom-context-fields.html +++ b/how-to/how-to-define-custom-context-fields.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    How to define custom context fields

    Availability

    Before Unleash 4.16, custom context fields were only available to Unleash Pro and Enterprise users. From 4.16 onwards, they're available to everyone. They were introduced in Unleash 3.2.28.

    This guide shows you how to create custom context field for the Unleash Context. You can use custom context fields for strategy constraints and for custom stickiness calculations. If there are standard Unleash Context fields missing from the context fields page, you can use the same steps to add them too.

    Step 1: Navigate to the context field creation form​

    In the Unleash Admin UI, navigate to the context fields page:

    1. Click the "Configure" button in the top menu to open the configuration dropdown menu.

    2. Click the "Context fields" menu item.

      A visual representation of the tutorial steps described in the preceding paragraph, showing the interaction points in the admin UI in order.

    3. On the context fields page, click the "add new context field" button.

      The &quot;context fields&quot; page with the &quot;add new context field&quot; button highlighted.

    Step 2: Define the new context field​

    Define the custom context field by filling out the form. You must at least give the field a unique name. Everything else is optional. Refer to the custom context field reference guide for a full overview of the parameters and their functions and requirements.

    When you are satisfied with the context field's values, use the "create" button to submit the form and save the context field.

    A &quot;create context field&quot; form. It contains data for a custom context field called &quot;region&quot;. Its description is &quot;allows you to constrain on specific regions&quot; and its legal values are &quot;Africa&quot;, &quot;Asia&quot;, &quot;Europe&quot;, and &quot;North America&quot;. Its custom stickiness value is not shown.

    - + \ No newline at end of file diff --git a/how-to/how-to-download-login-history.html b/how-to/how-to-download-login-history.html index b5424d3729..38c2b05d44 100644 --- a/how-to/how-to-download-login-history.html +++ b/how-to/how-to-download-login-history.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    How to download your login history

    availability

    Login history is an enterprise feature available from Unleash 4.22 onwards.

    Login history enables Unleash admins to audit login events and their respective information, including whether they were successful or not.

    Step 1: Navigate to the login history page​

    Navigate to the login history page in the admin UI (available at the URL /admin/logins). Use the settings button in the navigation menu and select "login history".

    The admin UI navigation settings submenu with the login history item highlighted.

    Step 2: Click the "Download login history" button​

    Use the "download login history" button to proceed with the download of the login history as CSV.

    The login history table with the &quot;download login history&quot; button highlighted.

    - + \ No newline at end of file diff --git a/how-to/how-to-enable-openapi.html b/how-to/how-to-enable-openapi.html index 9f0cb5a0d8..f0f55ecd6f 100644 --- a/how-to/how-to-enable-openapi.html +++ b/how-to/how-to-enable-openapi.html @@ -20,7 +20,7 @@ - + @@ -29,7 +29,7 @@
    Skip to main content

    How to enable OpenAPI and the Swagger UI

    Availability

    OpenAPI schemas were introduced in v4.13.0 of Unleash and v0.10.0 of the Unleash proxy. Since v5.2.0 Unleash has OpenAPI enabled by default.

    Both Unleash and the Unleash proxy have included OpenAPI schemas and Swagger UIs for their APIs. The schemas can be used to get an overview over all API operations and to generate API clients using OpenAPI client generators. The Swagger UI lets you see and try out all the available API operations directly in your browser.

    To enable the OpenAPI documentation and the Swagger UI, you must start Unleash or the proxy with the correct configuration option. The following section shows you how. The methods are the same for both Unleash and the Unleash proxy, so the steps described in the next section will work for either.

    Location of the OpenAPI spec​

    Once you enable OpenAPI, you can find the specification in JSON format at /docs/openapi.json and the swagger UI at /docs/openapi.

    For instance, if you're running the Unleash server locally at http://localhost:4242, then

    • the JSON specification will be at http://localhost:4242/docs/openapi.json
    • the Swagger UI will be at http://localhost:4242/docs/openapi

    Similarly, if you're running the Unleash proxy locally at http://localhost:3000 (so that the proxy endpoint is at http://localhost:3000/proxy), then

    • the JSON specification will be at http://localhost:3000/docs/openapi.json
    • the Swagger UI will be at http://localhost:3000/docs/openapi

    Step 1: enable OpenAPI​

    The OpenAPI spec and the Swagger UI can be turned on either via environment variables or via configuration options. Configuration options take precedence over environment variables.

    If you are using Unleash v5.2.0, OpenAPI is enabled by default. You still need to enable it for Unleash proxy.

    Enable OpenAPI via environment variables​

    To turn on OpenAPI via environment variables, set the ENABLE_OAS to true in the environment you're running the server in.

    Enable OpenAPI via an environment variable
    export ENABLE_OAS=true

    Enable OpenAPI via configuration options​

    The configuration option for enabling OpenAPI and the swagger UI is enableOAS. Set this option to true.

    The following examples have been shortened to show the only the relevant configuration options. For more detailed instructions on how to run Unleash or the proxy, refer to how to run the Unleash proxy or the section on running Unleash via Node.js from the deployment section of the documentation.

    Enable OpenAPI for Unleash via configuration option
    const unleash = require('unleash-server');

    unleash
        .start({
            // ... Other options elided for brevity
            enableOAS: true,
        })
        .then((unleash) => {
            console.log(
                `Unleash started on http://localhost:${unleash.app.get('port')}`,
            );
        });
    - + \ No newline at end of file diff --git a/how-to/how-to-environment-import-export.html b/how-to/how-to-environment-import-export.html index 1724f8f909..4468326c34 100644 --- a/how-to/how-to-environment-import-export.html +++ b/how-to/how-to-environment-import-export.html @@ -20,7 +20,7 @@ - + @@ -29,7 +29,7 @@
    Skip to main content

    Environment Import & Export

    Availability

    The environment import and export first appeared in Unleash 4.22.0.

    Environment export and import lets you copy feature configurations from one environment to another and even copy features from one Unleash instance to another.

    When exporting, you select a set of features and one environment to export the configuration from. The environment must be the same for all features.

    Then, when you import, you must select one environment and one project to import into. All features are imported into that project in that environment. If Unleash is unable to import the configuration safely, it will tell you why the import failed and what you need to fix it (read more about import requirements.

    Import & Export items​

    When you export features, the export will contain both feature-specific configuration and global configuration.

    On the project-level these items are exported:

    On the environment-level, these items are exported for the chosen environment:

    Additionally, these global configuration items are exported:

    Importantly, while references to segments are exported, the segments themselves are not exported. Consult the import requirements section for more information.

    Export​

    You can export features either from a project search or the global feature search. Use the search functionality to narrow the results to the list of features you want to export and use the export button to select environment. All features included in your search results will be included in the export.

    Import​

    Import is a 3 stage process designed to be efficient and error-resistant.

    Import stages​

    • upload - you can upload previously exported JSON file or copy-paste export data from the exported JSON file into the code editor
    • validation - you will get feedback on any errors or warnings before you do the actual import. This ensures your feature flags configurations are correct. You will not be able to finish the import if you have errors. Warnings don't stop you from importing.
    • import - the actual import that creates a new configuration in the target environment or creates a [change request]/reference/change-requests.md) when the environment has change requests enabled

    The import UI. It has three stages: import, file, validate configuration, finish import.

    Import requirements​

    Unleash will reject an import if it discovers conflicts between the data to be imported and what already exists on the Unleash instance. The import tool will tell you about why an import is rejected in these cases.

    The following sections describe requirements that must be met for Unleash not to stop the import job.

    Context fields​

    When you import a custom context field with legal values defined:

    If a custom context field with the same name already exists in the target instance, then the pre-existing context field must have at least those legal values defined. In other words, the imported context field legal values must be a subset of the already existing context field's legal values.

    When you import custom context fields without legal values or custom context fields that don't already exist in the target instance, then there are no requirements.

    Custom context fields that don't already exist in the target instance will be created upon import.

    Segments​

    If your import has segments, then a segment with the same name must already exist in the Unleash instance you are trying to import into. Only the name must be the same: the constraints in the segment can be different.

    Dependencies​

    If your import has a parent feature dependency, then the parent feature must already exist in the target Unleash instance or be part of the import data. The existing feature is identified by name.

    Custom strategies​

    If your import contains custom strategies, then custom strategies with the same names must already exist in the target Unleash instance. The custom strategy definitions (including strategy parameters) that exist in the target instance do not otherwise need to match the custom strategy definitions in the instance the import came from.

    Existing features​

    If any of the features you import already exist in the target Unleash instance, then they must exist within the project you're importing into. If any features you are attempting to import exist in a different project on the target instance, the import will be rejected.

    Pending change requests​

    The project and environment you are importing into must not have any pending change requests.

    Import warnings​

    The import validation system will warn you about potential problems it finds in the import data. These warnings do not prevent you from importing the data, but you should read them carefully to ensure that Unleash does as you intend.

    The following sections list things that the import tool will warn you about.

    Archived features​

    The import tool will not import any features that have already been archived on the target Unleash instance. Because features are identified by their name, that means that if a feature called feature-a has been created and archived on the target Unleash instance, then a feature with the same name (feature-a) will not be imported.

    If you permanently delete the archived feature-a from the target instance, then the new feature-a (in the import data) will be imported.

    Custom strategies​

    Unleash will verify that any custom strategies you are trying to import have already been defined on the target instance. However, it only does this verification by name. It does not validate that the definitions are otherwise the same or that they have the same configuration parameters.

    Required permissions​

    To import features, you will always require the update feature toggles permission. Additionally, depending on the actions your import job would trigger, you may also require any of the following permissions:

    • Create feature toggles: when the import would create new features
    • Update tag types: when the import would create new tag types
    • Create context fields: when the import would create new context fields
    • Create activation strategies: when the import would add activation strategies to a feature and change requests are disabled
    • Delete activation strategies: when import would remove existing activation strategies from a feature and change requests are disabled
    • Update variants: when the import would update variants and change requests are disabled
    • Update feature dependency: when the import would add feature dependencies and change requests are disabled

    Import and change requests​

    If change requests are enabled for the target project and environment, the import will not be fully applied. Any new features will be created, but all feature configuration will be added to a new change request.

    If change requests are enabled, any permissions for Create activation strategies, Delete activation strategies and Update variants are not required.

    Environment import/export vs the instance import/export API​

    Environment import/export has some similarities to the instance import/export API, but they serve different purposes.

    The instance import/export API was designed to export all feature toggles (optionally with strategies and projects) from one Unleash instance to another. When it was developed, Unleash had much fewer features than it does now. As such, the API lacks support for some of the more recent features in Unleash.

    On the other hand, the environment import/export feature was designed to export a selection of features based on search criteria. It can only export data from a single environment and only import it to a single environment. It also only supports importing into a single project (although it can export features from multiple projects).

    Further, the environment import/export comes with a much more stringent validation and will attempt to stop any corrupted data imports.

    - + \ No newline at end of file diff --git a/how-to/how-to-import-export.html b/how-to/how-to-import-export.html index ef0b7bb56b..bc1d6f11ee 100644 --- a/how-to/how-to-import-export.html +++ b/how-to/how-to-import-export.html @@ -20,7 +20,7 @@ - + @@ -30,7 +30,7 @@
    Skip to main content

    [Deprecated] Import & Export

    Availability

    The import and export API first appeared in Unleash 3.3.0.

    Deprecation notice

    Api admin state is deprecated from version 5. We recommend using the new Environment Import & Export.

    Unleash supports import and export of feature toggles and strategies at startup and during runtime. The main purpose of the import/export feature is to bootstrap new Unleash instances with feature toggles and their configuration. If you are looking for a granular way to keep separate Unleash instances in sync we strongly recommend that you take a look at the Unleash Admin APIs.

    The import mechanism guarantees that:

    • all imported features will be non-archived
    • existing updates to strategies and features are included in the event history

    All import mechanisms support a drop parameter which will clean the database before import (all strategies and features will be removed).

    Dropping in production

    Be careful when using the drop parameter in production environments: cleaning the database could lead to unintended loss of data.

    Runtime import & export​

    State Service​

    Unleash returns a StateService when started, you can use this to import and export data at any time.

    const unleash = require('unleash-server');

    const { services } = await unleash.start({...});
    const { stateService } = services;

    const exportedData = await stateService.export({includeStrategies: false, includeFeatureToggles: true, includeTags: true, includeProjects: true});

    await stateService.import({data: exportedData, userName: 'import', dropBeforeImport: false});

    await stateService.importFile({file: 'exported-data.yml', userName: 'import', dropBeforeImport: true})

    If you want the database to be cleaned before import (all strategies and features will be removed), set the dropBeforeImport parameter.

    It is also possible to not override existing feature toggles (and strategies) by using the keepExisting parameter.

    API Export​

    The api endpoint /api/admin/state/export will export feature-toggles and strategies as json by default. You can customize the export with query parameters:

    ParameterDefaultDescription
    formatjsonExport format, either json or yaml
    downloadfalseIf the exported data should be downloaded as a file
    featureTogglestrueInclude feature-toggles in the exported data
    strategiestrueInclude strategies in the exported data
    tagstrueInclude tagtypes, tags and feature_tags in the exported data
    projectstrueInclude projects in the exported data

    For example if you want to download just feature-toggles as yaml:

    Export features (and nothing else) as YAML.
    GET <unleash-url>/api/admin/state/export?format=yaml&featureToggles=1&strategies=0&tags=0&projects=0&download=1
    Authorization: <API-token>
    content-type: application/json

    API Import​

    Importing environments in Unleash 4.19 and below

    This is only relevant if you use Unleash 4.19 or earlier:

    If you import an environment into an instance that already has that environment defined, Unleash will delete any API keys created specifically for that environment. This is to prevent unexpected access to the newly imported environments.

    You can import feature-toggles and strategies by POSTing to the /api/admin/state/import endpoint (keep in mind this will require authentication).\ You can either send the data as JSON in the POST-body or send a file parameter with multipart/form-data (YAML files are also accepted here).

    You can customize the import with query parameters:

    ParameterDefaultDescription
    dropfalseIf the database should be cleaned before import (see comment below)
    keeptrueIf true, the existing feature toggles and strategies will not be overridden

    If you want the database to be cleaned before import (all strategies and features will be removed), specify a drop query parameter.

    caution

    You should be cautious about using the drop query parameter in production environments.

    Example usage:

    Import data into Unleash.
    POST <unleash-url>/api/admin/state/import
    Authorization: <API-token>
    content-type: application/json

    {
      "version": 3,
      "features": [
        {
          "name": "a-feature-toggle",
          "enabled": true,
          "description": "#1 feature-toggle"
        }
      ]
    }

    Startup import​

    You can import toggles and strategies on startup by using an import file in JSON or YAML format. As with other forms of imports, you can also choose to remove the current toggle and strategy configuration in the database before importing.

    Unleash lets you do this both via configuration parameters and environment variables. The relevant parameters/variables are:

    config parameterenvironment variabledefaultvalue
    importFileIMPORT_FILEnonepath to the configuration file
    dropBeforeImportIMPORT_DROP_BEFORE_IMPORTfalsewhether to clean the database before importing the file

    Importing files​

    To import strategies and toggles from a file (called configuration.yml in the examples below), either

    • use the importFile parameter to point to the file (you can also pass this into the unleash.start() entry point)

      unleash-server --databaseUrl [...] \
                 --importFile configuration.yml

    • set the IMPORT_FILE environment variable to the path of the file before starting Unleash

      IMPORT_FILE=configuration.yml

    Drop before import​

    caution

    You should never use this in production environments.

    To remove pre-existing feature toggles and strategies in the database before importing the new ones, either:

    • add the dropBeforeImport flag to the unleash-server command (or to unleash.start())

      unleash-server --databaseUrl [...] \
                 --importFile configuration.yml \
                 --dropBeforeImport

    • set the IMPORT_DROP_BEFORE_IMPORT environment variable (note the leading IMPORT_) to true, t, or 1. The variable is case-sensitive.

      IMPORT_DROP_BEFORE_IMPORT=true
    - + \ No newline at end of file diff --git a/how-to/how-to-manage-public-invite-tokens.html b/how-to/how-to-manage-public-invite-tokens.html index 6ae94a7ff6..e2f9a8e0d7 100644 --- a/how-to/how-to-manage-public-invite-tokens.html +++ b/how-to/how-to-manage-public-invite-tokens.html @@ -20,7 +20,7 @@ - + @@ -29,7 +29,7 @@
    Skip to main content

    How to manage public invite tokens

    Public invite links let you invite new members to an Unleash instance. A key part of an invite link is the public invite token. This guide shows you how to use the Unleash admin UI to create, update, and delete public invite tokens. You can also manage public signup tokens via the Unleash API.

    Only Unleash instance admins have the necessary permissions to create and manage public invite tokens.

    Creating a token​

    1. Navigate to the users page in Unleash and use the create invite link button

    The settings menu in the Unleash nav bar with the &quot;users&quot; link highlighted.

    The Unleash users page. There is a separate &quot;create invite link&quot; section above the list of users.

    1. Fill out the "create invite link" form and (optionally) copy the invite link. You can always get the link later. A short form with only one field: token expiry.

    An &quot;invite link created&quot; modal. It contains an invite link that can be copied and some info on how to use it.

    Updating/Deleting a token​

    1. Follow the steps in the previous paragraph to navigate to the users page.
    2. When you have an active invite token, use the button labeled "update invite link".
    3. Use the form to edit the expiry for the token or to delete it entirely.
    - + \ No newline at end of file diff --git a/how-to/how-to-run-the-unleash-proxy.html b/how-to/how-to-run-the-unleash-proxy.html index ea8b124481..f02254e4a4 100644 --- a/how-to/how-to-run-the-unleash-proxy.html +++ b/how-to/how-to-run-the-unleash-proxy.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    How to run the Unleash Proxy

    Placeholders

    Placeholders in the code samples below are delimited by angle brackets (i.e. <placeholder-name>). You will need to replace them with the values that are correct in your situation for the code samples to run properly.

    The Unleash Proxy provides a way for you to consume feature toggles in front-end clients, such as the JavaScript Proxy client and React Proxy client.

    Depending on your setup, the Proxy is most easily run in one of two ways, depending on your situation:

    If you're using a hosted version of Unleash, we can also run the proxy for you.

    Prerequisites​

    This is what you need before you can run the proxy:

    • A running Unleash server to connect to. You'll need its API path (e.g. https://app.unleash-hosted.com/demo/api) to connect the proxy to it.
    • A client API token for the proxy to use.
    • If you're running the Proxy via Docker: the docker command line tool.
    • If you're running the Proxy as a Node.js app: Node.js and its command line tools.
    • A Proxy client key. This can be any arbitrary string (for instance: proxy-client-key). Use this key when connecting a client SDK to the Proxy.

    How to run the Proxy via Docker​

    We provide a Docker image (available on on Docker Hub) that you can use to run the proxy.

    1. Pull the Proxy image​

    Use the docker command to pull the Proxy image:

    Pull the Unleash Proxy docker image
    docker pull unleashorg/unleash-proxy

    2. Start the Proxy​

    When running the Proxy, you'll need to provide it with at least the configuration options listed below. Check the reference docs for the full list of configuration options.

    Run the Unleash Proxy via Docker
    docker run \
        -e UNLEASH_PROXY_CLIENT_KEYS=<proxy-client-key> \
        -e UNLEASH_URL='<unleash-api-url>' \
        -e UNLEASH_API_TOKEN=<client-api-token> \
        -p 3000:3000 \
        unleashorg/unleash-proxy

    If the proxy starts up successfully, you should see the following output:

    Unleash-proxy is listening on port 3000!

    How to run the Proxy as a Node.js app​

    To run the Proxy via Node.js, you'll have to create your own Node.js project and use the Unleash Proxy as a dependency.

    1. initialize the project​

    If you don't already have an existing Node.js project, create one:

    npm init

    2. Install the Unleash Proxy package​

    Install the Unleash Proxy as a dependency:

    npm install @unleash/proxy

    3. Configure and start the proxy​

    Import the createApp function from @unleash/proxy and configure the proxy. You'll need to provide at least the configuration options highlighted below. Check the reference docs for the full list of configuration options.

    Here is an example of what running the Proxy as a Node.js app might look like:

    Sample app running the Unleash Proxy
    const port = 3000;

    const { createApp } = require('@unleash/proxy');

    const app = createApp({
        unleashUrl: '<unleash-api-url>',
        unleashApiToken: '<client-api-token>',
        clientKeys: ['<proxy-client-key>'],
        proxyPort: 3000,
    });

    app.listen(port, () =>
        console.log(`Unleash Proxy listening on http://localhost:${port}/proxy`),
    );

    Verify that the proxy is working​

    When the proxy process has started up correctly, you can start querying its /proxy endpoint. If it's running correctly, you'll get back a JSON object with a list of toggles. The list may be empty if you haven't added any toggles for the corresponding project/environment yet.

    Request toggles from the Unleash Proxy
    GET <proxy-url>/proxy
    Authorization: <proxy-client-key>
    content-type: application/json
    - + \ No newline at end of file diff --git a/how-to/how-to-schedule-feature-releases.html b/how-to/how-to-schedule-feature-releases.html index ff33851de8..9acaad89bc 100644 --- a/how-to/how-to-schedule-feature-releases.html +++ b/how-to/how-to-schedule-feature-releases.html @@ -20,7 +20,7 @@ - + @@ -29,7 +29,7 @@
    Skip to main content

    How to schedule feature releases

    Placeholders

    Placeholders in the code samples below are delimited by angle brackets (i.e. <placeholder-name>). You will need to replace them with the values that are correct in your situation for the code samples to run properly.

    There's a whole host of reasons why you may want to schedule the release of a feature, such as:

    • to release a feature at a specific date and time (for a product launch, for instance)
    • to make a feature available only up until a specific moment (for a contest cutoff, for instance)
    • to make a feature available during a limited period (for a 24 hour flash sale, for instance)

    There are two distinct ways to do this, depending on which version of Unleash you are running:

    In this guide we'll schedule a feature for release at some point in time. The exact same logic applies if you want to make a feature available until some point in the future. Finally, if you want to only make a feature available during a limited time period, you can easily combine the two options.

    Prerequisites​

    This guide assumes that you've got the following:

    • some basic experience with Unleash
    • a running instance of Unleash and connected clients (where applicable)
    • an existing feature toggle that you want to schedule the release for

    Schedule feature releases with strategy constraints​

    Strategy constraints are the easiest way to schedule feature releases (as long as your SDKs are up to date). You can use this approach with any strategy you want. The strategies will work just as they normally do, they just won't become active until the specified time. For example: with the standard strategy, the feature would become available to all your users at the specified time; with a gradual rollout, the rollout would start at the specified time.

    Step 1: Add an activation strategy with a date-based constraint​

    Scheduling a release via the UI​

    To schedule a feature release via the UI:

    1. Add the desired activation strategy to the feature
    2. Open the constraint creator by using the "Add constraint" button
    3. Add a date-based constraint by selecting the currentTime context field (step 1 in the below image), choosing the DATE_AFTER operator (step 2), and setting the point in time where you want the feature to be available from (step 3) A strategy constraint specifying that the activation strategy should be enabled at 12:00 AM, November 25th 2022. There are visual call-outs pointing to the relevant settings mentioned above.

    Scheduling a release via the API​

    To add an activation strategy via the Admin API, use the feature's strategies endpoint to add a new strategy (see the API documentation for adding strategies to feature toggles for more details).

    The payload's "name" property should contain the name of the strategy to apply (see activation strategies reference documentation for all built-in strategies' modeling names).

    The "constraint" object should have the same format as described in the code sample below. The activation date must be in an RFC 3339-compatible format, e.g. "1990-12-31T23:59:60Z".

    Add a feature activation strategy with a scheduled activation time.
    POST <unleash-url>/api/admin/projects/<project-id>/features/environments/<environment>/strategies
    Authorization: <API-token>
    content-type: application/json

    {
      "name": "default",
      "constraints": [
        {
          "value": "<activation-date>",
          "operator": "DATE_AFTER",
          "contextName": "currentTime"
        }
      ]
    }

    The "operator" property in the code sample can be replaced with any of the other date and time-based operators according to your needs.

    Schedule feature releases with custom activation strategies​

    To schedule feature releases without using strategy constraints, you can use custom activation strategies. This requires defining a custom strategy and then implementing that strategy in your SDKs. For detailed instructions on how to do either of these things, refer to their respective how-to guides:

    Step 1: Define and apply a custom activation strategy​

    Define a strategy that takes a parameter that tells it when to activate (visit the custom activation strategy reference documentation for full details on definitions):

    1. Give the strategy a name. We'll use enableAfter.
    2. Give the strategy a required string parameter where the user can enter the time at which the feature should activate. Be sure to describe the format that the user must adhere to.
    3. Save the strategy

    Apply the strategy to the feature toggle you want to schedule.

    A custom activation strategy definition for a strategy called `enableAfter`. It takes a required parameter called `start time`: a string in a date format.

    Step 2: Implement the custom activation strategy in your clients​

    In each of the client SDKs that will interact with your feature, implement the strategy (the implementation how-to guide has steps for all SDK types).

    - + \ No newline at end of file diff --git a/how-to/how-to-send-feature-updates-to-slack-deprecated.html b/how-to/how-to-send-feature-updates-to-slack-deprecated.html index 9c8f9f44c2..e06a4dcb7c 100644 --- a/how-to/how-to-send-feature-updates-to-slack-deprecated.html +++ b/how-to/how-to-send-feature-updates-to-slack-deprecated.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Feature Updates To Slack

    caution

    This guide is deprecated. If you're looking for ways to integrate with Slack, you should refer to the Slack integration guide instead.

    Event hook option is removed in Unleash v5

    Create a custom Slack WebHook URL:​

    1. Go to https://slack.com/apps/manage/custom-integrations
    2. Click Incoming WebHooks
    3. Click “Add Configuration”
    4. This is Slack's help page on how to do this: https://api.slack.com/messaging/webhooks
      • Choose a channel, follow the wizard, get the custom URL.

    Send data to Slack using an event hook function​

    Using the eventHook option, create a function that will send the data you'd like into Slack when mutation events happen.

    const unleash = require('unleash-server');
    const axios = require('axios');

    function onEventHook(event, eventData) {
      const { createdBy: user, data } = eventData;
      let text = '';

      const unleashUrl = 'http://your.unleash.host.com';
      const feature = `<${unleashUrl}/#/features/strategies/${data.name}|${data.name}>`;

      switch (event) {
        case 'feature-created':
        case 'feature-updated': {
          const verb =
            event === 'feature-created' ? 'created a new' : 'updated the';
          text = `${user} ${verb} feature ${feature}\ndescription: ${
            data.description
          }\nenabled: ${data.enabled}\nstrategies: \`${JSON.stringify(
            data.strategies,
          )}\``;
          break;
        }
        case 'feature-archived':
        case 'feature-revived': {
          const verb = event === 'feature-archived' ? 'archived' : 'revived';
          text = `${user} ${verb} the feature ${feature}`;
          break;
        }
        default: {
          console.error(`Unknown event ${event}`);
          return;
        }
      }

      axios
        .post(
          'https://hooks.slack.com/services/THIS_IS_WHERE_THE_CUSTOM_URL_GOES',
          {
            username: 'Unleash',
            icon_emoji: ':unleash:', // if you added a custom emoji, otherwise you can remove this field.
            text: text,
          },
        )
        .then((res) => {
          console.log(`Slack post statusCode: ${res.status}. Text: ${text}`);
        })
        .catch((error) => {
          console.error(error);
        });
    }

    const options = {
      eventHook: onEventHook,
    };

    unleash.start(options).then((server) => {
      console.log(`Unleash started on http://localhost:${server.app.get('port')}`);
    });
    - + \ No newline at end of file diff --git a/how-to/how-to-set-up-group-sso-sync.html b/how-to/how-to-set-up-group-sso-sync.html index f935689d94..c5400807ee 100644 --- a/how-to/how-to-set-up-group-sso-sync.html +++ b/how-to/how-to-set-up-group-sso-sync.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    How to Set Up User Group SSO Syncing

    availability

    User group syncing was released in Unleash 4.18 and is available for enterprise customers.

    This guide takes you through how to configure your user groups to automatically populate users through Single Sign On (SSO). Refer to setting up Keycloak for user group sync for an end to end example. Note that the steps below require you to be logged in as an admin user.

    Step 1: Navigate to SSO configuration​

    Navigate to the "Single sign-on" configuration page.

    The Unleash Admin UI with the steps highlighted to navigate to the Single sign-on configuration.

    Step 2: Enable Group Syncing​

    Turn on "Enable Group Syncing" and enter a value for "Group Field JSON Path". Refer to the User group SSO integration documentation for more information or to the how-to guide for integrating with Keycloak for a practical example.

    The value is the JSON path in the token response where your group properties are located, this is up to your SSO provider, a full example for Keycloak can be found here. Once you're happy, save your configuration.

    The Single sign-on configuration page with enable group syncing, group field JSON path and save inputs highlighted.

    Step 3: Navigate to a group​

    Navigate to the group you want to sync users for.

    The Unleash Admin UI with the steps highlighted to navigate to groups and a highlighted group card.

    Step 4: Edit the group configuration​

    Navigate to edit group.

    The group configuration screen with edit group highlighted.

    Step 5: Link SSO groups to your group​

    Link as many SSO groups as you like to your group, these names should match the group name or ID sent by your SSO provider exactly. Save your group configuration, the next time a user belonging to one of these groups logs in, they'll be automatically added to this group.

    The edit group screen with SSO Group input and save highlighted.

    - + \ No newline at end of file diff --git a/how-to/how-to-setup-sso-keycloak-group-sync.html b/how-to/how-to-setup-sso-keycloak-group-sync.html index d02beb755e..4bcf98232b 100644 --- a/how-to/how-to-setup-sso-keycloak-group-sync.html +++ b/how-to/how-to-setup-sso-keycloak-group-sync.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    How to set up Keycloak and Unleash to sync user groups

    availability

    User group syncing was released in Unleash 4.18 and is available to enterprise customers.

    In this guide, we will setup OIDC Single Sign-On (SSO) in Keycloak and configure Unleash to automatically sync user group membership from Keycloak.

    Prerequisites​

    The steps in this guide assume you have admin access to a running Unleash instance and to a running Keycloak instance.

    Keycloak Configuration​

    Step 1: Navigate to Create Client​

    Open the Keycloak admin dashboard, navigate to clients and select "Create Client".

    The Keycloak Admin UI with the steps highlighted to navigate to client configuration.

    Step 2: Create an Unleash Client​

    Select "OpenID Connect" as the client type and give your client a name, then save your configuration.

    The Keycloak Admin UI with the client configuration open.

    Step 3: Set a redirect URI​

    Set the redirect URI to:

    <base-url>/auth/oidc/callback

    For a hosted Unleash instance this becomes:

    https://<region>.app.unleash-hosted.com/<instance-name>/auth/oidc/callback

    Save your configuration.

    The Keycloak client configuration with redirect URIs highlighted.

    Step 4: Copy your client secret​

    Navigate to "Credentials" and copy your client secret. You'll need to add this to the Unleash configuration later, so put it somewhere you'll be able to find it.

    The Keycloak credentials configuration with copy client secret highlighted.

    Step 5: Copy your OpenID endpoint configuration​

    Navigate to your realm settings and copy the link to OpenID endpoint configuration. You'll need to add this to the Unleash configuration later.

    The Keycloak realm settings the OpenID endpoint configuration link highlighted.

    Step 6: Create a new Client Scope and Map Groups​

    Navigate to the "Client Scopes" page and select "Create Client Scope".

    The Keycloak Client Scopes page with the Create Client Scope button highlighted.

    Give your new scope a name. Set the type to "Optional". Make sure the protocol is set to "OpenID Connect" and the "Include in Token Response" option is enabled. Save your new scope.

    The Keycloak Add Client Scope page with the Name, Type, Protocol and Include in Token Response fields highlighted.

    Navigate to the Mappers tab and select "Configure new Mapper".

    The Keycloak Client Scope details page with the Mappers tab and Configure new Mapper element highlighted.

    Select the Group Membership mapper.

    The Keycloak mapper popup with the Group Membership mapper highlighted.

    Give your mapper a claim name, this must match the "Group Field JSON Path" in Unleash, and turn off the "Full group path" option.

    The Keycloak mapper options screen with the Token Claim Name and Full Group Path elements highlighted.

    Unleash Configuration​

    Step 1: Navigate to the Unleash SSO Configuration​

    Log in to Unleash as an admin user and navigate to the SSO configuration. Input your Client Secret (copied in step 3 of the Keycloak configuration), your Discover URL (copied in step 4 of the Keycloak configuration), and the Client ID (from step 2 of the Keycloak configuration).

    The Unleash SSO configuration screen with Client ID, Client Secret and Discover URL highlighted.

    Step 2: Enable Group Syncing​

    Turn on Group Syncing and set a value for "Group Field JSON Path". This must match the value in claim name in Keycloak exactly. Save your configuration.

    The Unleash SSO configuration screen with the Enable Group Syncing and Group Field JSON Path highlighted.

    Step 3: Enable Group Syncing for your Group​

    Navigate to Groups and select the group that you want to sync.

    The Groups page with a group element highlighted.

    Edit the group.

    The Group page with the Edit group element highlighted.

    Add as many SSO groups as you like. These need to match the Keycloak groups exactly.

    The edit group page with the add SSO group element highlighted.

    Save your configuration. Once a user belonging to one of these Keycloak groups logs in through SSO, they'll be automatically added to this Unleash group.

    - + \ No newline at end of file diff --git a/how-to/how-to-synchronize-unleash-instances.html b/how-to/how-to-synchronize-unleash-instances.html index c27ffec33e..a7a9def2ab 100644 --- a/how-to/how-to-synchronize-unleash-instances.html +++ b/how-to/how-to-synchronize-unleash-instances.html @@ -20,7 +20,7 @@ - + @@ -32,7 +32,7 @@ Example: SOURCE_API_TOKEN="user:98b555423fa020a3e67267fb8462fdeea13a1d62e7ea61d5fe4f3022"
  • SOURCE_ENV: The environment name for the source instance. Only feature toggles matching this environment will be exported.
  • SOURCE_TAG: The tag to filter feature toggles for export.

    • Target Unleash Instance​

    Process​

    The script performs the following steps:

    1. Export feature toggles from the source instance based on the specified tag and environment.
    2. Import the exported feature toggles into the target instance under the specified project and environment.

    If change requests are enabled in the target project, the import process will go through the change request process, allowing you to review the changes before applying them.

    The script prints each step of the export and import process, providing feedback on the success or failure of each operation.

    Troubleshooting​

    Here are some common issues you might encounter and how to resolve them:

    1. Make sure you use the correct URLs for the source and target instances.
    2. Ensure that the API tokens have the necessary permissions to perform export and import operations.
    3. Verify that the specified source and target environments exist.
    4. Check that the target project exists.
    5. If you have change requests enabled in the target project, ensure that there are no pending change requests for the same API token.
    Feedback wanted

    If you would like to give feedback on this feature, experience issues or have questions, please feel free to open an issue on GitHub.

    - + \ No newline at end of file diff --git a/how-to/how-to-use-custom-strategies.html b/how-to/how-to-use-custom-strategies.html index 31051bca8e..c472648304 100644 --- a/how-to/how-to-use-custom-strategies.html +++ b/how-to/how-to-use-custom-strategies.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    How to use custom activation strategies

    tip

    Use custom activation strategies only for cases where strategy constraints don't give you enough control.

    The downside of using a custom activation strategy instead of constraints is that you need to distribute the code of your strategy with Unleash client SDK while on the other hand, strategy constraints work without any extra code or maintenance.

    This guide takes you through how to use custom activation strategies with Unleash. We'll go through how you define a custom strategy in the admin UI, how you add it to a toggle, and how you'd implement it in a client SDK.

    In this example we want to define an activation strategy offers a scheduled release of a feature toggle. This means that we want the feature toggle to be activated after a given date and time.

    Step 1: Define your custom strategy​

    1. Navigate to the strategies view. Interact with the "Configure" button in the page header and then go to the "Strategies" link in the dropdown menu that appears.

      A visual guide for how to navigate to the strategies page in the Unleash admin UI. It shows the steps described in the preceding paragraph.

    2. Define your strategy. Use the "Add new strategy" button to open the strategy creation form. Fill in the form to define your strategy. Refer to the custom strategy reference documentation for a full list of options.

      A strategy creation form. It has fields labeled &quot;strategy name&quot; — &quot;TimeStamp&quot; — and &quot;description&quot; — &quot;activate toggle after a given timestamp&quot;. It also has fields for a parameter named &quot;enableAfter&quot;. The parameter is of type &quot;string&quot; and the parameter description is &quot;Expected format: YYYY-MM-DD HH:MM&quot;. The parameter is required.

    Step 2: Apply your custom strategy to a feature toggle​

    Navigate to your feature toggle and apply the strategy you just created.

    The strategy configuration screen for the custom &quot;TimeStamp&quot; strategy from the previous step. The &quot;enableAfter&quot; field says &quot;2021-12-25 00:00&quot;.

    Step 3: Implement the strategy in your client SDK​

    The steps to implement a custom strategy for your client depend on the kind of client SDK you're using:

    Option A: Implement the strategy for a server-side client SDK​

    1. Implement the custom strategy in your client SDK. The exact way to do this will vary depending on the specific SDK you're using, so refer to the SDK's documentation. The example below shows an example of how you'd implement a custom strategy called "TimeStamp" for the Node.js client SDK.

      const { Strategy } = require('unleash-client');

      class TimeStampStrategy extends Strategy {
        constructor() {
          super('TimeStamp');
        }

        isEnabled(parameters, context) {
          return Date.parse(parameters.enableAfter) < Date.now();
        }
      }

    2. Register the custom strategy with the Unleash Client. When instantiating the Unleash Client, provide it with a list of the custom strategies you'd like to use — again: refer to your client SDK's docs for the specifics.

      Here's a full, working example for Node.js. Notice the strategies property being passed to the initialize function.

      const { Strategy, initialize, isEnabled } = require('unleash-client');

      class TimeStampStrategy extends Strategy {
        constructor() {
          super('TimeStamp');
        }

        isEnabled(parameters, context) {
          return Date.parse(parameters.enableAfter) < Date.now();
        }
      }

      const instance = initialize({
        url: 'https://unleash.example.com/api/',
        appName: 'unleash-demo',
        instanceId: '1',
        strategies: [new TimeStampStrategy()],
      });

      instance.on('ready', () => {
        setInterval(() => {
          console.log(isEnabled('demo.TimeStampRollout'));
        }, 1000);
      });

    Option B: Implement the strategy for a front-end client SDK​

    Front-end client SDKs don't evaluate strategies directly, so you need to implement the custom strategy in the Unleash Proxy. Depending on how you run the Unleash Proxy, follow one of the below series of steps:

    With a containerized proxy​

    Strategies are stored in separate JavaScript files and loaded into the container at startup. Refer to the Unleash Proxy documentation for a full overview of all the options.

    1. Create a strategies directory. Create a directory that Docker has access to where you can store your strategies. The next steps assume you called it strategies

    2. Initialize a Node.js project and install the Unleash Client:

      npm init -y && \
      npm install unleash-client

    3. Create a strategy file and implement your strategies. Remember to export your list of strategies. The next steps will assume you called the file timestamp.js. An example implementation looks like this:

      const { Strategy } = require('unleash-client');

      class TimeStampStrategy extends Strategy {
        constructor() {
          super('TimeStamp');
        }

        isEnabled(parameters, context) {
          return Date.parse(parameters.enableAfter) < Date.now();
        }
      }

      module.exports = [new TimeStampStrategy()]; // <- export strategies

    4. Mount the strategies directory and point the Unleash Proxy docker container at your strategies file. The highlighted lines below show the extra options you need to add. The following command assumes that your strategies directory is a direct subdirectory of your current working directory. Modify the rest of the command to suit your needs.

      docker run --name unleash-proxy --pull=always \
          -e UNLEASH_PROXY_CLIENT_KEYS=some-secret \
          -e UNLEASH_URL='http://unleash:4242/api/' \
          -e UNLEASH_API_TOKEN=${API_TOKEN} \
          -e UNLEASH_CUSTOM_STRATEGIES_FILE=/strategies/timestamp.js \
          --mount type=bind,source="$(pwd)"/strategies,target=/strategies \
          -p 3000:3000 --network unleash unleashorg/unleash-proxy

    When running the proxy with Node.js​

    The Unleash Proxy accepts a customStrategies property as part of its initialization options. Use this to pass it initialized strategies.

    1. Install the unleash-client package. You'll need this to implement the custom strategy:

      npm install unleash-client

    2. Implement your strategy. You can import it from a different file or put it in the same file as the Proxy initialization. For instance, a TimeStampStrategy could look like this:

      const { Strategy } = require('unleash-client');

      class TimeStampStrategy extends Strategy {
        constructor() {
          super('TimeStamp');
        }

        isEnabled(parameters, context) {
          return Date.parse(parameters.enableAfter) < Date.now();
        }
      }

    3. Pass the strategy to the Proxy Client using the customStrategies option. A full code example:

      const { createApp } = require('@unleash/proxy');
      const { Strategy } = require('unleash-client');

      class TimeStampStrategy extends Strategy {
        constructor() {
          super('TimeStamp');
        }

        isEnabled(parameters, context) {
          return Date.parse(parameters.enableAfter) < Date.now();
        }
      }

      const port = 3000;

      const app = createApp({
        unleashUrl: 'https://app.unleash-hosted.com/demo/api/',
        unleashApiToken:
          '*:default.56907a2fa53c1d16101d509a10b78e36190b0f918d9f122d',
        clientKeys: ['proxy-secret', 'another-proxy-secret', 's1'],
        refreshInterval: 1000,
        customStrategies: [new TimeStampStrategy()],
      });

      app.listen(port, () =>
        // eslint-disable-next-line no-console
        console.log(`Unleash Proxy listening on http://localhost:${port}/proxy`),
      );
    - + \ No newline at end of file diff --git a/how-to/how-to-use-the-admin-api.html b/how-to/how-to-use-the-admin-api.html index 34bdf47088..81745a68d0 100644 --- a/how-to/how-to-use-the-admin-api.html +++ b/how-to/how-to-use-the-admin-api.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    How to use the Admin API

    It is possible to integrate directly with the Admin API. In this guide we will explain all the steps to set it up.

    Step 1: Create API token​

    You'll need either an admin token or a personal access token for this to work. To create one, follow the steps in the how to create API tokens guide or the how to create personal access tokens guide, respectively.

    Please note that it may take up to 60 seconds for the new key to propagate to all Unleash instances due to eager caching.

    note

    If you need an API token to use in a client SDK you should create a "client token" as these have fewer access rights.

    Step 2: Use Admin API​

    Now that you have an access token with admin privileges we can use that to perform changes in our Unleash instance.

    In the example below we will use the Unleash Admin API to enable the “Demo” feature toggle using curl.

    curl -X POST -H "Content-Type: application/json" \
         -H "Authorization: some-token" \
         https://app.unleash-hosted.com/demo/api/admin/features/Demo/toggle/on

    Great success! We have now enabled the feature toggle. We can also verify that it was actually changed by the API user by navigating to the Event log (history) for this feature toggle.

    A feature toggle&#39;s event log showing that it was last updated by &quot;admin-api&quot;.

    API overview​

    You can find the full documentation on everything the Unleash API supports in the Unleash API documentation.

    - + \ No newline at end of file diff --git a/how-to/misc.html b/how-to/misc.html index 8dc68c78f5..6750c8eed0 100644 --- a/how-to/misc.html +++ b/how-to/misc.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    How-to: general Unleash tasks

    Guides for how to perform general Unleash tasks.

    - + \ No newline at end of file diff --git a/how-to/proxy.html b/how-to/proxy.html index 186bdd6116..c4906596dd 100644 --- a/how-to/proxy.html +++ b/how-to/proxy.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    How-to: The Unleash Proxy

    Learn how to work with the Unleash Proxy

    - + \ No newline at end of file diff --git a/how-to/sso.html b/how-to/sso.html index 8c6685a30c..67292eacfd 100644 --- a/how-to/sso.html +++ b/how-to/sso.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    How-to: Single Sign-On

    Single Sign-On how-to guides.

    📄️ [Deprecated] How to add SSO with Google

    Single Sign-on via the Google Authenticator provider has been removed in Unleash v5 (deprecated in v4). We recommend using OpenID Connect instead. If you're running a self hosted version of Unleash and you need to temporarily re-enable Google SSO, you can do so by setting the GOOGLEAUTHENABLED environment variable to true. If you're running a hosted version of Unleash, you'll need to reach out to us and ask us to re-enable the flag. Note that this code will be removed in a future release and this is not safe to depend on.

    - + \ No newline at end of file diff --git a/how-to/users-and-permissions.html b/how-to/users-and-permissions.html index 469bd62508..1fde7b5124 100644 --- a/how-to/users-and-permissions.html +++ b/how-to/users-and-permissions.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    How-to: users and permissions

    Users and permission how-to guides.

    - + \ No newline at end of file diff --git a/index.html b/index.html index 9ae4a14014..0e80ece5ee 100644 --- a/index.html +++ b/index.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Welcome

    Welcome to Unleash's documentation, your one-stop shop for everything Unleash. Whether you're just getting started or have been using Unleash for years, you should be able to find answers to all your questions here.

    • Quick Start: Get up and running with Unleash in just a few steps.
    • Unleash Academy: Video Tutorials to onboard you to Unleash’s full suite of capabilities.
    • Feature Flag Best Practices: Maximize your effectiveness with feature flags, regardless of what technology you choose to use.
    • Feature Flag Tutorials: Our small but growing collection of tutorials on using feature flags with different technologies.
    • Understanding Unleash: Get a high-level view of Unleash's architecture, core functionalities, and concepts to leverage our platform to its full potential.
    • Using Unleash: Our comprehensive guides on APIs, SDKs, integrations, how-to guides, and troubleshooting will help you get things done with Unleash.
    • Contributing to Unleash: Join our community and contribute to the ongoing growth of Unleash.

    Dive in and start exploring—great things await. If you need a hand, our team is just a click away.

    Getting help​

    Have questions that you can't find the answer to in these docs?

    💬 If you've got questions or want to chat with the team and other Unleash users join our Slack community or a GitHub Discussion. Our Slack tends to be more active, but you're welcome to use whatever works best for you.

    🤖 Ask our AI ‘intern’ (still in training, but not bad). The "Ask AI" button lives in the bottom right corner on every page. ↘

    🐦 You can also follow us on Twitter, LinkedIn and visit our website for ongoing updates and content.

    - + \ No newline at end of file diff --git a/quickstart.html b/quickstart.html index bf1a12f2bb..d8020abf98 100644 --- a/quickstart.html +++ b/quickstart.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Quick Start

    There are lots of options to get started with Unleash. If you're comfortable with Docker, this is the fastest way to get up and running. If that's not you, here are some additional ways to try Unleash

    1. Set up Unleash with Docker​

    The easiest way to run unleash locally is using git and docker.

    git clone git@github.com:Unleash/unleash.git
    cd unleash
    docker compose up -d

    2. Log in to the Admin UI​

    Then point your browser to localhost:4242 and log in using:

    username: admin
    password: unleash4all

    3. Create your first flag​

    1. Navigate to the Feature toggles list
    2. Click 'New feature toggle'
    3. Give it a unique name, and click 'Create feature toggle'

    For a detailed guide on how to create a flag through the UI, you can follow this guide.

    4a. Connect a client-side SDK​

    To try Unleash with a client-side technology, create a front-end token and use <your-unleash-instance>/api/frontend as the API URL.

    Now you can open your application code and connect through one of the client-side SDKs.

    The following example shows you how you could use the JavaScript SDK to connect to the Unleash demo frontend API:

    import { UnleashClient } from 'unleash-proxy-client';

    const unleash = new UnleashClient({
      url: 'https://<your-unleash-instance>/api/frontend',
      clientKey: '<your-token>',
      appName: '<your-app-name>',
    });

    unleash.on('synchronized', () => {
      // Unleash is ready to serve updated feature flags.

      // Check a feature flag
      if (unleash.isEnabled('some-toggle')) {
        // do cool new things when the flag is enabled 
      }
    });

    4b. Connect a backend SDK​

    To try Unleash with a server-side technology, create a client token and use <your-unleash-instance>/api as the API URL.

    Now you can open up your application code and create a connection to Unleash using one of our SDKs. Here's an example using the NodeJS SDK to connect to the Unleash demo instance:

    const { initialize } = require('unleash-client');
    const unleash = initialize({
      url: 'https://<your-unleash-instance>/api/',
      appName: '<your-app-name>',
      customHeaders: {
        Authorization: '<your-token>',
      },
    });

    unleash.on('synchronized', () => {
      // Unleash is ready to serve updated feature flags.

      if(unleash.isEnabled('some-toggle')){
        // do cool new things when the flag is enabled 
      } 
    });

    Additional Ways to Try Unleash​

    Unleash Demo Instance​

    For testing purposes we have set up a demo instance that you can use in order to test out different use-cases before setting up your own instance. You can find the demo instance here: https://app.unleash-hosted.com/demo/

    NOTE: This is a demo instance set up with the Enterprise version. More information on our different versions.

    If you don't have your own Unleash instance set up, you can use the Unleash demo instance. In that case, the details are:

    Client Side

    • API URL: https://app.unleash-hosted.com/demo/api/frontend
    • Frontend key: demo-app:default.bf8d2a449a025d1715a28f218dd66a40ef4dcc97b661398f7e05ba67

    Server Side

    • API URL: https://app.unleash-hosted.com/demo/api
    • Client key: 56907a2fa53c1d16101d509a10b78e36190b0f918d9f122d

    Curl command to test credentials and retrieve feature toggles:

    curl https://app.unleash-hosted.com/demo/api/client/features \
    -H "Authorization: 56907a2fa53c1d16101d509a10b78e36190b0f918d9f122d";

    Unleash Pro & Enterprise Instances​

    You can run Unleash in the cloud by using our hosted offerings. Please see the plans page to learn more.

    Other Local Setup Options​

    There are several more options to get started locally.

    - + \ No newline at end of file diff --git a/reference.html b/reference.html index e348d6b19f..ccefead6ac 100644 --- a/reference.html +++ b/reference.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Unleash Concepts

    Documents describing the inner parts of Unleash.

    - + \ No newline at end of file diff --git a/reference/activation-strategies.html b/reference/activation-strategies.html index 7d8c8aff3a..01dda4a60f 100644 --- a/reference/activation-strategies.html +++ b/reference/activation-strategies.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Activation Strategies

    It is powerful to be able to turn a feature on and off instantaneously, without redeploying the application. Activation strategies let you enable a feature only for a specified audience. Different strategies use different parameters. Predefined strategies are bundled with Unleash. The recommended strategy is the gradual rollout strategy with 100% rollout, which basically means that the feature should be enabled to everyone.

    Unleash comes with a number of built-in strategies (described below) that can be enhanced with constraints for fine-grained control. For more advanced use cases, where constraints do not fulfill your needs, you can add your own custom activation strategies. However, while activation strategies are defined on the server, the server does not implement the strategies. Instead, activation strategy implementation is done client-side. This means that it is the client that decides whether a feature should be enabled or not.

    All server-side client SDKs and the Unleash Proxy implement the default strategies (and allow you to add your own custom strategy implementations). The front-end client SDKs do not do the evaluation themselves, instead relying on the Unleash Proxy to take care of the implementation and evaluation.

    Some activation strategies require the client to provide the current Unleash context to the toggle evaluation function for the evaluation to be done correctly.

    The following activation strategies are bundled with Unleash and always available:

    Standard​

    A basic strategy that means "active for everyone".

    This strategy has the following modelling name in the code:

    • default

    UserIDs​

    Active for users with a userId defined in the userIds list. A typical use case is to enable a feature for a few specific devs or key persons before enabling the feature for everyone else. This strategy allows you to specify a list of user IDs that you want to expose the new feature for. (A user id may, of course, be an email if that is more appropriate in your system.)

    Parameters

    • userIds - List of user IDs you want the feature toggle to be enabled for

    This strategy has the following modelling name in the code:

    • userWithId

    Gradual Rollout​

    A flexible rollout strategy which combines all gradual rollout strategies in to a single strategy. This strategy allows you to customize what parameter should be sticky, and defaults to userId or sessionId.

    Parameters

    • stickiness is used to define how we guarantee consistency for a gradual rollout. The same userId and the same rollout percentage should give predictable results. Configuration that should be supported:
      • default - Unleash chooses the first value present on the context in defined order userId, sessionId, random.
      • userId - guaranteed to be sticky on userId. If userId not present the behavior would be false
      • sessionId - guaranteed to be sticky on sessionId. If sessionId not present the behavior would be false.
      • random - no stickiness guaranteed. For every isEnabled call it will yield a random true/false based on the selected rollout percentage.
    • groupId is used to ensure that different toggles will hash differently for the same user. The groupId defaults to feature toggle name, but the user can override it to correlate rollout of multiple feature toggles.
    • rollout The percentage (0-100) you want to enable the feature toggle for.

    This strategy has the following modelling name in the code:

    • flexibleRollout

    Custom stickiness​

    SDK compatibility

    Custom stickiness is supported by all of our SDKs except for the Rust SDK. You can always refer to the SDK compatibility table for the full overview.

    By enabling the stickiness option on a custom context field you can use the custom context field to group users with the gradual rollout strategy. This will guarantee a consistent behavior for specific values of this context field.

    IPs​

    The remote address strategy activates a feature toggle for remote addresses defined in the IP list. We occasionally use this strategy to enable a feature only for IPs in our office network.

    Parameters

    • IPs - List of IPs to enable the feature for.

    This strategy has the following modelling name in the code:

    • remoteAddress

    Hostnames​

    The application hostname strategy activates a feature toggle for client instances with a hostName in the hostNames list.

    Parameters

    • hostNames - List of hostnames to enable the feature toggle for.

    This strategy has the following modelling name in the code:

    • applicationHostname

    Multiple activation strategies​

    You can apply as many activation strategies to a toggle as you want. When a toggle has multiple strategies, Unleash will check each strategy in isolation. If any one of the strategies would enable the toggle for the current user, then the toggle is enabled.

    As an example, consider a case where you want to roll a feature out to 75% of your users. However, you also want to make sure that you and your product lead get access to the feature. To achieve this, you would apply a gradual rollout strategy and set it to 75%. Additionally, you would add a user IDs strategy and add engineer@mycompany.com and productlead@mycompany.com.

    A feature toggle with two active strategies: a user ID strategy and a gradual rollout strategy. The strategies are configured as described in the preceding paragraph.

    Deprecated strategies​

    gradualRolloutUserId (DEPRECATED from v4) - Use Gradual rollout instead​

    The gradualRolloutUserId strategy gradually activates a feature toggle for logged-in users. Stickiness is based on the user ID. The strategy guarantees that the same user gets the same experience every time across devices. It also assures that a user which is among the first 10% will also be among the first 20% of the users. That way, we ensure the users get the same experience, even if we gradually increase the number of users exposed to a particular feature. To achieve this, we hash the user ID and normalize the hash value to a number between 1 and 100 with a simple modulo operator.

    hash_and_normalise

    Starting from v3.x all clients should use the 32-bit MurmurHash3 algorithm to normalize values. (issue 247)

    Parameters

    • percentage - The percentage (0-100) you want to enable the feature toggle for.
    • groupId - Used to define an activation group, which allows you to correlate rollout across feature toggles.

    gradualRolloutSessionId (DEPRECATED from v4) - Use Gradual rollout instead​

    Similar to gradualRolloutUserId strategy, this strategy gradually activates a feature toggle, with the exception being that the stickiness is based on the session IDs. This makes it possible to target all users (not just logged-in users), guaranteeing that a user will get the same experience within a session.

    Parameters

    • percentage - The percentage (0-100) you want to enable the feature toggle for.
    • groupId - Used to define an activation group, which allows you to correlate rollout across feature toggles.

    gradualRolloutRandom (DEPRECATED from v4) - Use Gradual rollout instead​

    The gradualRolloutRandom strategy randomly activates a feature toggle and has no stickiness. We have found this rollout strategy very useful in some scenarios, especially when we enable a feature which is not visible to the user. It is also the strategy we use to sample metrics and error reports.

    Parameters

    • percentage - The percentage (0-100) you want to enable the feature toggle for.
    - + \ No newline at end of file diff --git a/reference/api-tokens-and-client-keys.html b/reference/api-tokens-and-client-keys.html index fff24a5c5c..c7ed60993b 100644 --- a/reference/api-tokens-and-client-keys.html +++ b/reference/api-tokens-and-client-keys.html @@ -20,7 +20,7 @@ - + @@ -30,7 +30,7 @@
    Skip to main content

    API Tokens and Client Keys

    For Unleash to be of any use, it requires at least a server and a consuming client. More advanced use cases may call for multiple clients, automated feature toggle updates, the Unleash proxy and Unleash proxy clients, and more. To facilitate communication between all these moving parts, Unleash uses a system of API tokens and client keys, all with a specific purpose in mind.

    This document details the three kinds of tokens and keys that you will need to fully connect any Unleash system:

    API tokens​

    tip

    This section describes what API tokens are. For information on how to create them, refer to the how-to guide for creating API tokens.

    Use API tokens to connect to the Unleash server API. API tokens come in four distinct types:

    All types use the same format but have different intended uses. Admin and client tokens are secrets and should not be exposed to end users. Front-end tokens, on the other hand, are not secret.

    The parts of an API token​

    Admin, client and front-end tokens contain the following pieces of information:

    NameDescription
    Token name (sometimes called "username")The token's name. Names are not required to be unique.
    TypeWhat kind of token it is: admin, client, or front-end.
    ProjectsWhat projects a token has access to.
    EnvironmentWhat environment the token has access to.

    Personal access tokens follow their own special format, and only contain an optional description for the token and an expiry date.

    API token visibility​

    project-level visibility

    Project-level visibility and access to API tokens was introduced in Unleash 4.22.

    By default, only admin users can create API tokens, and only admins can see their values.

    However, any [client](#client-tokens client tokens) and front-end tokens that are applicable to a project, will also be visible to any members of that project that have the READ_PROJECT_API_TOKEN permission (all project members by default).

    Similarly, any project members with the CREATE_PROJECT_API_TOKEN permission can also create client and front-end tokens for that specific project (how to create project API tokens).

    Admin tokens​

    Admin tokens grant full read and write access to all resources in the Unleash server API. Admin tokens have access to all projects, all environments, and all root resources (find out more about resources in the RBAC document).

    Use admin tokens to:

    • Automate Unleash behavior such as creating feature toggles, projects, etc.

    • Write custom Unleash UIs to replace the default Unleash admin UI. Do not use admin tokens for:

    • Client SDKs: You will not be able to read toggle data from multiple environments. Use client tokens instead.

    Support for scoped admin tokens with more fine-grained permissions is currently in the planning stage.

    Deprecation Notice We do not recommend using admin tokens anymore, they are not connected to any user, and as such is a lot harder to track.

    Personal access tokens​

    Personal access tokens are a special form of admin tokens and grant access to the same resources that the user that created them has access to. These permissions are dynamic, so if a user's permissions change through addition of a custom role, the token will likewise have altered permissions.

    When using a personal access token to modify resources, the event log will list the token creator's name for that operation.

    Personal access tokens with a lifetime will stop working after the expiration date.

    Use personal access tokens to:

    • Provide more fine-grained permissions for automation than an admin token provides
    • Give temporary access to an automation tool
    On token expiration

    It is possible to set a token's expiration date to never. However, a token that doesn't expire brings with it a few security concerns. We recommend that you use tokens with expiration dates whenever possible.

    Do not use personal access tokens for:

    • Client SDKs: You will not be able to read toggle data from multiple environments. Use client tokens instead.
    • Write custom Unleash UIs: Personal access tokens may expire and their permissions may change. It's better to use admin tokens tokens instead.

    Client tokens​

    Client tokens are intended for use in server-side client SDKs (including the Unleash Proxy) and grant the user permissions to:

    • Read feature toggle information
    • Register applications with the Unleash server
    • Send usage metrics

    When creating a client token, you can choose which projects it should be able to read data from. You can give it access to a specific list of projects or to all projects (including projects that don't exist yet). Prior to Unleash 4.10, a token could be valid only for a single project or all projects.

    Each client token is only valid for a single environment.

    Use client tokens:

    Do not use client tokens in:

    Front-end tokens​

    Front-end tokens are used with front-end SDKs when used with the Unleash front-end API. They grant the user permission to:

    • Read the enabled toggled for a given context
    • Register applications with the Unleash server
    • Send usage metrics

    As with client tokens, front-end tokens can read data from one, multiple, or all existing projects.

    Each front-end token is only valid for a single environment.

    Use front-end tokens in:

    Do not use front-end tokens in:

    Format​

    API tokens come in one of two formats. When we introduced environments in Unleash 4.3, we updated the format of the tokens to provide more human-readable information to the user. Both formats are still valid (you don't need to update a working token of the old format) and are described below.

    Version 1​

    The first version of API tokens was a 64 character long hexadecimal string. Example:

    be44368985f7fb3237c584ef86f3d6bdada42ddbd63a019d26955178

    Version 2​

    API tokens consist of three parts:

    1. Project(s)
    2. Environment
    3. Hash

    The parts are separated by two different separators: A colon (:) between the project(s) and the environment, and a full stop (.) between the environment and the hash.

    The project(s) part is one of:

    • The id of a specific project, for example: default. This indicates that the token is only valid for this project.
    • A pair of opening and closing square brackets: []. This indicates that the token is valid for a discrete list of projects. The list of projects is not shown in the token.
    • An asterisk: *. This indicates that the token is valid for all projects (current and future).

    The environment is the name of an environment on your Unleash server, such as development.

    The hash is 64 character long hexadecimal string.

    Personal access tokens do not contain project or environment information, since they mimic the user that created them. Instead, the token starts with the string user.

    Some example client tokens are:

    • A token with access to toggles in the "development" environment of a single project, "project-a":
      project-a:development.be44368985f7fb3237c584ef86f3d6bdada42ddbd63a019d26955178
    • A token with access to toggles in the "production" environment multiple projects:
      []:production.be44368985f7fb3237c584ef86f3d6bdada42ddbd63a019d26955178
    • A token with access to toggles in the "development" environment of all projects:
      *:development.be44368985f7fb3237c584ef86f3d6bdada42ddbd63a019d26955178
    • A personal access token:
      user:be7536c3a160ff15e3a92da45de531dd54bc1ae15d8455c0476f086b

    Proxy client keys​

    Use proxy client keys to connect Proxy client SDKs (front-end SDKs) to the Unleash Proxy. As opposed to the API tokens, Proxy client keys are not considered secret and are safe to use on any clients (refer to the the proxy documentation for more about privacy). They do not let you connect to the Unleash server API.

    Proxy client keys are arbitrary strings that you must provide the Unleash proxy with on startup. They can be whatever you want and you create them yourself.

    Creating proxy client keys

    To designate a string as a proxy client key, add it to the clientKeys list when starting the proxy, as mentioned in the configuration section of the Unleash proxy documentation. Connecting clients should then specify the same string as their client key.

    Unleash does not generate proxy client keys for you. Because of this, they have no specific format.

    Use Proxy client keys to:

    Do not use Proxy client keys to:

    • Connect to the Unleash API. It will not work. Use an appropriate API token instead.
    - + \ No newline at end of file diff --git a/reference/api/legacy/unleash.html b/reference/api/legacy/unleash.html index 85f29fca89..32f9ce8f4f 100644 --- a/reference/api/legacy/unleash.html +++ b/reference/api/legacy/unleash.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Legacy API Documentation

    caution

    The docs in this category are legacy documentation. You should prefer to use the Unleash OpenAPI docs instead whenever possible.

    Client API​

    This describes the API provided to unleash-clients.

    Since v4.0.0 all operations require an API token with Client level access.

    With versions earlier than v4.0.0 and insecure authentication no authentication is required.

    Admin API (internal)​

    The internal API used by the Admin UI (unleash-frontend). Since v4.0.0 all operations require an API token with Admin level access:

    With versions earlier than v4.0.0 and insecure authentication Basic Auth (with curl -u myemail@test.com:) is enough.

    System API's​

    Content-Type​

    All endpoints require application/json as content type, so if you're using curl remember to add

    -H "Content-Type: application/json"
    - + \ No newline at end of file diff --git a/reference/api/legacy/unleash/admin/addons.html b/reference/api/legacy/unleash/admin/addons.html index 3d3bb56fe1..cfad4b098e 100644 --- a/reference/api/legacy/unleash/admin/addons.html +++ b/reference/api/legacy/unleash/admin/addons.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    /api/admin/addons

    In order to access the admin API endpoints you need to identify yourself. Unless you're using the none authentication method, you'll need to create an ADMIN token and add an Authorization header using the token.

    List integrations and providers​

    GET https://unleash.host.com/api/admin/addons

    Returns a list of configured integrations and available integration providers.

    Example response:

    {
      "addons": [
        {
          "id": 30,
          "provider": "webhook",
          "enabled": true,
          "description": "post updates to slack",
          "parameters": {
            "url": "http://localhost:4242/webhook"
          },
          "events": ["feature-created", "feature-updated"]
        },
        {
          "id": 33,
          "provider": "slack",
          "enabled": true,
          "description": "default",
          "parameters": {
            "defaultChannel": "integration-demo-instance",
            "url": "https://hooks.slack.com/someurl"
          },
          "events": ["feature-created", "feature-updated"]
        }
      ],
      "providers": [
        {
          "name": "webhook",
          "displayName": "Webhook",
          "description": "Webhooks are a simple way to post messages from Unleash to third party services. Unleash make use of normal HTTP POST with a payload you may define yourself.",
          "parameters": [
            {
              "name": "url",
              "displayName": "Webhook URL",
              "type": "url",
              "required": true
            },
            {
              "name": "bodyTemplate",
              "displayName": "Body template",
              "description": "You may format the body using a mustache template. If you don't specify anything, the format will be similar to the /api/admin/events format",
              "type": "textfield",
              "required": false
            }
          ],
          "events": [
            "feature-created",
            "feature-updated",
            "feature-archived",
            "feature-revived"
          ]
        },
        {
          "name": "slack",
          "displayName": "Slack",
          "description": "Integrates Unleash with Slack.",
          "parameters": [
            {
              "name": "url",
              "displayName": "Slack webhook URL",
              "type": "url",
              "required": true
            },
            {
              "name": "defaultChannel",
              "displayName": "Default channel",
              "description": "Default channel to post updates to if not specified in the slack-tag",
              "type": "text",
              "required": true
            }
          ],
          "events": [
            "feature-created",
            "feature-updated",
            "feature-archived",
            "feature-revived"
          ],
          "tags": [
            {
              "name": "slack",
              "description": "Slack tag used by the slack integration to specify the slack channel.",
              "icon": "S"
            }
          ]
        }
      ]
    }

    Create a new integration configuration​

    POST https://unleash.host.com/api/addons

    Creates an integration configuration for an integration provider.

    Body

    {
      "provider": "webhook",
      "description": "Optional description",
      "enabled": true,
      "parameters": {
        "url": "http://localhost:4242/webhook"
      },
      "events": ["feature-created", "feature-updated"]
    }

    Notes​

    • provider must be a valid integration provider

    Update new integration configuration​

    POST https://unleash.host.com/api/addons/:id

    Updates an integration configuration.

    Body

    {
      "provider": "webhook",
      "description": "Optional updated description",
      "enabled": true,
      "parameters": {
        "url": "http://localhost:4242/webhook"
      },
      "events": ["feature-created", "feature-updated"]
    }

    Notes​

    • provider can not be changed.

    Delete an integration configuration​

    DELETE https://unleash.host.com/api/admin/addons/:id

    Deletes the integration with id=id.

    - + \ No newline at end of file diff --git a/reference/api/legacy/unleash/admin/archive.html b/reference/api/legacy/unleash/admin/archive.html index 5be4bf94cf..7947711130 100644 --- a/reference/api/legacy/unleash/admin/archive.html +++ b/reference/api/legacy/unleash/admin/archive.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    /api/admin/archive

    In order to access the admin API endpoints you need to identify yourself. Unless you're using the none authentication method, you'll need to create an ADMIN token and add an Authorization header using the token.

    Fetch archived toggles​

    GET http://unleash.host.com/api/admin/archive/features

    Used to fetch list of archived feature toggles

    Example response:

    {
      "version": 1,
      "features": [
        {
          "name": "Feature.A",
          "description": "lorem ipsum",
          "type": "release",
          "stale": false,
          "variants": [],
          "tags": [],
          "strategy": "default",
          "parameters": {}
        }
      ]
    }

    Revive feature toggle​

    POST http://unleash.host.com/api/admin/archive/revive/:featureName

    Response: 200 OK - When feature toggle was successfully revived.

    Delete an archived feature toggle​

    DELETE http://unleash.host.com/api/admin/archive/:featureName

    Will fully remove the feature toggle and associated configuration. Impossible to restore after this action.

    - + \ No newline at end of file diff --git a/reference/api/legacy/unleash/admin/context.html b/reference/api/legacy/unleash/admin/context.html index a20a053ac9..6dc9e09045 100644 --- a/reference/api/legacy/unleash/admin/context.html +++ b/reference/api/legacy/unleash/admin/context.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    /api/admin/context

    The context feature is only available as part of Unleash Enterprise. In order to access the API programmatically you need to make sure you obtain a API token with admin permissions.

    List context fields defined in Unleash​

    GET https://unleash.host.com/api/admin/context

    Returns a list of context fields defined in Unleash.

    Example response:

    [
      {
        "name": "appName",
        "description": "Allows you to constrain on application name",
        "stickiness": false,
        "sortOrder": 2,
        "createdAt": "2020-03-05T19:33:19.784Z"
      },
      {
        "name": "environment",
        "description": "Allows you to constrain on application environment",
        "stickiness": false,
        "sortOrder": 0,
        "legalValues": ["qa", "dev", "prod"],
        "createdAt": "2020-03-05T19:33:19.784Z"
      },
      {
        "name": "tenantId",
        "description": "Control rollout to your tenants",
        "stickiness": true,
        "sortOrder": 10,
        "legalValues": ["company-a, company-b"],
        "createdAt": "2020-03-05T19:33:19.784Z"
      },
      {
        "name": "userId",
        "description": "Allows you to constrain on userId",
        "stickiness": false,
        "sortOrder": 1,
        "createdAt": "2020-03-05T19:33:19.784Z"
      }
    ]

    Create a new context field​

    POST https://unleash.host.com/api/admin/context

    Creates a new context field.

    Body

    {
      "name": "region",
      "description": "Control rollout based on region",
      "legalValues": ["asia", "eu", "europe"],
      "stickiness": true
    }

    Update a context field​

    PUT https://unleash.host.com/api/context/:name

    Updates a new context field

    Body

    {
      "name": "region",
      "description": "Control rollout based on region",
      "legalValues": ["asia", "eu"],
      "stickiness": true
    }

    Delete a context field​

    DELETE https://unleash.host.com/api/admin/context/:name

    Deletes the context field with name=name.

    - + \ No newline at end of file diff --git a/reference/api/legacy/unleash/admin/events.html b/reference/api/legacy/unleash/admin/events.html index 83ceb9ddc2..3eb34b1555 100644 --- a/reference/api/legacy/unleash/admin/events.html +++ b/reference/api/legacy/unleash/admin/events.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    /api/admin/events

    note

    In order to access the admin API endpoints you need to identify yourself. Unless you're using the none authentication method, you'll need to create an ADMIN token and add an Authorization header using the token.

    The Events API lets you retrieve events from your Unleash instance.

    Event endpoints​

    Get all events​

    Retrieve all events from the Unleash instance.
    GET <unleash-url>/api/admin/events
    Authorization: <API-token>
    content-type: application/json

    Query parameters​

    Query parameterDescriptionRequired
    projectWhen applied, the endpoint will only return events from the given project.No

    When called without any query parameters, the endpoint will return the last 100 events from the Unleash instance. When called with a project query parameter, it will return only events related to that project, but it will return all the events, and not just the last 100.

    Get events by project​

    Retrieve all events belonging to the given project.
    GET <unleash-url>/api/admin/events?project=<project-name>
    Authorization: <API-token>
    content-type: application/json

    Use the project query parameter to make the API return all events pertaining to the given project.

    Responses​

    Responses
    200 OK​

    The last 100 events from the Unleash server when called without a project query parameter.

    When called with a project query parameter: all events related to that project.

    Successful response; a list of events
    {
      "version": 1,
      "events": [
        {
          "id": 842,
          "type": "feature-environment-enabled",
          "createdBy": "user@company.com",
          "createdAt": "2022-05-12T08:49:49.521Z",
          "data": null,
          "preData": null,
          "tags": [],
          "featureName": "my-constrained-toggle",
          "project": "my-project",
          "environment": "development"
        },
        {
          "id": 841,
          "type": "feature-environment-disabled",
          "createdBy": "user@company.com",
          "createdAt": "2022-05-12T08:49:45.986Z",
          "data": null,
          "preData": null,
          "tags": [],
          "featureName": "my-constrained-toggle",
          "project": "my-project",
          "environment": "development"
        }
      ]
    }

    Get events for a specific toggle​

    Retrieve all events related to the given toggle.
    GET <unleash-url>/api/admin/events/<toggle-name>
    Authorization: <API-token>
    content-type: application/json

    Fetch all events related to a specified toggle.

    Responses​

    Responses
    200 OK​

    The list of events related to the given toggle.

    Successful response; all events relating to the specified toggle
    {
      "toggleName": "my-constrained-toggle",
      "events": [
        {
          "id": 842,
          "type": "feature-environment-enabled",
          "createdBy": "user@company.com",
          "createdAt": "2022-05-12T08:49:49.521Z",
          "data": null,
          "preData": null,
          "tags": [],
          "featureName": "my-constrained-toggle",
          "project": "my-project",
          "environment": "development"
        },
        {
          "id": 841,
          "type": "feature-environment-disabled",
          "createdBy": "user@company.com",
          "createdAt": "2022-05-12T08:49:45.986Z",
          "data": null,
          "preData": null,
          "tags": [],
          "featureName": "my-constrained-toggle",
          "project": "my-project",
          "environment": "development"
        }
      ]
    }

    Event type description​

    Content moved

    This section has been moved to a dedicated event type reference document.

    - + \ No newline at end of file diff --git a/reference/api/legacy/unleash/admin/feature-types.html b/reference/api/legacy/unleash/admin/feature-types.html index 6e29b31af4..37ea36c7ee 100644 --- a/reference/api/legacy/unleash/admin/feature-types.html +++ b/reference/api/legacy/unleash/admin/feature-types.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    /api/admin/feature-types

    In order to access the admin API endpoints you need to identify yourself. Unless you're using the none authentication method, you'll need to create an ADMIN token and add an Authorization header using the token.

    Feature Types API

    GET: http://unleash.host.com/api/admin/feature-types

    Used to fetch all feature types defined in the unleash system.

    Response

    {
      "version": 1,
      "types": [
        {
          "id": "release",
          "name": "Release",
          "description": "Used to enable trunk-based development for teams practicing Continuous Delivery.",
          "lifetimeDays": 40
        },
        {
          "id": "experiment",
          "name": "Experiment",
          "description": "Used to perform multivariate or A/B testing.",
          "lifetimeDays": 40
        },
        {
          "id": "ops",
          "name": "Operational",
          "description": "Used to control operational aspects of the system behavior.",
          "lifetimeDays": 7
        },
        {
          "id": "killswitch",
          "name": "Kill switch",
          "description": "Used to to gracefully degrade system functionality.",
          "lifetimeDays": null
        },
        {
          "id": "permission",
          "name": "Permission",
          "description": "Used to change the features or product experience that certain users receive.",
          "lifetimeDays": null
        }
      ]
    }
    - + \ No newline at end of file diff --git a/reference/api/legacy/unleash/admin/features-v2.html b/reference/api/legacy/unleash/admin/features-v2.html index c1b324678f..3c29b6b28b 100644 --- a/reference/api/legacy/unleash/admin/features-v2.html +++ b/reference/api/legacy/unleash/admin/features-v2.html @@ -20,7 +20,7 @@ - + @@ -29,7 +29,7 @@
    Skip to main content

    /api/admin/projects/:projectId

    info

    In order to access the admin API endpoints you need to identify yourself. Unless you're using the none authentication method, you'll need to create an admin token and add an Authorization header using the token.

    Fetching Feature Toggles​

    Available since Unleash v4.3

    In this document we will guide you on how you can work with feature toggles and their configuration. Please remember the following details:

    • All feature toggles exists inside a project.
    • A feature toggle exists across all environments.
    • A feature toggle can take different configuration, activation strategies, per environment.
    note

    This document lists HTTP request data and cURL and HTTPie command examples for all endpoints. Further examples use HTTPie.

    Get Project Overview​

    Get a project overview
    GET <unleash-url>/api/admin/projects/:project-id
    Authorization: <API-token>
    content-type: application/json

    This endpoint will give you an general overview of a project. It will return essential details about a project, in addition it will return all feature toggles and high level environment details per feature toggle.

    Example Query

    http GET http://localhost:4242/api/admin/projects/default Authorization:$KEY

    Example response:

    {
      "description": "Default project",
      "features": [
        {
          "createdAt": "2021-08-31T08:00:33.335Z",
          "environments": [
            {
              "displayName": "Development",
              "enabled": false,
              "name": "development"
            },
            {
              "displayName": "Production",
              "enabled": false,
              "name": "production"
            }
          ],
          "lastSeenAt": null,
          "name": "demo",
          "stale": false,
          "type": "release"
        },
        {
          "createdAt": "2021-08-31T09:43:13.686Z",
          "environments": [
            {
              "displayName": "Development",
              "enabled": false,
              "name": "development"
            },
            {
              "displayName": "Production",
              "enabled": false,
              "name": "production"
            }
          ],
          "lastSeenAt": null,
          "name": "demo.test",
          "stale": false,
          "type": "release"
        }
      ],
      "health": 100,
      "members": 2,
      "name": "Default",
      "version": 1
    }

    From the results we can see that we have received two feature toggles, demo, demo.test, and other useful metadata about the project.

    Get All Feature Toggles​

    Get all feature toggles in a project
    GET <unleash-url>/api/admin/projects/:projectId/features
    Authorization: <API-token>
    content-type: application/json

    This endpoint will return all feature toggles and high level environment details per feature toggle for a given projectId

    Example Query

    http GET http://localhost:4242/api/admin/projects/default/features \
    Authorization:$KEY

    Example response:

    {
      "features": [
        {
          "createdAt": "2021-08-31T08:00:33.335Z",
          "environments": [
            {
              "displayName": "Development",
              "enabled": false,
              "name": "development"
            },
            {
              "displayName": "Production",
              "enabled": false,
              "name": "production"
            }
          ],
          "lastSeenAt": null,
          "name": "demo",
          "stale": false,
          "type": "release"
        },
        {
          "createdAt": "2021-08-31T09:43:13.686Z",
          "environments": [
            {
              "displayName": "Development",
              "enabled": false,
              "name": "development"
            },
            {
              "displayName": "Production",
              "enabled": false,
              "name": "production"
            }
          ],
          "lastSeenAt": null,
          "name": "demo.test",
          "stale": false,
          "type": "release"
        }
      ],
      "version": 1
    }

    Create Feature Toggle​

    Create a feature toggle with the specified details (example data)
    POST <unleash-url>/api/admin/projects/:projectId/features
    Authorization: <API-token>
    content-type: application/json

    {
      "name": "my-feature-toggle"
    }

    This endpoint will accept HTTP POST request to create a new feature toggle for a given projectId

    Toggle options

    This endpoint accepts the following toggle options:

    Property nameRequiredDescriptionExample value
    nameYesThe name of the feature toggle."my-feature-toggle"
    descriptionNoThe feature toggle's description. Defaults to an empty string."Turn my feature on!"
    impressionDataNoWhether to enable impression data for this toggle. Defaults to false.true
    typeNoThe type of toggle you want to create. Defaults to "release""release"

    Example Query

    echo '{"name": "demo2", "description": "A new feature toggle"}' | \
    http POST http://localhost:4242/api/admin/projects/default/features \
    Authorization:$KEY`

    Example response:

    HTTP/1.1 201 Created
    Access-Control-Allow-Origin: *
    Connection: keep-alive
    Content-Length: 159
    Content-Type: application/json; charset=utf-8
    Date: Tue, 07 Sep 2021 20:16:02 GMT
    ETag: W/"9f-4btEokgk0N74zuBVKKxws0IBu4w"
    Keep-Alive: timeout=60
    Vary: Accept-Encoding

    {
        "createdAt": "2021-09-07T20:16:02.614Z",
        "description": "A new feature toggle",
        "lastSeenAt": null,
        "name": "demo2",
        "project": "default",
        "stale": false,
        "type": "release",
        "variants": null
    }

    Possible Errors:

    • 409 Conflict - A toggle with that name already exists

    Get Feature Toggle​

    Retrieve a named feature toggle
    GET <unleash-url>/api/admin/projects/:projectId/features/:featureName
    Authorization: <API-token>
    content-type: application/json

    This endpoint will return the feature toggles with the defined name and projectId. We will also see the list of environments and all activation strategies configured per environment.

    Example Query

    http GET http://localhost:4242/api/admin/projects/default/features/demo \
    Authorization:$KEY`

    Example response:

    {
        "archived": false,
        "createdAt": "2021-08-31T08:00:33.335Z",
        "description": null,
        "environments": [
            {
                "enabled": false,
                "name": "development",
                "strategies": [
                    {
                        "constraints": [],
                        "id": "8eaa8abb-0e03-4dbb-a440-f3bf193917ad",
                        "name": "default",
                        "parameters": null
                    }
                ]
            },
            {
                "enabled": false,
                "name": "production",
                "strategies": []
            }
        ],
        "lastSeenAt": null,
        "name": "demo",
        "project": "default",
        "stale": false,
        "type": "release",
        "variants": null
    }

    Possible Errors:

    • 404 Not Found - Could not find feature toggle with the provided name.

    Update Feature Toggle​

    Update a feature toggle entry (example data)
    PUT <unleash-url>/api/admin/projects/:projectId/features/:featureName
    Authorization: <API-token>
    content-type: application/json

    {
      "name": "demo",
      "description": "An updated feature toggle description."
    }

    This endpoint will accept HTTP PUT request to update the feature toggle metadata.

    Example Query

    echo '{"name": "demo", "description": "An update feature toggle", "type": "kill-switch"}' | \
    http PUT http://localhost:4242/api/admin/projects/default/features/demo \
    Authorization:$KEY`

    Example response:

    {
        "createdAt": "2021-09-07T20:16:02.614Z",
        "description": "An update feature toggle",
        "lastSeenAt": null,
        "name": "demo",
        "project": "default",
        "stale": false,
        "type": "kill-switch",
        "variants": null
    }

    Some fields is not possible to change via this endpoint:

    • name
    • project
    • createdAt
    • lastSeen

    Patch Feature Toggle​

    Patch a feature toggle (example data)
    PATCH <unleash-url>/api/admin/projects/:projectId/features/:featureName
    Authorization: <API-token>
    content-type: application/json

    [
      {
        "op": "replace",
        "path": "/description",
        "value": "patched description"
      }
    ]

    This endpoint will accept HTTP PATCH request to update the feature toggle metadata.

    Example Query

    echo '[{"op": "replace", "path": "/description", "value": "patched desc"}]' | \
    http PATCH http://localhost:4242/api/admin/projects/default/features/demo \
    Authorization:$KEY`

    Example response:

    {
        "createdAt": "2021-09-07T20:16:02.614Z",
        "description": "patched desc",
        "lastSeenAt": null,
        "name": "demo",
        "project": "default",
        "stale": false,
        "type": "release",
        "variants": null
    }

    Some fields is not possible to change via this endpoint:

    • name
    • project
    • createdAt
    • lastSeen

    Clone Feature Toggle​

    Clone a feature toggle (example data)
    POST <unleash-url>/api/admin/projects/:projectId/features/:featureName/clone
    Authorization: <API-token>
    content-type: application/json

    {
      "name": "newToggleName"
    }

    This endpoint will accept HTTP POST request to clone an existing feature toggle with all strategies and variants. When cloning a toggle, you must provide a new name for it. You can not clone archived feature toggles. The newly created feature toggle will be disabled for all environments.

    Example Query

    echo '{ "name": "DemoNew" }' | \
    http POST http://localhost:4242/api/admin/projects/default/features/Demo/clone \
    Authorization:$KEY`

    Example response:

    HTTP/1.1 201 Created
    Access-Control-Allow-Origin: *
    Connection: keep-alive
    Content-Length: 260
    Content-Type: application/json; charset=utf-8
    Date: Wed, 06 Oct 2021 20:04:39 GMT
    ETag: W/"104-joC/gdjtJ29jZMxj91lIzR42Pmo"
    Keep-Alive: timeout=60
    Vary: Accept-Encoding

    {
        "createdAt": "2021-09-29T10:22:28.523Z",
        "description": "Some useful description",
        "lastSeenAt": null,
        "name": "DemoNew",
        "project": "default",
        "stale": false,
        "type": "release",
        "variants": [
            {
                "name": "blue",
                "overrides": [],
                "stickiness": "default",
                "weight": 1000,
                "weightType": "variable"
            }
        ]
    }

    Possible Errors:

    • 409 Conflict - A toggle with that name already exists

    Archive Feature Toggle​

    Archive a named feature toggle
    DELETE <unleash-url>/api/admin/projects/:projectId/features/:featureName
    Authorization: <API-token>
    content-type: application/json

    This endpoint will accept HTTP DELETE requests to archive a feature toggle.

    Example Query

    http DELETE http://localhost:4242/api/admin/projects/default/features/demo \
    Authorization:$KEY`

    Example response:

    HTTP/1.1 202 Accepted
    Access-Control-Allow-Origin: *
    Connection: keep-alive
    Date: Wed, 08 Sep 2021 20:09:21 GMT
    Keep-Alive: timeout=60
    Transfer-Encoding: chunked

    Add strategy to Feature Toggle​

    Add a new strategy to the named feature toggle in the named environment (example data)
    POST <unleash-url>/api/admin/projects/:projectId/features/:featureName/environments/:environment/strategies
    Authorization: <API-token>
    content-type: application/json

    {
      "name": "flexibleRollout",
      "parameters": {
        "rollout": 20,
        "groupId": "demo",
        "stickiness": "default"
      }
    }

    This endpoint will allow you to add a new strategy to a feature toggle in a given environment.

    Example Query

    echo '{"name": "flexibleRollout",
            "parameters": {
                "rollout": 20,
                "groupId": "demo",
                "stickiness": "default"
              }
          }' | \
    http POST \
    http://localhost:4242/api/admin/projects/default/features/demo/environments/production/strategies \
    Authorization:$KEY

    Example response:

    {
        "constraints": [],
        "id": "77bbe972-ffce-49b2-94d9-326593e2228e",
        "name": "flexibleRollout",
        "parameters": {
            "groupId": "demo",
            "rollout": 20,
            "stickiness": "default"
        }
    }

    Update strategy configuration​

    Overwrite the specified strategy on the named feature toggle in the named environment (example data)
    PUT <unleash-url>/api/admin/projects/:projectId/features/:featureName/environments/:environment/strategies/:strategy-id
    Authorization: <API-token>
    content-type: application/json

    {
      "name": "flexibleRollout",
      "parameters": {
        "rollout": 25,
        "groupId": "demo",
        "stickiness": "default"
      }
    }

    Example Query

    echo '{"name": "flexibleRollout",
            "parameters": {
              "rollout": 25,
              "groupId": "demo",
              "stickiness": "default"
            }
          }' | \
    http PUT \
    http://localhost:4242/api/admin/projects/default/features/demo/environments/production/strategies/77bbe972-ffce-49b2-94d9-326593e2228e \
    Authorization:$KEY

    Example response:

    {
        "constraints": [],
        "id": "77bbe972-ffce-49b2-94d9-326593e2228e",
        "name": "flexibleRollout",
        "parameters": {
            "groupId": "demo",
            "rollout": 20,
            "stickiness": "default"
        }
    }

    Patch strategy configuration​

    Patch update a strategy definition (example data)
    PATCH <unleash-url>/api/admin/projects/:project-id/features/:featureName/environments/:environment/strategies/:strategyId
    Authorization: <API-token>
    content-type: application/json

    [
      {
        "op": "replace",
        "path": "/parameters/rollout",
        "value": 50
      }
    ]

    Example Query

    echo '[{"op": "replace", "path": "/parameters/rollout", "value": 50}]' | \
    http PATCH \
    http://localhost:4242/api/admin/projects/default/features/demo/environments/production/strategies/ea5404e5-0c0d-488c-93b2-0a2200534827 \
    Authorization:$KEY

    Example response:

    {
        "constraints": [],
        "id": "ea5404e5-0c0d-488c-93b2-0a2200534827",
        "name": "flexibleRollout",
        "parameters": {
            "groupId": "demo",
            "rollout": 50,
            "stickiness": "default"
        }
    }

    Delete strategy from Feature Toggle​

    Delete the strategy with the given ID
    DELETE <unleash-url>/api/admin/projects/:projectId/features/:featureName/environments/:environment/strategies/:strategyId
    Authorization: <API-token>
    content-type: application/json

    Example Query

    http DELETE http://localhost:4242/api/admin/projects/default/features/demo/environments/production/strategies/77bbe972-ffce-49b2-94d9-326593e2228e Authorization:$KEY

    Example response:

    HTTP/1.1 200 OK
    Access-Control-Allow-Origin: *
    Connection: keep-alive
    Content-Type: application/json; charset=utf-8
    Date: Tue, 07 Sep 2021 20:47:55 GMT
    Keep-Alive: timeout=60
    Transfer-Encoding: chunked
    Vary: Accept-Encoding

    Enabling and disabling toggles​

    Enable Feature Toggle in an Environment​

    Activate the named toggle in the given environment
    POST <unleash-url>/api/admin/projects/:projectId/features/:featureName/environments/:environment/on
    Authorization: <API-token>
    content-type: application/json

    Example Query

    http POST http://localhost:4242/api/admin/projects/default/features/demo/environments/development/on Authorization:$KEY --json

    Example response:

    HTTP/1.1 200 OK
    Access-Control-Allow-Origin: *
    Connection: keep-alive
    Date: Tue, 07 Sep 2021 20:49:51 GMT
    Keep-Alive: timeout=60
    Transfer-Encoding: chunked

    Possible Errors:

    • 409 Conflict - You can not enable the environment before it has strategies.

    Disable Feature Toggle in an Environment​

    Disable the named toggle in the given environment
    POST <unleash-url>/api/admin/projects/:projectId/features/:featureName/environments/:environment/off
    Authorization: <API-token>
    content-type: application/json

    Example Query

    http POST http://localhost:4242/api/admin/projects/default/features/demo/environments/development/off Authorization:$KEY --json

    Example response:

    HTTP/1.1 200 OK
    Access-Control-Allow-Origin: *
    Connection: keep-alive
    Date: Tue, 07 Sep 2021 20:49:51 GMT
    Keep-Alive: timeout=60
    Transfer-Encoding: chunked

    Feature Variants​

    Put variants for Feature Toggle​

    caution

    From 4.21 variants are tied to an environment. Check our Open API docs for the up-to-date docs: https://docs.getunleash.io/reference/api/unleash/features

    This endpoint affects all environments at once. If you only want to update a single environment, use #update-variants-per-environment instead.

    Create (overwrite) variants for a feature toggle in all environments (example data)
    PUT <unleash-url>/api/admin/projects/:projectId/features/:featureName/variants
    Authorization: <API-token>
    content-type: application/json

    [
      {
        "name": "variant1",
        "weightType": "fix",
        "weight": 650,
        "payload": {
          "type": "json",
          "value": "{\"key1\": \"value\", \"key2\": 123}"
        },
        "stickiness": "userId",
        "overrides": [
          {
            "contextName": "userId",
            "values": [
              "1",
              "23"
            ]
          }
        ]
      },
      {
        "name": "variant2",
        "weightType": "variable",
        "weight": 123
      }
    ]

    This overwrites the current variants for the feature toggle specified in the :featureName parameter. The backend will validate the input for the following invariants

    • If there are variants, there needs to be at least one variant with weightType: variable
    • The sum of the weights of variants with weightType: fix must be below 1000 (< 1000)

    The backend will also distribute remaining weight up to 1000 after adding the variants with weightType: fix together amongst the variants of weightType: variable

    Example Query

    echo '[
        {
            "name": "variant1",
            "weightType": "fix",
            "weight": 650,
            "payload": {
              "type": "json",
              "value": "{\"key1\": \"value\", \"key2\": 123}"
            },
            "stickiness": "userId",
            "overrides": [{
              "contextName": "userId",
              "values": ["1", "23"]
            }]
        },
        {
            "name": "variant2",
            "weightType": "variable",
            "weight": 123
        }
    ]' | \
    http PUT http://localhost:4242/api/admin/projects/default/features/demo/variants Authorization:$KEY

    Example response:

    HTTP/1.1 200 OK
    Access-Control-Allow-Origin: *
    Connection: keep-alive
    Date: Tue, 23 Nov 2021 08:46:32 GMT
    Keep-Alive: timeout=60
    Transfer-Encoding: chunked
    Content-Type: application/json; charset=utf-8

    {
      "version": "1",
      "variants": [
        {
          "name": "variant2",
          "weightType": "variable",
          "weight": 350
        },
        {
          "name": "variant1",
          "weightType": "fix",
          "weight": 650
        }
      ]
    }

    PATCH variants for a feature toggle​

    caution

    This API documentation is no longer maintained. You should use the OpenAPI docs for this endpoint instead.

    This endpoint affects all environments at once. If you only want to update a single environment, use the operation for updating variants per enviroment instead.

    Patch variants for a feature toggle in all environments (example data)
    PATCH <unleash-url>/api/admin/projects/:projectId/features/:featureName/variants
    Authorization: <API-token>
    content-type: application/json

    [
      {
        "op": "add",
        "path": "/1",
        "value": {
          "name": "new-variant",
          "weightType": "fix",
          "weight": 200
        }
      }
    ]

    Example Query

    echo '[{"op": "add", "path": "/1", "value": {
      "name": "new-variant",
      "weightType": "fix",
      "weight": 200
    }}]' | \
    http PATCH \
    http://localhost:4242/api/admin/projects/default/features/demo/variants \
    Authorization:$KEY

    Example Response 

    {
      "version": "1",
      "variants": [
        {
          "name": "variant2",
          "weightType": "variable",
          "weight": 150
        },
        {
          "name": "new-variant",
          "weightType": "fix",
          "weight": 200
        },
        {
          "name": "variant1",
          "weightType": "fix",
          "weight": 650
        }
      ]
    }

    Manage project users and roles​

    You can add and remove users to a project using the /api/admin/projects/:projectId/users/:userId/roles/:roleId endpoint. When adding or removing users, you must also provide the ID for the role to give them (when adding) or the ID of the role they currently have (when removing).

    Add a user to a project​

    Add a user to a project (example data)
    POST <unleash-url>/api/admin/projects/:projectId/users/:userId/roles/:roleId
    Authorization: <API-token>
    content-type: application/json

    {
      "userId": 25,
      "projectId": "myProject",
      "roleId": "1"
    }

    This will add a user to a project and give the user a specified role within that project.

    URL parameters​

    ParameterTypeDescriptionExample value
    userIdintegerThe ID of the user you want to add to the project.1
    projectIdstringThe id of the project to add the user to."MyCoolProject"
    roleIdintegerThe id of the role you want to assign to the new user in the project.7

    Responses​

    Responses data
    200 OK​

    The user was added to the project with the specified role. This response has no body.

    400 Bad Request​

    The user already exists in the project and cannot be added again:

    [
      {
        "msg": "User already has access to project=<projectId>"
      }
    ]

    Example query​

    The following query would add the user with ID 42 to the MyCoolProject project and give them the role with ID 13.

    http POST \
    http://localhost:4242/api/admin/projects/MyCoolProject/users/42/roles/13 \
    Authorization:$KEY

    Change a user's role in a project​

    Update a user's role in a project
    PUT <unleash-url>/api/admin/projects/:projectId/users/:userId/roles/:roleId
    Authorization: <API-token>
    content-type: application/json

    {
      "userId": 25,
      "projectId": "myProject",
      "roleId": "3"
    }

    This will change the user's project role to the role specified by :roleId. If the user has not been added to the project, nothing happens.

    URL parameters​

    ParameterTypeDescriptionExample value
    userIdintegerThe ID of the user whose role you want to update.1
    projectIdstringThe id of the relevant project."MyCoolProject"
    roleIdintegerThe role ID of the role you wish to assign the user.7

    Responses​

    Responses data
    200 OK​

    The user's role has been successfully changed. This response has no body.

    400 Bad Request​

    You tried to change the role of the only user with the owner role in the project:

    [
      {
        "msg": "A project must have at least one owner."
      }
    ]

    Example query​

    The following query would change the role of the user with ID 42 the role with ID 13 in the MyCoolProject project.

    http PUT \
    http://localhost:4242/api/admin/projects/MyCoolProject/users/42/roles/13 \
    Authorization:$KEY

    Remove a user from a project​

    Delete a user from a project
    DELETE <unleash-url>/api/admin/projects/:projectId/users/:userId/roles/:roleId
    Authorization: <API-token>
    content-type: application/json

    This removes the specified role from the user in the project. Because users can only have one role in a project, this effectively removes the user from the project. The user must have the role indicated by the :roleId URL parameter for the request to succeed.

    URL parameters​

    ParameterTypeDescriptionExample value
    userIdintegerThe ID of the user you want to remove from the project.1
    projectIdstringThe id of the project to remove the user from."MyCoolProject"
    roleIdintegerThe current role the of the user you want to remove from the project.7

    Responses​

    Responses data
    200 OK​

    The user no longer has the specified role in the project. If the user had this role prior to this API request, they will have been removed from the project. This response has no body.

    400 Bad Request​

    You tried to remove the only user with the role owner in the project:

    [
      {
        "msg": "A project must have at least one owner."
      }
    ]

    Example query​

    The following query would remove the user with ID 42 and role ID 13 from the MyCoolProject project.

    http DELETE \
    http://localhost:4242/api/admin/projects/MyCoolProject/users/42/roles/13 \
    Authorization:$KEY
    - + \ No newline at end of file diff --git a/reference/api/legacy/unleash/admin/features.html b/reference/api/legacy/unleash/admin/features.html index 7c9a803376..387c93b727 100644 --- a/reference/api/legacy/unleash/admin/features.html +++ b/reference/api/legacy/unleash/admin/features.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    /api/admin/features

    Deprecation notice

    Most of this API was removed in Unleash v5 (after being deprecated since Unleash v4.3). You should use the project-based API (/api/admin/projects/:projectId) instead.

    info

    In order to access the admin API endpoints you need to identify yourself. Unless you're using the none authentication method, you'll need to create an admin token and add an Authorization header using the token.

    Fetching Feature Toggles​

    Deprecation notice

    This endpoint was removed in Unleash v5. Please use the project-based endpoint to fetch all toggles instead.

    GET: http://unleash.host.com/api/admin/features

    This endpoint is the one all admin ui should use to fetch all available feature toggles from the unleash-server. The response returns all active feature toggles and their current strategy configuration. A feature toggle will have at least one configured strategy. A strategy will have a name and parameters map.

    Example response:

    {
      "version": 2,
      "features": [
        {
          "name": "Feature.A",
          "description": "lorem ipsum",
          "type": "release",
          "enabled": false,
          "stale": false,
          "strategies": [
            {
              "name": "default",
              "parameters": {}
            }
          ],
          "variants": [
            {
              "name": "variant1",
              "weight": 50
            },
            {
              "name": "variant2",
              "weight": 50
            }
          ],
          "tags": [
            {
              "id": 1,
              "type": "simple",
              "value": "TeamRed"
            }
          ]
        },
        {
          "name": "Feature.B",
          "description": "lorem ipsum",
          "enabled": true,
          "stale": false,
          "strategies": [
            {
              "name": "ActiveForUserWithId",
              "parameters": {
                "userIdList": "123,221,998"
              }
            },
            {
              "name": "GradualRolloutRandom",
              "parameters": {
                "percentage": "10"
              }
            }
          ],
          "variants": [],
          "tags": []
        }
      ]
    }

    Filter feature toggles​

    Supports three params for now

    • tag - filters for features tagged with tag
    • project - filters for features belonging to project
    • namePrefix - filters for features beginning with prefix

    For tag and project performs OR filtering if multiple arguments

    To filter for any feature tagged with a simple tag with value taga or a simple tag with value tagb use

    GET https://unleash.host.com/api/admin/features?tag[]=simple:taga&tag[]simple:tagb

    To filter for any feature belonging to project myproject use

    GET https://unleash.host.com/api/admin/features?project=myproject

    Response format is the same as api/admin/features

    Fetch specific feature toggle​

    Removal notice

    This endpoint was removed in Unleash v5 (deprecated since v4). Please use the project-based endpoint to fetch specific toggles instead.

    GET: http://unleash.host.com/api/admin/features/:featureName

    Used to fetch details about a specific featureToggle. This is mostly provded to make it easy to debug the API and should not be used by the client implementations.

    {
      "name": "Feature.A",
      "description": "lorem ipsum..",
      "type": "release",
      "enabled": false,
      "stale": false,
      "strategies": [
        {
          "name": "default",
          "parameters": {}
        }
      ],
      "variants": [],
      "tags": []
    }

    Create a new Feature Toggle​

    Removal notice

    This endpoint was removed in Unleash v5 (deprecated since v4). Please use the project-based endpoint to create feature toggles instead.

    POST: http://unleash.host.com/api/admin/features/

    Body:

    {
      "name": "Feature.A",
      "description": "lorem ipsum..",
      "type": "release",
      "enabled": false,
      "stale": false,
      "strategies": [
        {
          "name": "default",
          "parameters": {}
        }
      ]
    }

    Used by the admin-dashboard to create a new feature toggles.

    Notes:

    • name must be globally unique, otherwise you will get a 403-response.
    • type is optional. If not defined it defaults to release

    Returns 200-response if the feature toggle was created successfully.

    Update a Feature Toggle​

    Removal notice

    This endpoint was removed in Unleash v5. Please use the project-based endpoint to update a feature toggle instead.

    PUT: http://unleash.host.com/api/admin/features/:toggleName

    Body:

    {
      "name": "Feature.A",
      "description": "lorem ipsum..",
      "type": "release",
      "enabled": false,
      "stale": false,
      "strategies": [
        {
          "name": "default",
          "parameters": {}
        }
      ],
      "variants": []
    }

    Used by the admin dashboard to update a feature toggles. The name has to match an existing features toggle.

    Returns 200-response if the feature toggle was updated successfully.

    Tag a Feature Toggle​

    POST https://unleash.host.com/api/admin/features/:featureName/tags

    Used to tag a feature

    If the tuple (type, value) does not already exist, it will be added to the list of tags. Then Unleash will add a relation between the feature name and the tag.

    Body:

    {
      "type": "simple",
      "value": "Team-Green"
    }

    Success

    - Returns _201-CREATED_ if the feature was tagged successfully
    - Creates the tag if needed, then connects the tag to the existing feature

    Failures

    - Returns _404-NOT-FOUND_ if the `type` was not found

    Remove a tag from a Feature Toggle​

    DELETE https://unleash.host.com/api/admin/features/:featureName/tags/:type/:value

    Removes the specified tag from the (type, value) tuple from the Feature Toggle's list of tags.

    Success

    - Returns _200-OK_

    Failures

    - Returns 404 if the tag does not exist
    - Returns 500 if the database could not be reached

    Archive a Feature Toggle​

    Removal notice

    This endpoint was removed in v5. Please use the project-based endpoint to archive toggles instead.

    DELETE: http://unleash.host.com/api/admin/features/:toggleName

    Used to archive a feature toggle. A feature toggle can never be totally be deleted, but can be archived. This is a design decision to make sure that a old feature toggle does not suddenly reappear because someone else is re-using the same name.

    Enable a Feature Toggle​

    Removal notice

    This endpoint was removed in v5. Please use the project-based endpoint to enable feature toggles instead.

    POST: http://unleash.host.com/api/admin/features/:featureName/toggle/on

    Used to enable a feature toggle. The :featureName must match an existing Feature Toggle. Returns 200-response if the feature toggle was enabled successfully.

    Body

    None

    Example response:

    {
      "name": "Feature.A",
      "description": "lorem ipsum..",
      "type": "release",
      "enabled": true,
      "strategies": [
        {
          "name": "default",
          "parameters": {}
        }
      ],
      "variants": [],
      "tags": []
    }

    Disable a Feature Toggle​

    Removal notice

    This endpoint was removed in v5. Please use the project-based endpoint to disable feature toggles instead.

    POST: http://unleash.host.com/api/admin/features/:featureName/toggle/off

    Used to disable a feature toggle. The :featureName must match an existing Feature Toggle. Returns 200-response if the feature toggle was disabled successfully.

    Body

    None

    Example response:

    {
      "name": "Feature.A",
      "description": "lorem ipsum..",
      "type": "release",
      "enabled": false,
      "stale": false,
      "strategies": [
        {
          "name": "default",
          "parameters": {}
        }
      ],
      "variants": [],
      "tags": []
    }

    Mark a Feature Toggle as "stale"​

    Removal notice

    This endpoint was removed in v5. Please use the project-based endpoint to patch a feature toggle and mark it as stale instead.

    POST: http://unleash.host.com/api/admin/features/:featureName/stale/on

    Used to mark a feature toggle as stale (deprecated). The :featureName must match an existing Feature Toggle. Returns 200-response if the feature toggle was enabled successfully.

    Body

    None

    Example response:

    {
      "name": "Feature.A",
      "description": "lorem ipsum..",
      "type": "release",
      "enabled": true,
      "stale": true,
      "strategies": [
        {
          "name": "default",
          "parameters": {}
        }
      ],
      "variants": [],
      "tags": []
    }

    Mark a Feature Toggle as "active"​

    Removal notice

    This endpoint was removed in v5. Please use the project-based endpoint to patch a feature toggle and mark it as not stale instead.

    POST: http://unleash.host.com/api/admin/features/:featureName/stale/off

    Used to mark a feature toggle active (remove stale marking). The :featureName must match an existing Feature Toggle. Returns 200-response if the feature toggle was disabled successfully.

    Body

    None

    Example response:

    {
      "name": "Feature.A",
      "description": "lorem ipsum..",
      "type": "release",
      "enabled": false,
      "stale": false,
      "strategies": [
        {
          "name": "default",
          "parameters": {}
        }
      ],
      "variants": [],
      "tags": []
    }
    - + \ No newline at end of file diff --git a/reference/api/legacy/unleash/admin/metrics.html b/reference/api/legacy/unleash/admin/metrics.html index 2bb09f7904..145ae8e219 100644 --- a/reference/api/legacy/unleash/admin/metrics.html +++ b/reference/api/legacy/unleash/admin/metrics.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    /api/admin/metrics

    In order to access the admin API endpoints you need to identify yourself. Unless you're using the none authentication method, you'll need to create an ADMIN token and add an Authorization header using the token.

    This document describes the metrics endpoint for admin ui

    Seen-toggles​

    Deprecation notice

    This endpoint has been deprecated

    GET http://unleash.host.com/api/admin/metrics/seen-toggles

    This enpoints returns a list of applications and what toogles unleash has seen for each application. It will only guarantee toggles reported by client applications within the last hour, but will in most cases remember seen toggles for applications longer.

    Example response:

    [
      {
        "appName": "demo-app",
        "seenToggles": ["add-feature-2", "toggle-2", "toggle-3"],
        "metricsCount": 127
      },
      {
        "appName": "demo-app-2",
        "seenToggles": ["add-feature-2", "toggle-2", "toggle-3"],
        "metricsCount": 21
      }
    ]

    Fields:

    • appName - Name of the application seen by unleash-server
    • seenToggles - array of toggles names seen by unleash-server for this application
    • metricsCount - number of metrics counted across all toggles for this application.

    Feature-Toggles metrics​

    GET http://unleash.host.com/api/admin/metrics/feature-toggles

    This endpoint gives last minute and last hour metrics for all active toggles. This is based on metrics reported by client applications. Yes is the number of times a given feature toggle was evaluated to enabled in a client application, and no is the number it was evaluated to false.

    Example response:

    {
      "lastHour": {
        "add-feature-2": {
          "yes": 0,
          "no": 527
        },
        "toggle-2": {
          "yes": 265,
          "no": 85
        },
        "toggle-3": {
          "yes": 257,
          "no": 93
        }
      },
      "lastMinute": {
        "add-feature-2": {
          "yes": 0,
          "no": 527
        },
        "toggle-2": {
          "yes": 265,
          "no": 85
        },
        "toggle-3": {
          "yes": 257,
          "no": 93
        }
      }
    }

    Fields:

    • lastHour - Hour projection collected metrics for all feature toggles.
    • lastMinute - Minute projection collected metrics for all feature toggles.

    Applications​

    GET http://unleash.host.com/api/admin/metrics/applications

    This endpoint returns a list of known applications (seen in the last day) and a link to follow for more details.

    {
      "applications": [
        {
          "appName": "another",
          "strategies": ["default", "other", "brother"],
          "createdAt": "2016-12-09T14:56:36.730Z",
          "links": {
            "appDetails": "/api/admin/applications/another"
          }
        },
        {
          "appName": "bow",
          "strategies": ["default", "other", "brother"],
          "createdAt": "2016-12-09T14:56:36.730Z",
          "links": {
            "appDetails": "/api/admin/applications/bow"
          }
        }
      ]
    }

    Query Params​

    You can also specify the query param: strategyName, which will return all applications implementing the given strategy.

    GET http://unleash.host.com/api/admin/metrics/applications?strategyName=someStrategyName

    Application Details​

    GET http://unleash.host.com/api/admin/metrics/applications/:appName

    This endpoint gives insight into details about a client application, such as instances, strategies implemented and seen toggles.

    {
      "appName": "demo-app",
      "instances": [
        {
          "instanceId": "generated-732038-17080",
          "clientIp": "::ffff:127.0.0.1",
          "lastSeen": "2016-11-30T17:32:04.265Z",
          "createdAt": "2016-11-30T17:31:08.914Z"
        },
        {
          "instanceId": "generated-639919-11185",
          "clientIp": "::ffff:127.0.0.1",
          "lastSeen": "2016-11-30T16:04:15.991Z",
          "createdAt": "2016-11-30T10:49:11.223Z"
        }
      ],
      "strategies": [
        {
          "appName": "demo-app",
          "strategies": ["default", "extra"]
        }
      ],
      "seenToggles": ["add-feature-2", "toggle-2", "toggle-3"]
    }

    Seen applications​

    Deprecation notice

    This endpoint has been deprecated

    GET http://unleash.host.com/api/admin/metrics/seen-apps

    This endpoint gives insight into details about application seen per feature toggle.

    {
      "my-toggle": [
        {
          "appName": "my-app",
          "createdAt": "2016-12-28T10:39:24.966Z",
          "updatedAt": "2017-01-06T15:32:41.932Z",
          "description": "our main app",
          "strategies": [
            "gradualRolloutRandom",
            "abTest",
            "default",
            "betaUser",
            "userWithId",
            "byHostName",
            "gradualRolloutWithSessionId",
            "gradualRollout",
            "byRemoteAddr"
          ],
          "url": "http://example.com",
          "color": null,
          "icon": "terrain"
        },
        {
          "appName": "my-other-app",
          "createdAt": "2016-12-28T10:39:24.966Z",
          "updatedAt": "2017-01-06T15:32:41.932Z",
          "description": "our other app",
          "strategies": ["default"],
          "url": "http://example.com",
          "color": null,
          "icon": "desktop"
        }
      ]
    }
    - + \ No newline at end of file diff --git a/reference/api/legacy/unleash/admin/projects.html b/reference/api/legacy/unleash/admin/projects.html index 0b314508c1..9ba071d65b 100644 --- a/reference/api/legacy/unleash/admin/projects.html +++ b/reference/api/legacy/unleash/admin/projects.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    /api/admin/projects

    The context feature is only available as part of Unleash Enterprise. In order to access the API programmatically you need to make sure you obtain an API token with admin permissions.

    List projects in Unleash​

    GET https://unleash.host.com/api/admin/projects

    Returns a list of projects in Unleash.

    Example response:

    {
      "version": 1,
      "projects": [
        {
          "id": "default",
          "name": "Default",
          "description": "Default project",
          "createdAt": "2020-12-03T09:47:20.170Z"
        },
        {
          "id": "MyNewProject",
          "name": "MyNewProject",
          "description": "A test project",
          "createdAt": "2020-12-03T09:47:20.170Z"
        },
        {
          "id": "test",
          "name": "Test Project",
          "description": "Collection of test toggles",
          "createdAt": "2020-12-03T09:47:20.170Z"
        }
      ]
    }

    Create a new project​

    POST https://unleash.host.com/api/admin/projects

    Creates a new project.

    Body

    {
      "id": "someId",
      "name": "Test Project",
      "description": "Some description"
    }

    Update a projects field​

    PUT https://unleash.host.com/api/projects/:id

    Updates a project with id=id.

    Body

    {
      "id": "someId",
      "name": "Test Project",
      "description": "Some description"
    }

    Delete a projects field​

    DELETE https://unleash.host.com/api/admin/projects/:id

    Deletes the project with id=id.

    - + \ No newline at end of file diff --git a/reference/api/legacy/unleash/admin/segments.html b/reference/api/legacy/unleash/admin/segments.html index 9e51c4cf82..15e5cb7de1 100644 --- a/reference/api/legacy/unleash/admin/segments.html +++ b/reference/api/legacy/unleash/admin/segments.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    /api/admin/segments

    Availability

    Segments are available to Unleash Pro and Unleash Enterprise users since Unleash 4.13.

    note

    To use the admin API, you'll need to create and use an admin API token.

    The segments API lets you create, read, update, and delete segments.

    Get all segments​

    Retrieve all segments that exist in this Unleash instance. Returns a list of segment objects.

    Retrieve all existing segments.
    GET <unleash-url>/api/admin/segments
    Authorization: <API-token>
    content-type: application/json
    Example responses

    200 OK​

    [
      {
        "id": 1,
        "name": "my-segment",
        "description": "a segment description",
        "constraints": [],
        "createdBy": "user@example.com",
        "createdAt": "2022-04-01T14:02:25.491Z"
      }
    ]

    Create segment​

    Create a new segment with the specified configuration.

    Create a new segment.
    POST <unleash-url>/api/admin/segments
    Authorization: <API-token>
    content-type: application/json

    {
      "name": "my-segment",
      "description": "a segment description",
      "constraints": []
    }
    Example responses

    201 Created​

    The segment was successfully created. This response has no body.

    400 Bad Request​

    A segment with the provided name already exists.

    Payload structure​

    Use a JSON object with the following properties to create a new segment.

    PropertyTypeRequiredDescriptionExample value
    namestringYesThe name of the segment."mobile-users"
    descriptionstringNoA description of the segment."This segment is for users on mobile devices."
    constraintslist of constraint objectsYesThe constraints in this segment.[]

    Get segment by ID​

    Retrieves the segment with the specified ID.

    Retrieve the segment with the provided ID.
    GET <unleash-url>/api/admin/segments/<segment-id>
    Authorization: <API-token>
    content-type: application/json
    Example responses

    200 OK​

    {
      "id": 1,
      "name": "my-segment",
      "description": "a segment description",
      "constraints": [],
      "createdBy": "user@example.com",
      "createdAt": "2022-04-01T14:02:25.491Z"
    }

    404 Not Found​

    No segment with the provided ID exists.

    Update an existing segment​

    Replace the data of the specified segment with the provided payload.

    Update a segment with new data.
    PUT <unleash-url>/api/admin/segments/<segment-id>
    Authorization: <API-token>
    content-type: application/json

    {
      "name": "my-segment",
      "description": "this is a newly provided description.",
      "constraints": []
    }
    Example responses

    204 No Content​

    The update was successful. This response has no body.

    404 Not Found​

    No segment with the provided ID exists.

    Delete a segment​

    Delete the request with the specified ID.

    Delete a segment.
    DELETE <unleash-url>/api/admin/segments/<segment-id>
    Authorization: <API-token>
    content-type: application/json
    Example responses

    204 No Content​

    The segment was deleted successfully.

    404 Not Found​

    No segment with the provided ID exists.

    409 Conflict​

    The segment is being used by at least one strategy and can not be deleted. To delete the segment, first remove it from any strategies that use it.

    List strategies that use a specific segment​

    Retrieve all strategies that use the specified segment. Returns a list of activation strategy objects.

    Retrieve all activation strategies that use the specified segment.
    GET <unleash-url>/api/admin/segments/<segment-id>/strategies
    Authorization: <API-token>
    content-type: application/json
    Example responses

    200 OK​

    [
      {
        "id": "strategy-id",
        "featureName": "my-feature",
        "projectId": "my-project",
        "environment": "development",
        "strategyName": "my strategy",
        "parameters": {},
        "constraints": [],
        "createdAt": "2022-04-01T14:02:25.491Z"
      }
    ]

    404 Not Found​

    No segment with the provided id exists.

    List segments applied to a specific strategy​

    Retrieve all segments that are applied to the specified strategy. Returns a list of segment objects.

    Retrieve all segments that are used by the specified strategy.
    GET <unleash-url>/api/admin/segments/strategies/<strategy-id>
    Authorization: <API-token>
    content-type: application/json
    Example responses

    200 OK​

    [
      {
        "id": 1,
        "name": "my-segment",
        "description": "a segment description",
        "constraints": [],
        "createdBy": "user@example.com",
        "createdAt": "2022-04-01T14:02:25.491Z"
      }
    ]

    404 Not Found​

    No strategy with the provided id exists.

    Replace activation strategy segments​

    Replace the segments applied to the specified activation strategy with the provided segment list.

    Replace the segments to the specified strategy.
    POST <unleash-url>/api/admin/segments/strategies
    Authorization: <API-token>
    content-type: application/json

    {
      "projectId": "my-project",
      "strategyId": "my-strategy",
      "environmentId": "development",
      "segmentIds": [
        61,
        62,
        63,
        64
      ]
    }

    Remove all segments from an activation strategy​

    To remove all segments from an activation strategy, use this endpoint and provide an empty list of segmentIds. For instance, the following payload would remove all segments from the strategy "my-strategy".

    {
      "projectId": "my-project",
      "strategyId": "my-strategy",
      "environmentId": "development",
      "segmentIds": []
    }
    Example responses

    201 Created​

    The strategy's list of segments was successfully updated.

    403 Forbidden​

    You do not have access to edit this activation strategy.

    404 Not Found​

    No strategy with the provided ID exists.

    Payload structure​

    Use a JSON object with the following properties to update the list of applied segments.

    PropertyTypeRequiredDescriptionExample value
    projectIdstringYesThe ID of the feature toggle's project."my-project"
    strategyIdstringYesThe ID of the strategy."my-strategy"
    environmentIdstringYesThe ID of the environment."development"
    segmentIdslist of segment IDs (numbers)YesThe list of segment IDs to apply to the strategy.[]

    API types​

    This section describes the data objects returned by the endpoints in the segments API. For information on a specific endpoint, refer to its specific description above.

    Segment​

    Example​

    {
      "id": 12054,
      "name": "segment name",
      "description": "segment description",
      "constraints": [],
      "createdBy": "you@example.com",
      "createdAt": "2022-05-23T15:45:22.000Z"
    }

    Description​

    PropertyTypeRequiredDescriptionExample value
    idnumberYesThe segment's ID.546
    namestringYesThe segment's name"my-segment"
    descriptionstringNoAn optional description of the segment."segment description"
    constraintslist of constraint objectsYesThe list of constraint objects in the segment.[]
    createdBystringNoAn identifier for who created the segment."you@example.com"
    createdAttimestamp stringYesThe time when the segment was created. Format: YYYY-MM-DDThh:mm:ss.sTZD"2022-04-23T13:56:24.45+01:00"

    Constraint​

    Example​

    {
        "contextName": "appName",
        "operator": "STR_CONTAINS",
        "values": [],
        "inverted": false,
        "caseInsensitive": false
    }

    Description​

    values and value

    Some constraint operators only support single values. If a constraint uses one of these operators, the payload will contain a value property with the correct value. However, for backwards compatibility reasons, the payload will also contain a values property. If the operator accepts multiple values, the value property will not be present. Visit the strategy constraints documentation for more information on what operators support what number of values.

    PropertyTypeRequiredDescriptionExample value
    contextNamestringYesThe name of the context field targeted by the constraint."myContextField"
    operatorstring, the name of one of the constraint operatorsYesThe operator to apply to the context field."DATE_BEFORE"
    valuesa list of stringsYesThe list of values to apply the constraint operator to.["value a", "value b"]
    valuestringNoThe value to apply the constraint operator to."15"
    invertedbooleanNoWhether the result of the constraint will be negated or not.false
    caseInsensitiveboolean stringNoWhether the constraint operator is case sensitive or not. Only applies to some string-based operators.false

    Activation strategy​

    Example​

    {
      "id": "64fbe72b-d107-4b26-b6b8-4fead08d286c",
      "environment": "development",
      "featureName": "my-feature",
      "projectId": "my-project",
      "strategyName": "flexibleRollout"
    }

    Description​

    PropertyTypeRequiredDescriptionExample value
    idGUID stringNoThe ID of the strategy."64fbe72b-d107-4b26-b6b8-4fead08d286c"
    environmentstringYesThe name of the strategy's environment."development"
    featureNamestringYesThe name of the feature the strategy is applied to."my-feature"
    projectIdstringYesThe name of the current project."my-project"
    strategyNamestringYesThe name of the strategy."flexibleRollout"
    - + \ No newline at end of file diff --git a/reference/api/legacy/unleash/admin/state.html b/reference/api/legacy/unleash/admin/state.html index 3bc0e43580..ff453855dc 100644 --- a/reference/api/legacy/unleash/admin/state.html +++ b/reference/api/legacy/unleash/admin/state.html @@ -20,7 +20,7 @@ - + @@ -31,7 +31,7 @@ You can customize the export with query parameters:

    ParameterDefaultDescription
    formatjsonExport format, either json or yaml
    downloadfalseIf the exported data should be downloaded as a file
    featureTogglestrueInclude feature-toggles in the exported data
    strategiestrueInclude strategies in the exported data

    Example response:

    GET /api/admin/state/export?format=yaml&featureToggles=1&strategies=1

    version: 1
    features:
      - name: Feature.A
        description: lorem ipsum
        enabled: false
        strategies:
          - name: default
            parameters: {}
        variants:
          - name: variant1
            weight: 50
          - name: variant2
            weight: 50
      - name: Feature.B
        description: lorem ipsum
        enabled: true
        strategies:
          - name: ActiveForUserWithId
            parameters:
              userIdList: '123,221,998'
          - name: GradualRolloutRandom
            parameters:
              percentage: '10'
        variants: []
    strategies:
      - name: country
        description: Enable feature for certain countries
        parameters:
          - name: countries
            type: list
            description: List of countries
            required: true

    Import Feature Toggles & Strategies​

    POST: http://unleash.host.com/api/admin/state/import

    You can import feature-toggles and strategies by POSTing to the /api/admin/state/import endpoint.\ You can either send the data as JSON in the POST-body or send a file parameter with multipart/form-data (YAML files are also accepted here).

    Query Paramters

    You should be careful using the drop parameter in production environments.

    Success: 202 Accepted\ Error: 400 Bad Request

    Example body:

    {
      "version": 1,
      "features": [
        {
          "name": "Feature.A",
          "description": "lorem ipsum",
          "enabled": false,
          "strategies": [
            {
              "name": "default",
              "parameters": {}
            }
          ],
          "variants": [
            {
              "name": "variant1",
              "weight": 50
            },
            {
              "name": "variant2",
              "weight": 50
            }
          ]
        },
        {
          "name": "Feature.B",
          "description": "lorem ipsum",
          "enabled": true,
          "strategies": [
            {
              "name": "ActiveForUserWithId",
              "parameters": {
                "userIdList": "123,221,998"
              }
            },
            {
              "name": "GradualRolloutRandom",
              "parameters": {
                "percentage": "10"
              }
            }
          ],
          "variants": []
        }
      ],
      "strategies": [
        {
          "name": "country",
          "description": "Enable feature for certain countries",
          "parameters": [
            {
              "name": "countries",
              "type": "list",
              "description": "List of countries",
              "required": true
            }
          ]
        }
      ]
    }
    - + \ No newline at end of file diff --git a/reference/api/legacy/unleash/admin/strategies.html b/reference/api/legacy/unleash/admin/strategies.html index ae181eaeec..8e83362a80 100644 --- a/reference/api/legacy/unleash/admin/strategies.html +++ b/reference/api/legacy/unleash/admin/strategies.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    /api/admin/strategies

    In order to access the admin API endpoints you need to identify yourself. Unless you're using the none authentication method, you'll need to create an ADMIN token and add an Authorization header using the token.

    Fetch Strategies​

    GET: http://unleash.host.com/api/admin/strategies

    Used to fetch all defined strategies and their defined parameters.

    Response

    {
      "version": 1,
      "strategies": [
        {
          "name": "default",
          "description": "Default on/off strategy.",
          "parameters": []
        },
        {
          "name": "userWithId",
          "description": "Active for userId specified in the comma seperated 'userIds' parameter.",
          "parameters": [
            {
              "name": "userIds",
              "type": "list",
              "description": "List of unique userIds the feature should be active for.",
              "required": true
            }
          ]
        },
        {
          "name": "gradualRollout",
          "description": "Gradual rollout to logged in users",
          "parameters": [
            {
              "name": "percentage",
              "type": "percentage",
              "description": "How many percent should the new feature be active for.",
              "required": false
            },
            {
              "name": "group",
              "type": "string",
              "description": "Group key to use when hasing the userId. Makes sure that the same user get different value for different groups",
              "required": false
            }
          ]
        }
      ]
    }

    Create strategy​

    POST: http://unleash.host.com/api/admin/strategies

    Body

    {
        "name": "gradualRollout",
        "description": "Gradual rollout to logged in users",
        "parameters": [
            {
                "name": "percentage",
                "type": "percentage",
                "description": "How many percent should the new feature be active for.",
                "required": false
            },
            {
                "name": "group",
                "type": "string",
                "description": "Group key to use when hasing the userId. Makes sure that the same user get different value for different groups",
                "required": false
            }
        ]
    },

    Used to create a new Strategy. Name is required and must be unique. It is also required to have a parameters array, but it can be empty.

    Update strategy​

    PUT: http://unleash.host.com/api/admin/strategies/:name

    Body

    {
        "name": "gradualRollout",
        "description": "Gradual rollout to logged in users with updated desc",
        "parameters": [
            {
                "name": "percentage",
                "type": "percentage",
                "description": "How many percent should the new feature be active for.",
                "required": false
            },
            {
                "name": "group",
                "type": "string",
                "description": "Group key to use when hasing the userId. Makes sure that the same user get different value for different groups",
                "required": false
            }
        ]
    },

    Used to update a Strategy definition. Name can't be changed. PS! I can be dangerous to change an implemented strategy as the implementation also might need to be changed

    Deprecate strategy​

    POST: https://unleash.host.com/api/admin/strategies/:name/deprecate

    Used to deprecate a strategy definition. This will set the deprecated flag to true. If the strategy is already deprecated, this will be a noop.

    Errors​

    404 NOT FOUND - if :name does not exist

    Reactivate strategy​

    POST: https://unleash.host.com/api/admin/strategies/:name/reactivate

    Used to reactivate a deprecated strategy definition. This will set the deprecated flag back to false. If the strategy is not deprecated this is a noop and will still return 200.

    Errors​

    404 NOT FOUND - if :name does not exist

    - + \ No newline at end of file diff --git a/reference/api/legacy/unleash/admin/tags.html b/reference/api/legacy/unleash/admin/tags.html index b59e9bb771..fc42733a09 100644 --- a/reference/api/legacy/unleash/admin/tags.html +++ b/reference/api/legacy/unleash/admin/tags.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    /api/admin/tags

    In order to access the admin API endpoints you need to identify yourself. Unless you're using the none authentication method, you'll need to create an ADMIN token and add an Authorization header using the token.

    Create a new tag​

    POST https://unleash.host.com/api/admin/tags

    Creates a new tag without connecting it to any other object, can be helpful to build an autocomplete list.

    Body

    {
      "value": "MyTag",
      "type": "simple"
    }

    Notes​

    • type must exist in tag-types

    List tags​

    GET https://unleash.host.com/api/admin/tags

    This endpoint is the one all admin UIs should use to fetch all available tags from the unleash_server. The response returns all tags.

    Example response:

    {
      "version": 1,
      "tags": [
        {
          "value": "Team-Red",
          "type": "simple"
        },
        {
          "value": "Team-Green",
          "type": "simple"
        },
        {
          "value": "DecemberExperiment",
          "type": "simple"
        },
        {
          "value": "#team-alert-channel",
          "type": "slack"
        }
      ]
    }

    List tags by type​

    GET: https://unleash.host.com/api/admin/tags/:type

    Lists all tags of :type. If none exist, returns the empty list

    Example response to query for https://unleash.host.com/api/admin/tags/simple

    {
      "version": 1,
      "tags": [
        {
          "value": "Team-Red",
          "type": "simple"
        },
        {
          "value": "Team-Green",
          "type": "simple"
        },
        {
          "value": "DecemberExperiment",
          "type": "simple"
        }
      ]
    }

    Get a single tag​

    GET https://unleash.host.com/api/admin/tags/:type/:value

    Gets the tag defined by the type, value tuple

    Delete a tag​

    DELETE https://unleash.host.com/api/admin/tags/:type/:value

    Deletes the tag defined by the type, value tuple; all features tagged with this tag will lose the tag.

    Fetching Tag types​

    GET: https://unleash.host.com/api/admin/tag-types

    Used to fetch all types the server knows about. This endpoint is the one all admin UI should use to fetch all available tag types from the unleash-server. The response returns all tag types. Any server will have at least one configured tag type (the simple type). A tag type will be a map of type, description, icon

    Example response:

    {
      "version": 1,
      "tagTypes": [
        {
          "name": "simple",
          "description": "Arbitrary tags. Used to simplify filtering of features",
          "icon": "#"
        }
      ]
    }

    Get a single tag type​

    GET: https://unleash.host.com/api/admin/tag-types/simple

    Used to fetch details about a specific tag-type. This is mostly provided to make it easy to debug the API and should not be used by the client implementations.

    Example response:

    {
      "version": 1,
      "tagType": {
        "name": "simple",
        "description": "Some description",
        "icon": "Some icon",
        "createdAt": "2021-01-07T10:00:00Z"
      }
    }

    Create a new tag type​

    POST: https://unleash.host.com/api/admin/tag-types

    Used to register a new tag type. This endpoint should be used to inform the server about a new type of tags.

    Body:

    {
      "name": "tagtype",
      "description": "Purpose of tag type",
      "icon": "Either an URL to icon or a simple prefix string for tag"
    }

    Notes:

    • if name is not unique, will return 409 CONFLICT, if you'd like to update an existing tag through admin-api look at Update tag type.

    Returns 201-CREATED if the tag type was created successfully

    Update tag type​

    PUT: https://unleash.host.com/api/admin/tag-types/:typeName

    Body:

    {
      "description": "New description",
      "icon": "New icon"
    }

    Deleting a tag type​

    DELETE: https://unleash.host.com/api/admin/tag-types/:typeName

    Returns 200 if the type was not in use and the type was deleted. If the type was in use, will return a 409 CONFLICT

    - + \ No newline at end of file diff --git a/reference/api/legacy/unleash/admin/user-admin.html b/reference/api/legacy/unleash/admin/user-admin.html index c5a64b3641..07daf64c75 100644 --- a/reference/api/legacy/unleash/admin/user-admin.html +++ b/reference/api/legacy/unleash/admin/user-admin.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    /api/admin/user-admin

    In order to access the admin API endpoints you need to identify yourself. Unless you're using the none authentication method, you'll need to create an ADMIN token and add an Authorization header using the token.

    List all users​

    GET https://unleash.host.com/api/admin/user-admin

    Will return all users and all available root roles for the Unleash instance.

    Body

    {
      "rootRoles": [
        {
          "description": "Users with the root admin role have superuser access to Unleash and can perform any operation within the unleash platform.",
          "id": 1,
          "name": "Admin",
          "project": null,
          "type": "root"
        },
        {
          "description": "Users with this role have access most features in Unleash, but can not manage users and roles in the root scope. If a user with a regular root role creates a project, they will become a project admin and receive superuser rights within the context of that project.",
          "id": 2,
          "name": "Editor",
          "project": null,
          "type": "root"
        },
        {
          "description": "Users with this role can only read root resources in Unleash. They may be added as collaborator to specific projects.",
          "id": 3,
          "name": "Viewer",
          "project": null,
          "type": "root"
        }
      ],
      "users": [
        {
          "createdAt": "2021-05-14T08:56:34.859Z",
          "email": "random-user@getunleash.ai",
          "id": 3,
          "imageUrl": "https://gravatar.com/avatar/3066e45cf3a09d9a4b51e08a3ac20749?size=42&default=retro",
          "inviteLink": "",
          "isAPI": false,
          "loginAttempts": 0,
          "rootRole": 1,
          "seenAt": null
        },
        {
          "createdAt": "2021-05-14T08:58:07.891Z",
          "email": "random-user2@getunleash.ai",
          "id": 4,
          "imageUrl": "https://gravatar.com/avatar/90047524992cd6ae8f66e249a7630d80?size=42&default=retro",
          "inviteLink": "",
          "isAPI": false,
          "loginAttempts": 0,
          "rootRole": 1,
          "seenAt": null
        }
      ]
    }

    Get a single user​

    GET https://unleash.host.com/api/admin/user-admin/:id

    Will return a single user by id.

    Body

    {
      "createdAt": "2021-05-14T08:58:07.891Z",
      "email": "random-user2@getunleash.ai",
      "id": 4,
      "imageUrl": "https://gravatar.com/avatar/90047524992cd6ae8f66e249a7630d80?size=42&default=retro",
      "inviteLink": "",
      "isAPI": false,
      "loginAttempts": 0,
      "rootRole": 1,
      "seenAt": null
    }

    Search for users​

    You can also search for users via the search API. It will preform a simple search based on name and email matching the given query. Requires minimum 2 characters.

    GET http://localhost:4242/api/admin/user-admin/search?q=iv

    Body

    [
      {
        "email": "iva2@some-mail.com",
        "id": 19,
        "imageUrl": "https://gravatar.com/avatar/6c795493735ff1864f17d47ec52cf0ec?size=42&default=retro"
      },
      {
        "email": "ivar@another.com",
        "id": 20,
        "imageUrl": "https://gravatar.com/avatar/f4b3e16a54bfbe824eb814479053bf88?size=42&default=retro"
      }
    ]

    Add a new user​

    POST https://unleash.host.com/api/admin/user-admin

    Creates a new user with the given root role.

    Payload properties

    Requirements

    The payload must contain at least one of the name and email properties, though which one is up to you. For the user to be able to log in to the system, the user must have an email.

    Property nameRequiredDescriptionExample value(s)
    emailNoThe user's email address. Must be provided if username is not provided."user@getunleash.io"
    usernameNoThe user's username. Must be provided if email is not provided."Baz the Beholder"
    rootRoleYesThe role to assign to the user. Can be either the role's ID or its unique name.2, "Editor"
    sendEmailNoWhether to send a welcome email with a login link to the user or not. Defaults to true.false
    nameNoThe user's name (not the user's username)."Sam Seawright"

    Body

    {
      "email": "some-email@getunleash.io",
      "username": "Baz the Beholder",
      "rootRole": "Editor",
      "sendEmail": true
    }

    Return values:​

    201: Created

    {
      "createdAt": "2021-05-18T10:28:23.067Z",
      "email": "some-email@getunleash.io",
      "emailSent": true,
      "id": 1337,
      "imageUrl": "https://gravatar.com/avatar/222f2ab70c039dda12e3d11acdcebd02?size=42&default=retro",
      "inviteLink": "http://localhost:4242/new-user?token=123",
      "isAPI": false,
      "loginAttempts": 0,
      "name": "Some Name",
      "rootRole": 2,
      "seenAt": null
    }

    400: Bad request

    [
      {
        "msg": "User already exists"
      }
    ]

    400: Bad request

    [
      {
        "msg": "You must specify username or email"
      }
    ]

    Update a user​

    PUT https://unleash.host.com/api/admin/user-admin/:userId

    Updates user with new fields

    Body

    {
      "email": "some-email@getunleash.io",
      "name": "Some Name",
      "rootRole": 2
    }

    Notes

    • userId is required as a url path parameter.
    • All fields are optional. Only provided fields are updated.
    • Note that earlier versions of Unleash required either name or email to be set.

    Delete a user​

    DELETE https://unleash.host.com/api/admin/user-admin/:userId

    Deletes the user with the given userId.

    Possible return values:

    • 200: OK - user was deleted
    • 404: NOT FOUND - No user with the provided userId was found

    Change password for a user​

    POST https://unleash.host.com/api/admin/user-admin/:userId/change-password

    Body

    {
      "password": "k!5As3HquUrQ"
    }

    Return values:

    • 200 OK: Password was changed.
    • 400 Bad Request: Password was not changed. Unleash requires a strong password.
      • This means
        • minimum 10 characters long
        • contains at least one uppercase letter
        • contains at least one number
        • contains at least one special character (symbol)
    • Please see in the response body on how to improve the password.

    Validate password for a user​

    You can use this endpoint to validate the strength of a given password. Unleash requires a strong password.

    • This means
      • minimum 10 characters long
      • contains at least one uppercase letter
      • contains at least one number
      • contains at least one special character (symbol)

    http POST http://localhost:4242/api/admin/user-admin/validate-password

    Body

    {
      "password": "some-simple"
    }
    • 200 OK: Password is strong enough for Unleash.
    • 400 Bad Request: Unleash requires a stronger password. Please see in the response body on how to improve the password.
    - + \ No newline at end of file diff --git a/reference/api/legacy/unleash/basic-auth.html b/reference/api/legacy/unleash/basic-auth.html index 308d61e2be..9126fe97e3 100644 --- a/reference/api/legacy/unleash/basic-auth.html +++ b/reference/api/legacy/unleash/basic-auth.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Basic auth

    When using the insecure authentication method, identifying using basic auth against the API is enough. Since the insecure method doesn't require a password, it is enough to define the username when making HTTP requests.

    With curl​

    Add the -u myemail@test.com flag to your curl command.

    With wget​

    Add the --user=myemail@test.com flag to your wget command.

    - + \ No newline at end of file diff --git a/reference/api/legacy/unleash/client/features.html b/reference/api/legacy/unleash/client/features.html index 9e37be6d31..659786d656 100644 --- a/reference/api/legacy/unleash/client/features.html +++ b/reference/api/legacy/unleash/client/features.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    /api/client/features

    In order to access the client API endpoints you need to identify yourself. Unless you're using the none authentication method, you'll need to create a CLIENT token and add an Authorization header using the token.

    Fetching Feature Toggles​

    GET: http://unleash.host.com/api/client/features

    HEADERS:

    • UNLEASH-APPNAME: appName
    • UNLEASH-INSTANCEID: instanceId

    This endpoint is the one all clients should use to fetch all available feature toggles from the unleash-server. The response returns all active feature toggles and their current strategy configuration. A feature toggle will have at least one configured strategy. A strategy will have a name and parameters map.

    Note: Clients should prefer the strategies property. Legacy properties (strategy & parameters) will be kept until version 2 of the format.

    This endpoint should never return anything besides a valid 20X or 304-response. It will also include an Etag-header. The value of this header can be used by clients as the value of the If-None-Match-header in the request to prevent a data transfer if the client already has the latest response locally.

    Example response:

    {
      "version": 1,
      "features": [
        {
          "name": "Feature.A",
          "type": "release",
          "enabled": false,
          "stale": false,
          "strategies": [
            {
              "name": "default",
              "parameters": {}
            }
          ],
          "strategy": "default",
          "parameters": {}
        },
        {
          "name": "Feature.B",
          "type": "killswitch",
          "enabled": true,
          "stale": false,
          "strategies": [
            {
              "name": "ActiveForUserWithId",
              "parameters": {
                "userIdList": "123,221,998"
              }
            },
            {
              "name": "GradualRolloutRandom",
              "parameters": {
                "percentage": "10"
              }
            }
          ],
          "strategy": "ActiveForUserWithId",
          "parameters": {
            "userIdList": "123,221,998"
          }
        }
      ]
    }

    Filter feature toggles​

    Supports three params for now

    • tag - filters for features tagged with tag
    • project - filters for features belonging to project
    • namePrefix - filters for features beginning with prefix

    For tag and project performs OR filtering if multiple arguments

    To filter for any feature tagged with a simple tag with value taga or a simple tag with value tagb use

    GET https://unleash.host.com/api/client/features?tag[]=simple:taga&tag[]simple:tagb

    To filter for any feature belonging to project myproject use

    GET https://unleash.host.com/api/client/features?project=myproject

    Response format is the same as api/client/features

    Get specific feature toggle​

    GET: http://unleash.host.com/api/client/features/:featureName

    Used to fetch details about a specific feature toggle. This is mainly provided to make it easy to debug the API and should not be used by the client implementations.

    Notice: You will not get a version property when fetching a specific feature toggle by name.

    {
      "name": "Feature.A",
      "type": "release",
      "enabled": false,
      "stale": false,
      "strategies": [
        {
          "name": "default",
          "parameters": {}
        }
      ],
      "strategy": "default",
      "parameters": {}
    }

    Strategy Constraints​

    Availability

    Before Unleash 4.16, strategy constraints were only available to Unleash Pro and Enterprise users. From 4.16 onwards, they're available to everyone.

    Strategy definitions may also contain a constraints property. Strategy constraints is a feature in Unleash which work on context fields, which is defined as part of the Unleash Context. The purpose is to define a set of rules where all needs to be satisfied in order for the activation strategy to evaluate to true. A high level description of it is available online.

    Example response:

    The example shows strategy constraints in action. Constraints is a new field on the strategy-object. It is a list of constraints that need to be satisfied.

    In the example environment needs to be production AND userId must be either 123 OR 44 in order for the Unleash Client to evaluate the strategy, which in this scenario is “default” and will always evaluate to true.

    {
      "type": "release",
      "enabled": true,
      "stale": false,
      "name": "Demo",
      "strategies": [
        {
          "constraints": [
            {
              "contextName": "environment",
              "operator": "IN",
              "values": ["production"]
            },
            {
              "contextName": "userId",
              "operator": "IN",
              "values": ["123", "44"]
            }
          ],
          "name": "default",
          "parameters": {}
        }
      ]
    }
    • contextName - is the name of the field to look up on the unleash context.
    • values - is a list of values (string).
    • operator - is the logical action to take on the values Supported operator are:
      • IN - constraint is satisfied if one of the values in the list matches the value for this context field in the context.
      • NOT_IN - constraint is satisfied if NONE of the values is the list matches the value for this field in the context.

    Variants​

    All feature toggles can also take an array of variants. You can read more about feature toggle variants.

    {
      "version": 1,
      "features": [
        {
          "name": "Demo",
          "type": "operational",
          "enabled": true,
          "stale": false,
          "strategies": [
            {
              "name": "default"
            }
          ],
          "variants": [
            {
              "name": "red",
              "weight": 500,
              "weightType": "variable",
              "payload": {
                "type": "string",
                "value": "something"
              },
              "overrides": [
                {
                  "contextName": "userId",
                  "values": ["123"]
                }
              ]
            },
            {
              "name": "blue",
              "weight": 500,
              "overrides": [],
              "weightType": "variable"
            }
          ]
        }
      ]
    }
    • payload - an optional object representing a payload to the variant. Takes two properties if present type and value.
    • overrides - an optional array of overrides. If any context field matches any of the the defined overrides it means that the variant should be selected.
    - + \ No newline at end of file diff --git a/reference/api/legacy/unleash/client/metrics.html b/reference/api/legacy/unleash/client/metrics.html index 9d8ae3d14a..0c3995e3cc 100644 --- a/reference/api/legacy/unleash/client/metrics.html +++ b/reference/api/legacy/unleash/client/metrics.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    /api/client/metrics

    In order to access the client API endpoints you need to identify yourself. Unless you're using the none authentication method, you'll need to create a CLIENT token and add an Authorization header using the token.

    Send metrics​

    POST: http://unleash.host.com/api/client/metrics

    Register a metrics payload with a timed bucket.

    {
      "appName": "appName",
      "instanceId": "instanceId",
      "bucket": {
        "start": "2016-11-03T07:16:43.572Z",
        "stop": "2016-11-03T07:16:53.572Z",
        "toggles": {
          "toggle-name-1": {
            "yes": 123,
            "no": 321
          },
          "toggle-name-2": {
            "yes": 111,
            "no": 0
          }
        }
      }
    }
    - + \ No newline at end of file diff --git a/reference/api/legacy/unleash/client/register.html b/reference/api/legacy/unleash/client/register.html index fad4a30670..6fcb1aa902 100644 --- a/reference/api/legacy/unleash/client/register.html +++ b/reference/api/legacy/unleash/client/register.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    /api/client/register

    In order to access the client API endpoints you need to identify yourself. Unless you're using the none authentication method, you'll need to create a CLIENT token and add an Authorization header using the token.

    Client registration​

    POST: http://unleash.host.com/api/client/register

    Registers a client instance with the unleash server. The client should send all fields specified.

    {
      "appName": "appName",
      "instanceId": "instanceId",
      "sdkVersion": "unleash-client-java:2.2.0",
      "strategies": ["default", "some-strategy-1"],
      "started": "2016-11-03T07:16:43.572Z",
      "interval": 10000
    }

    Fields:

    • appName - Name of the application seen by unleash-server
    • instanceId - Instance id for this application (typically hostname, podId or similar)
    • sdkVersion - Optional field that describes the sdk version (name:version)
    • strategies - List of strategies implemented by this application
    • started - When this client started. Should be reported as ISO8601 time.
    • interval - At which interval, in milliseconds, will this client be expected to send metrics
    - + \ No newline at end of file diff --git a/reference/api/legacy/unleash/internal/health.html b/reference/api/legacy/unleash/internal/health.html index 88517fbeed..551f9c5004 100644 --- a/reference/api/legacy/unleash/internal/health.html +++ b/reference/api/legacy/unleash/internal/health.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Health API

    GET http://unleash.host.com/health

    Used to check the health of the running Unleash instance. This endpoint has two possible responses:

    Status: 200

    {
      "health": "GOOD"
    }

    This response means everything is OK. Unleash is able to talk to the PostgreSQL

    Status: 500

    {
      "health": "BAD"
    }

    This response indicates that Unleash is not able to talk to PostgreSQL and will not be able to serve requests.

    - + \ No newline at end of file diff --git a/reference/api/legacy/unleash/internal/prometheus.html b/reference/api/legacy/unleash/internal/prometheus.html index f78182c5a5..33865b633d 100644 --- a/reference/api/legacy/unleash/internal/prometheus.html +++ b/reference/api/legacy/unleash/internal/prometheus.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Internal Backstage API

    GET http://unleash.host.com/internal-backstage/prometheus

    Unleash uses Prometheus internally to collect metrics. By default, the metrics are available at /internal-backstage/prometheus. You can disable this endpoint by setting the serverMetrics option to false.

    Note that it's not recommended to expose Prometheus metrics to the public as of the Prometheus pentest-report issue PRM-01-002. Thus, if you want to keep metrics enabled, you should block all external access to /internal-backstage/* on the network layer to keep your instance secure.

    Read more about Prometheus

    Annotations​

    Unleash will automatically count all updates for all toggles under the metric name feature_toggle_update_total, and the toggle name is will be set as a label value. This information can be used to create annotations in grafana for everytime a feature toggle is changed.

    You can use this query in grafana to achieve this:

    delta(feature_toggle_update_total{toggle="Demo"}[1m]) != bool 0

    Another useful counter is the feature_toggle_usage_total which will give you the numbers for how many times a feature toggle has been evaluated to active or not.

    - + \ No newline at end of file diff --git a/reference/api/unleash.html b/reference/api/unleash.html index 473cd903e5..5f55a7d78e 100644 --- a/reference/api/unleash.html +++ b/reference/api/unleash.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Unleash Server APIs

    Generated API docs based on the Unleash OpenAPI schema.

    - + \ No newline at end of file diff --git a/reference/api/unleash/add-access-to-project.html b/reference/api/unleash/add-access-to-project.html index 87469bf8c3..d5193ce2a1 100644 --- a/reference/api/unleash/add-access-to-project.html +++ b/reference/api/unleash/add-access-to-project.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Configure project access

    POST /api/admin/projects/:projectId/access

    Configure project access for groups and single users. The provided users and groups will be given the roles specified in the payload.

    Request​

    Path Parameters

    • projectId string required

    Body

    required

    projectAddAccessSchema

    • roles integer[] required

      A list of role IDs

    • groups integer[] required

      A list of group IDs

    • users integer[] required

      A list of user IDs

    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/add-change-request-comment.html b/reference/api/unleash/add-change-request-comment.html index 6bc569465b..c2cb8b5527 100644 --- a/reference/api/unleash/add-change-request-comment.html +++ b/reference/api/unleash/add-change-request-comment.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    This endpoint will add a comment to a change request

    POST /api/admin/projects/:projectId/change-requests/:id/comments

    This endpoint will add a comment to a change request for the user making the request.

    Request​

    Path Parameters

    • projectId string required
    • id string required

    Body

    required

    changeRequestAddCommentSchema

    • text string required

      The content of the comment.

    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/add-default-strategy-to-project-environment.html b/reference/api/unleash/add-default-strategy-to-project-environment.html index a7d09ccd6c..8589bf2289 100644 --- a/reference/api/unleash/add-default-strategy-to-project-environment.html +++ b/reference/api/unleash/add-default-strategy-to-project-environment.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Set environment-default strategy

    POST /api/admin/projects/:projectId/environments/:environment/default-strategy

    Sets a default strategy for this environment. Unleash will use this strategy by default when enabling a toggle. Use the wild card "*" for :environment to add to all environments.

    Request​

    Path Parameters

    • projectId string required
    • environment string required

    Body

    required

    createFeatureStrategySchema

    • name string required

      The name of the strategy type

    • title string nullable

      A descriptive title for the strategy

    • disabled boolean nullable

      A toggle to disable the strategy. defaults to false. Disabled strategies are not evaluated or returned to the SDKs

    • sortOrder number

      The order of the strategy in the list

    • constraints object[]

      A list of the constraints attached to the strategy. See https://docs.getunleash.io/reference/strategy-constraints

    • Array [
    • contextName string required

      The name of the context field that this constraint should apply to.

    • operator string required

      Possible values: [NOT_IN, IN, STR_ENDS_WITH, STR_STARTS_WITH, STR_CONTAINS, NUM_EQ, NUM_GT, NUM_GTE, NUM_LT, NUM_LTE, DATE_AFTER, DATE_BEFORE, SEMVER_EQ, SEMVER_GT, SEMVER_LT]

      The operator to use when evaluating this constraint. For more information about the various operators, refer to the strategy constraint operator documentation.

    • caseInsensitive boolean

      Default value: false

      Whether the operator should be case sensitive or not. Defaults to false (being case sensitive).

    • inverted boolean

      Default value: false

      Whether the result should be negated or not. If true, will turn a true result into a false result and vice versa.

    • values string[]

      The context values that should be used for constraint evaluation. Use this property instead of value for properties that accept multiple values.

    • value string

      The context value that should be used for constraint evaluation. Use this property instead of values for properties that only accept single values.

    • ]
    • variants object[]

      Strategy level variants

    • Array [
    • name string required

      The variant name. Must be unique for this feature toggle

    • weight integer required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is an integer between 0 and 1000. See the section on variant weights for more information

    • weightType string required

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000. Refer to the variant weight documentation.

    • stickiness string required

      The stickiness to use for distribution of this variant. Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • ]
    • parameters object

      A list of parameters for a strategy

    • property name* string
    • segments number[]

      Ids of segments to use for this strategy

    Responses

    createFeatureStrategySchema

    Schema
    • name string required

      The name of the strategy type

    • title string nullable

      A descriptive title for the strategy

    • disabled boolean nullable

      A toggle to disable the strategy. defaults to false. Disabled strategies are not evaluated or returned to the SDKs

    • sortOrder number

      The order of the strategy in the list

    • constraints object[]

      A list of the constraints attached to the strategy. See https://docs.getunleash.io/reference/strategy-constraints

    • Array [
    • contextName string required

      The name of the context field that this constraint should apply to.

    • operator string required

      Possible values: [NOT_IN, IN, STR_ENDS_WITH, STR_STARTS_WITH, STR_CONTAINS, NUM_EQ, NUM_GT, NUM_GTE, NUM_LT, NUM_LTE, DATE_AFTER, DATE_BEFORE, SEMVER_EQ, SEMVER_GT, SEMVER_LT]

      The operator to use when evaluating this constraint. For more information about the various operators, refer to the strategy constraint operator documentation.

    • caseInsensitive boolean

      Default value: false

      Whether the operator should be case sensitive or not. Defaults to false (being case sensitive).

    • inverted boolean

      Default value: false

      Whether the result should be negated or not. If true, will turn a true result into a false result and vice versa.

    • values string[]

      The context values that should be used for constraint evaluation. Use this property instead of value for properties that accept multiple values.

    • value string

      The context value that should be used for constraint evaluation. Use this property instead of values for properties that only accept single values.

    • ]
    • variants object[]

      Strategy level variants

    • Array [
    • name string required

      The variant name. Must be unique for this feature toggle

    • weight integer required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is an integer between 0 and 1000. See the section on variant weights for more information

    • weightType string required

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000. Refer to the variant weight documentation.

    • stickiness string required

      The stickiness to use for distribution of this variant. Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • ]
    • parameters object

      A list of parameters for a strategy

    • property name* string
    • segments number[]

      Ids of segments to use for this strategy

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/add-environment-to-project.html b/reference/api/unleash/add-environment-to-project.html index 602b832939..d8a92a8f46 100644 --- a/reference/api/unleash/add-environment-to-project.html +++ b/reference/api/unleash/add-environment-to-project.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Add an environment to a project.

    POST /api/admin/projects/:projectId/environments

    This endpoint adds the provided environment to the specified project, with optional support for enabling and disabling change requests for the environment and project.

    Request​

    Path Parameters

    • projectId string required

    Body

    required

    projectEnvironmentSchema

    • environment string required

      The environment to add to the project

    • changeRequestsEnabled boolean

      Whether change requests should be enabled or for this environment on the project or not

    • defaultStrategy object

      A default strategy to create for this environment on the project.

    • name string required

      The name of the strategy type

    • title string nullable

      A descriptive title for the strategy

    • disabled boolean nullable

      A toggle to disable the strategy. defaults to false. Disabled strategies are not evaluated or returned to the SDKs

    • sortOrder number

      The order of the strategy in the list

    • constraints object[]

      A list of the constraints attached to the strategy. See https://docs.getunleash.io/reference/strategy-constraints

    • Array [
    • contextName string required

      The name of the context field that this constraint should apply to.

    • operator string required

      Possible values: [NOT_IN, IN, STR_ENDS_WITH, STR_STARTS_WITH, STR_CONTAINS, NUM_EQ, NUM_GT, NUM_GTE, NUM_LT, NUM_LTE, DATE_AFTER, DATE_BEFORE, SEMVER_EQ, SEMVER_GT, SEMVER_LT]

      The operator to use when evaluating this constraint. For more information about the various operators, refer to the strategy constraint operator documentation.

    • caseInsensitive boolean

      Default value: false

      Whether the operator should be case sensitive or not. Defaults to false (being case sensitive).

    • inverted boolean

      Default value: false

      Whether the result should be negated or not. If true, will turn a true result into a false result and vice versa.

    • values string[]

      The context values that should be used for constraint evaluation. Use this property instead of value for properties that accept multiple values.

    • value string

      The context value that should be used for constraint evaluation. Use this property instead of values for properties that only accept single values.

    • ]
    • variants object[]

      Strategy level variants

    • Array [
    • name string required

      The variant name. Must be unique for this feature toggle

    • weight integer required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is an integer between 0 and 1000. See the section on variant weights for more information

    • weightType string required

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000. Refer to the variant weight documentation.

    • stickiness string required

      The stickiness to use for distribution of this variant. Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • ]
    • parameters object

      A list of parameters for a strategy

    • property name* string
    • segments number[]

      Ids of segments to use for this strategy

    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/add-favorite-feature.html b/reference/api/unleash/add-favorite-feature.html index 86e2a7e538..6ea0ff99c6 100644 --- a/reference/api/unleash/add-favorite-feature.html +++ b/reference/api/unleash/add-favorite-feature.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Add feature to favorites

    POST /api/admin/projects/:projectId/features/:featureName/favorites

    This endpoint marks the feature in the url as favorite

    Request​

    Path Parameters

    • projectId string required
    • featureName string required
    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/add-favorite-project.html b/reference/api/unleash/add-favorite-project.html index 3413db0199..1bf0b055af 100644 --- a/reference/api/unleash/add-favorite-project.html +++ b/reference/api/unleash/add-favorite-project.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Add project to favorites

    POST /api/admin/projects/:projectId/favorites

    This endpoint marks the project in the url as favorite

    Request​

    Path Parameters

    • projectId string required
    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/add-feature-dependency.html b/reference/api/unleash/add-feature-dependency.html index 97d98de509..c28d7252e7 100644 --- a/reference/api/unleash/add-feature-dependency.html +++ b/reference/api/unleash/add-feature-dependency.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Add a feature dependency.

    POST /api/admin/projects/:projectId/features/:child/dependencies

    Add a dependency to a parent feature. Each environment will resolve corresponding dependency independently.

    Request​

    Path Parameters

    • projectId string required
    • child string required

    Body

    required

    createDependentFeatureSchema

    • feature string required

      The name of the feature we depend on.

    • enabled boolean

      Whether the parent feature should be enabled. When false variants are ignored. true by default.

    • variants string[]

      The list of variants the parent feature should resolve to. Leave empty when you only want to check the enabled status.

    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/add-feature-strategy.html b/reference/api/unleash/add-feature-strategy.html index 53a3f5282a..0c8af2cb76 100644 --- a/reference/api/unleash/add-feature-strategy.html +++ b/reference/api/unleash/add-feature-strategy.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Add a strategy to a feature toggle

    POST /api/admin/projects/:projectId/features/:featureName/environments/:environment/strategies

    Add a strategy to a feature toggle in the specified environment.

    Request​

    Path Parameters

    • projectId string required
    • featureName string required
    • environment string required

    Body

    required

    createFeatureStrategySchema

    • name string required

      The name of the strategy type

    • title string nullable

      A descriptive title for the strategy

    • disabled boolean nullable

      A toggle to disable the strategy. defaults to false. Disabled strategies are not evaluated or returned to the SDKs

    • sortOrder number

      The order of the strategy in the list

    • constraints object[]

      A list of the constraints attached to the strategy. See https://docs.getunleash.io/reference/strategy-constraints

    • Array [
    • contextName string required

      The name of the context field that this constraint should apply to.

    • operator string required

      Possible values: [NOT_IN, IN, STR_ENDS_WITH, STR_STARTS_WITH, STR_CONTAINS, NUM_EQ, NUM_GT, NUM_GTE, NUM_LT, NUM_LTE, DATE_AFTER, DATE_BEFORE, SEMVER_EQ, SEMVER_GT, SEMVER_LT]

      The operator to use when evaluating this constraint. For more information about the various operators, refer to the strategy constraint operator documentation.

    • caseInsensitive boolean

      Default value: false

      Whether the operator should be case sensitive or not. Defaults to false (being case sensitive).

    • inverted boolean

      Default value: false

      Whether the result should be negated or not. If true, will turn a true result into a false result and vice versa.

    • values string[]

      The context values that should be used for constraint evaluation. Use this property instead of value for properties that accept multiple values.

    • value string

      The context value that should be used for constraint evaluation. Use this property instead of values for properties that only accept single values.

    • ]
    • variants object[]

      Strategy level variants

    • Array [
    • name string required

      The variant name. Must be unique for this feature toggle

    • weight integer required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is an integer between 0 and 1000. See the section on variant weights for more information

    • weightType string required

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000. Refer to the variant weight documentation.

    • stickiness string required

      The stickiness to use for distribution of this variant. Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • ]
    • parameters object

      A list of parameters for a strategy

    • property name* string
    • segments number[]

      Ids of segments to use for this strategy

    Responses

    featureStrategySchema

    Schema
    • id string

      A uuid for the feature strategy

    • name string required

      The name or type of strategy

    • title string nullable

      A descriptive title for the strategy

    • disabled boolean nullable

      A toggle to disable the strategy. defaults to false. Disabled strategies are not evaluated or returned to the SDKs

    • featureName string

      The name or feature the strategy is attached to

    • sortOrder number

      The order of the strategy in the list

    • segments number[]

      A list of segment ids attached to the strategy

    • constraints object[]

      A list of the constraints attached to the strategy. See https://docs.getunleash.io/reference/strategy-constraints

    • Array [
    • contextName string required

      The name of the context field that this constraint should apply to.

    • operator string required

      Possible values: [NOT_IN, IN, STR_ENDS_WITH, STR_STARTS_WITH, STR_CONTAINS, NUM_EQ, NUM_GT, NUM_GTE, NUM_LT, NUM_LTE, DATE_AFTER, DATE_BEFORE, SEMVER_EQ, SEMVER_GT, SEMVER_LT]

      The operator to use when evaluating this constraint. For more information about the various operators, refer to the strategy constraint operator documentation.

    • caseInsensitive boolean

      Default value: false

      Whether the operator should be case sensitive or not. Defaults to false (being case sensitive).

    • inverted boolean

      Default value: false

      Whether the result should be negated or not. If true, will turn a true result into a false result and vice versa.

    • values string[]

      The context values that should be used for constraint evaluation. Use this property instead of value for properties that accept multiple values.

    • value string

      The context value that should be used for constraint evaluation. Use this property instead of values for properties that only accept single values.

    • ]
    • variants object[]

      Strategy level variants

    • Array [
    • name string required

      The variant name. Must be unique for this feature toggle

    • weight integer required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is an integer between 0 and 1000. See the section on variant weights for more information

    • weightType string required

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000. Refer to the variant weight documentation.

    • stickiness string required

      The stickiness to use for distribution of this variant. Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • ]
    • parameters object

      A list of parameters for a strategy

    • property name* string
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/add-public-signup-token-user.html b/reference/api/unleash/add-public-signup-token-user.html index 37afee4fe5..51d15ff97b 100644 --- a/reference/api/unleash/add-public-signup-token-user.html +++ b/reference/api/unleash/add-public-signup-token-user.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Add a user via a signup token

    POST /invite/:token/signup

    Create a user with the viewer root role and link them to the provided signup token

    Request​

    Path Parameters

    • token string required

    Body

    required

    createInvitedUserSchema

    • username string

      The user's username. Must be unique if provided.

    • email string required

      The invited user's email address

    • name string required

      The user's name

    • password string required

      The user's password

    Responses

    userSchema

    Schema
    • id integer required

      The user id

    • isAPI boolean deprecated

      (Deprecated): Used internally to know which operations the user should be allowed to perform

    • name string nullable

      Name of the user

    • email string

      Email of the user

    • username string nullable

      A unique username for the user

    • imageUrl string

      URL used for the userprofile image

    • inviteLink string

      If the user is actively inviting other users, this is the link that can be shared with other users

    • loginAttempts integer

      How many unsuccessful attempts at logging in has the user made

    • emailSent boolean

      Is the welcome email sent to the user or not

    • rootRole integer

      Which root role this user is assigned

    • seenAt date-time nullable

      The last time this user logged in

    • createdAt date-time

      The user was created at this time

    • accountType string

      A user is either an actual User or a Service Account

    • permissions string[]

      Deprecated

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/add-role-access-to-project.html b/reference/api/unleash/add-role-access-to-project.html index 91283a8cbe..730c737730 100644 --- a/reference/api/unleash/add-role-access-to-project.html +++ b/reference/api/unleash/add-role-access-to-project.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Configure project role access

    POST /api/admin/projects/:projectId/role/:roleId/access
    deprecated

    This endpoint has been deprecated and may be removed in future versions of the API.

    Configure project access for groups and single users. The provided users and groups will be given the role specified in the URL parameters. This endpoint is deprecated. Use /:projectId/access instead.

    Request​

    Path Parameters

    • projectId string required
    • roleId string required

    Body

    required

    projectAddRoleAccessSchema

    • groups object[]required

      A list of groups IDs

    • Array [
    • id integer required

      A group ID

    • ]
    • users object[]required

      A list of user IDs

    • Array [
    • id integer required

      A user ID

    • ]
    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/add-role-to-user.html b/reference/api/unleash/add-role-to-user.html index c4379a00bc..51dbf31204 100644 --- a/reference/api/unleash/add-role-to-user.html +++ b/reference/api/unleash/add-role-to-user.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Add user to project

    POST /api/admin/projects/:projectId/users/:userId/roles/:roleId
    deprecated

    This endpoint has been deprecated and may be removed in future versions of the API.

    Adds the specified user to a project with the provided role. This endpoint is deprecated. Use /:projectId/access instead.

    Request​

    Path Parameters

    • projectId string required
    • userId string required
    • roleId string required
    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/add-tag-to-features.html b/reference/api/unleash/add-tag-to-features.html index 83533cd7b3..82b3e02958 100644 --- a/reference/api/unleash/add-tag-to-features.html +++ b/reference/api/unleash/add-tag-to-features.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Adds a tag to the specified features

    PUT /api/admin/projects/:projectId/tags

    Add a tag to a list of features. Create tags if needed.

    Request​

    Path Parameters

    • projectId string required

    Body

    required

    tagsBulkAddSchema

    • features string[] required

      Possible values: non-empty

      The list of features that will be affected by the tag changes.

    • tags objectrequired

      The tag changes to be applied to the features.

    • addedTags object[]required

      Tags to add to the feature.

    • Array [
    • value string required

      Possible values: >= 2 characters and <= 50 characters

      The value of the tag

    • type string required

      Possible values: >= 2 characters and <= 50 characters

      Default value: simple

      The type of the tag

    • ]
    • removedTags object[]required

      Tags to remove from the feature.

    • Array [
    • value string required

      Possible values: >= 2 characters and <= 50 characters

      The value of the tag

    • type string required

      Possible values: >= 2 characters and <= 50 characters

      Default value: simple

      The type of the tag

    • ]
    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/add-tag.html b/reference/api/unleash/add-tag.html index 96db16ed64..8a2912f91c 100644 --- a/reference/api/unleash/add-tag.html +++ b/reference/api/unleash/add-tag.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Adds a tag to a feature.

    POST /api/admin/features/:featureName/tags

    Adds a tag to a feature if the feature and tag type exist in the system. The operation is idempotent, so adding an existing tag will result in a successful response.

    Request​

    Path Parameters

    • featureName string required

    Body

    required

    tagSchema

    • value string required

      Possible values: >= 2 characters and <= 50 characters

      The value of the tag

    • type string required

      Possible values: >= 2 characters and <= 50 characters

      Default value: simple

      The type of the tag

    Responses

    The resource was successfully created.

    Response Headers
    • location string

      The location of the newly created resource.

    Schema
    • value string required

      Possible values: >= 2 characters and <= 50 characters

      The value of the tag

    • type string required

      Possible values: >= 2 characters and <= 50 characters

      Default value: simple

      The type of the tag

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/addons.html b/reference/api/unleash/addons.html index 6dfa03ac71..4cd439c5c5 100644 --- a/reference/api/unleash/addons.html +++ b/reference/api/unleash/addons.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Addons

    Create, update, and delete Unleash addons.

    - + \ No newline at end of file diff --git a/reference/api/unleash/admin-ui.html b/reference/api/unleash/admin-ui.html index 2682ddfc97..db0940f467 100644 --- a/reference/api/unleash/admin-ui.html +++ b/reference/api/unleash/admin-ui.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Admin UI

    Configuration for the Unleash Admin UI. These endpoints should not be relied upon and can change at any point without prior notice.

    - + \ No newline at end of file diff --git a/reference/api/unleash/api-tokens.html b/reference/api/unleash/api-tokens.html index 55a2fa5c46..90017dce00 100644 --- a/reference/api/unleash/api-tokens.html +++ b/reference/api/unleash/api-tokens.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    API tokens

    Create, update, and delete Unleash API tokens.

    - + \ No newline at end of file diff --git a/reference/api/unleash/archive-feature.html b/reference/api/unleash/archive-feature.html index ac382f5f87..ab3a7f83b1 100644 --- a/reference/api/unleash/archive-feature.html +++ b/reference/api/unleash/archive-feature.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Archive a feature toggle

    DELETE /api/admin/projects/:projectId/features/:featureName

    This endpoint archives the specified feature if the feature belongs to the specified project.

    Request​

    Path Parameters

    • projectId string required
    • featureName string required
    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/archive-features.html b/reference/api/unleash/archive-features.html index b789ea5c7b..8c239a062d 100644 --- a/reference/api/unleash/archive-features.html +++ b/reference/api/unleash/archive-features.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Archives a list of features

    POST /api/admin/projects/:projectId/archive

    This endpoint archives the specified features. Any features that are already archived or that don't exist are ignored. All existing features (whether already archived or not) that are provided must belong to the specified project.

    Request​

    Path Parameters

    • projectId string required

    Body

    required

    batchFeaturesSchema

    • features string[] required

      List of feature toggle names

    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/archive.html b/reference/api/unleash/archive.html index d0272bd709..835a465e17 100644 --- a/reference/api/unleash/archive.html +++ b/reference/api/unleash/archive.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Archive

    Revive or permanently delete archived feature toggles.

    - + \ No newline at end of file diff --git a/reference/api/unleash/auth.html b/reference/api/unleash/auth.html index 38e212586a..8fe6a3cb07 100644 --- a/reference/api/unleash/auth.html +++ b/reference/api/unleash/auth.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Auth

    Manage logins, passwords, etc.

    - + \ No newline at end of file diff --git a/reference/api/unleash/banners.html b/reference/api/unleash/banners.html index 4975844a68..3be5ab654a 100644 --- a/reference/api/unleash/banners.html +++ b/reference/api/unleash/banners.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content
    - + \ No newline at end of file diff --git a/reference/api/unleash/bulk-metrics.html b/reference/api/unleash/bulk-metrics.html index ebc041c53d..07bb4de354 100644 --- a/reference/api/unleash/bulk-metrics.html +++ b/reference/api/unleash/bulk-metrics.html @@ -20,7 +20,7 @@ - + @@ -29,7 +29,7 @@
    Skip to main content

    Send metrics from Edge

    POST /edge/metrics

    This operation accepts batched metrics from Edge. Metrics will be inserted into Unleash's metrics storage

    Request​

    Body

    required

    bulkMetricsSchema

    • applications object[]required

      A list of applications registered by an Unleash SDK

    • Array [
    • connectVia object[]

      A list of applications this app registration has been registered through. If connected directly to Unleash, this is an empty list. This can be used in later visualizations to tell how many levels of proxy or Edge instances our SDKs have connected through

    • Array [
    • appName string required
    • instanceId string required
    • ]
    • appName string required

      The name of the application that is evaluating toggles

    • environment string required

      Which environment the application is running in

    • instanceId string required

      A (somewhat) unique identifier for the application

    • interval number

      How often (in seconds) the application refreshes its features

    • started object

      The application started at

      oneOf
    • string date-time

      An RFC-3339-compliant timestamp.

    • strategies string[]

      Enabled strategies in the application

    • sdkVersion string

      The version the sdk is running. Typically :

    • ]
    • metrics object[]required

      a list of client usage metrics registered by downstream providers. (Typically Unleash Edge)

    • Array [
    • featureName string required

      Name of the feature checked by the SDK

    • appName string required

      The name of the application the SDK is being used in

    • environment string required

      Which environment the SDK is being used in

    • timestamp object

      The start of the time window these metrics are valid for. The window is 1 hour wide

      oneOf
    • string date-time

      An RFC-3339-compliant timestamp.

    • yes integer

      How many times the toggle evaluated to true

    • no integer

      How many times the toggle evaluated to false

    • variants object

      How many times each variant was returned

    • property name* integer
    • ]
    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/bulk-toggle-features-environment-off.html b/reference/api/unleash/bulk-toggle-features-environment-off.html index 39429f41b4..be468c2c8e 100644 --- a/reference/api/unleash/bulk-toggle-features-environment-off.html +++ b/reference/api/unleash/bulk-toggle-features-environment-off.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Bulk disable a list of features

    POST /api/admin/projects/:projectId/bulk_features/environments/:environment/off

    This endpoint disables multiple feature toggles.

    Request​

    Path Parameters

    • projectId string required
    • environment string required

    Body

    required

    bulkToggleFeaturesSchema

    • features string[] required

      The features that we want to bulk toggle

    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/bulk-toggle-features-environment-on.html b/reference/api/unleash/bulk-toggle-features-environment-on.html index a71443db6b..471f47cb98 100644 --- a/reference/api/unleash/bulk-toggle-features-environment-on.html +++ b/reference/api/unleash/bulk-toggle-features-environment-on.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Bulk enable a list of features

    POST /api/admin/projects/:projectId/bulk_features/environments/:environment/on

    This endpoint enables multiple feature toggles.

    Request​

    Path Parameters

    • projectId string required
    • environment string required

    Body

    required

    bulkToggleFeaturesSchema

    • features string[] required

      The features that we want to bulk toggle

    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/change-my-password.html b/reference/api/unleash/change-my-password.html index 33b0d05b5c..8ecc15180a 100644 --- a/reference/api/unleash/change-my-password.html +++ b/reference/api/unleash/change-my-password.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Change your own password

    POST /api/admin/user/change-password

    Requires specifying old password and confirming new password

    Request​

    Body

    required

    passwordSchema

    • password string required

      The new password to change or validate.

    • oldPassword string

      The old password the user is changing. This field is for the non-admin users changing their own password.

    • confirmPassword string

      The confirmation of the new password. This field is for the non-admin users changing their own password.

    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/change-password.html b/reference/api/unleash/change-password.html index 9214fc16bb..dc7cf12735 100644 --- a/reference/api/unleash/change-password.html +++ b/reference/api/unleash/change-password.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Changes a user password

    POST /auth/reset/password

    Allows users with a valid reset token to reset their password without remembering their old password

    Request​

    Body

    required

    changePasswordSchema

    • token string required

      A reset token used to validate that the user is allowed to change the password.

    • password string required

      The new password for the user

    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/change-project.html b/reference/api/unleash/change-project.html index 57fc711df5..f5c4d8a238 100644 --- a/reference/api/unleash/change-project.html +++ b/reference/api/unleash/change-project.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Move feature to project

    POST /api/admin/projects/:projectId/features/:featureName/changeProject

    Moves the specified feature to the new project in the request schema. Requires you to have permissions to move the feature toggle in both projects. Features that are included in any active change requests can not be moved.

    Request​

    Path Parameters

    • projectId string required
    • featureName string required

    Body

    required

    changeProjectSchema

    • newProjectId string required

      The project to move the feature toggle to.

    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/change-request.html b/reference/api/unleash/change-request.html index c0f5b44feb..823d9feb84 100644 --- a/reference/api/unleash/change-request.html +++ b/reference/api/unleash/change-request.html @@ -20,7 +20,7 @@ - + @@ -30,7 +30,7 @@
    Skip to main content

    Create/Add change to a change request

    POST /api/admin/projects/:projectId/environments/:environment/change-requests

    Given a change request exists, this endpoint will attempt to add a change to an existing change request for the user. If a change request does not exist. It will attempt to create it.

    Request​

    Path Parameters

    • projectId string required
    • environment string required

    Body

    required

    changeRequestOneOrManyCreateSchema

      oneOf
    • action string required

      Possible values: [updateSegment]

      The name of this action.

    • payload objectrequired

      Data used to create or update a segment

    • id integer required

      The ID of the segment to update.

    Responses

    changeRequestSchema

    Schema
      oneOf
    • id number required

      This change requests's ID.

    • title string

      A title describing the change request's content.

    • environment string required

      The environment in which the changes should be applied.

    • minApprovals number required

      The minimum number of approvals required before this change request can be applied.

    • project string required

      The project this change request belongs to.

    • features object[]required

      The list of features and their changes that relate to this change request.

    • Array [
    • name string required

      The name of the feature

    • conflict string

      A string describing the conflicts related to this change. Only present if there are any concflicts on the feature level.

    • changes object[]required

      List of changes inside change request. This list may be empty when listing all change requests for a project.

    • Array [
    • id number required

      The ID of this change.

    • action string required

      The kind of action that the change contains information about.

    • conflict string

      A description of the conflict caused by this change. Only present if there are any conflicts.

    • payload objectrequired

      The data required to perform this action.

      oneOf
    • string
    • createdBy object

      The user who created this change.

    • username string nullable

      The user's username.

    • imageUrl uri nullable

      The URL where the user's image can be found.

    • createdAt date-time

      When this change was suggested

    • ]
    • defaultChange object

      A description of a default change that will be applied with the change request to prevent invalid states.

      Default changes are changes that are applied in addition to explicit user-specified changes when a change request is applied. Any default changes are applied in the background and are not a real part of the change request.

    • action string required

      The kind of action this is.

    • payload object required

      The necessary data to perform this change.

    • ]
    • segments object[]required

      The list of segments and their changes that relate to this change request.

    • Array [
    • id number required

      The ID of this change.

    • action string required

      The kind of action that the change contains information about.

    • conflict string

      A description of the conflict caused by this change. Only present if there are any conflicts.

    • payload objectrequired

      The data required to perform this action.

      oneOf
    • string
    • createdBy object

      The user who created this change.

    • username string nullable

      The user's username.

    • imageUrl uri nullable

      The URL where the user's image can be found.

    • createdAt date-time

      When this change was suggested

    • name string required

      The current name of the segment

    • ]
    • approvals object[]

      A list of approvals that this change request has received.

    • Array [
    • createdBy objectrequired

      Information about the user who gave this approval.

    • id number

      The ID of the user who gave this approval.

    • username string

      The approving user's username.

    • imageUrl uri

      The URL where the user's image can be found.

    • createdAt date-time required

      When the approval was given.

    • ]
    • rejections object[]

      A list of rejections that this change request has received.

    • Array [
    • createdBy objectrequired

      Information about the user who gave this approval.

    • id number

      The ID of the user who gave this approval.

    • username string

      The approving user's username.

    • imageUrl uri

      The URL where the user's image can be found.

    • createdAt date-time required

      When the approval was given.

    • ]
    • comments object[]

      All comments that have been made on this change request.

    • Array [
    • id number

      The comment's ID. Unique per change request.

    • text string required

      The content of the comment.

    • createdBy objectrequired

      Information about the user who posted the comment

    • username string nullable

      The user's username.

    • imageUrl uri nullable

      The URL where the user's image can be found.

    • createdAt date-time required

      When the comment was made.

    • ]
    • createdBy objectrequired

      The user who created this change request.

    • username string nullable
    • imageUrl uri nullable

      The URL of the user's profile image.

    • createdAt date-time required

      When this change request was created.

    • state string required

      Possible values: [Draft, In review, Approved, Applied, Cancelled, Rejected]

      The current state of the change request.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/change-requests.html b/reference/api/unleash/change-requests.html index 6862a3ac56..667c20aff9 100644 --- a/reference/api/unleash/change-requests.html +++ b/reference/api/unleash/change-requests.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Change Requests

    API for managing change requests.

    - + \ No newline at end of file diff --git a/reference/api/unleash/change-role-for-group.html b/reference/api/unleash/change-role-for-group.html index c90c2e6803..dd364a14e9 100644 --- a/reference/api/unleash/change-role-for-group.html +++ b/reference/api/unleash/change-role-for-group.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Update group's project role

    PUT /api/admin/projects/:projectId/groups/:groupId/roles/:roleId
    deprecated

    This endpoint has been deprecated and may be removed in future versions of the API.

    Updates the permissions that the group has within the given project. This endpoint is deprecated. Use /:projectId/users/:userId/roles instead.

    Request​

    Path Parameters

    • projectId string required
    • groupId string required
    • roleId string required
    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/change-role-for-user.html b/reference/api/unleash/change-role-for-user.html index 62951c154c..babf77e1ef 100644 --- a/reference/api/unleash/change-role-for-user.html +++ b/reference/api/unleash/change-role-for-user.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Update user's project role

    PUT /api/admin/projects/:projectId/users/:userId/roles/:roleId
    deprecated

    This endpoint has been deprecated and may be removed in future versions of the API.

    Replaces the given user's project role with the provided role. The user must already be a memeber of the project. This endpoint is deprecated. Use /:projectId/users/:userId/roles instead.

    Request​

    Path Parameters

    • projectId string required
    • userId string required
    • roleId string required
    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/change-user-password.html b/reference/api/unleash/change-user-password.html index d229ec2ff0..b26b6aaafe 100644 --- a/reference/api/unleash/change-user-password.html +++ b/reference/api/unleash/change-user-password.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Change password for a user

    POST /api/admin/user-admin/:id/change-password

    Change password for a user as an admin

    Request​

    Path Parameters

    • id string required

    Body

    required

    passwordSchema

    • password string required

      The new password to change or validate.

    • oldPassword string

      The old password the user is changing. This field is for the non-admin users changing their own password.

    • confirmPassword string

      The confirmation of the new password. This field is for the non-admin users changing their own password.

    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/check-dependencies-exist.html b/reference/api/unleash/check-dependencies-exist.html index 1311a883fb..747f73496c 100644 --- a/reference/api/unleash/check-dependencies-exist.html +++ b/reference/api/unleash/check-dependencies-exist.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Check dependencies exist.

    GET /api/admin/projects/:projectId/dependencies

    Check if any dependencies exist in this Unleash instance

    Request​

    Path Parameters

    • projectId string required
    Responses

    dependenciesExistSchema

    Schema
    • boolean

      true when any dependencies exist, false when no dependencies exist.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/check-license.html b/reference/api/unleash/check-license.html index 2446a31994..e3f30a3c7c 100644 --- a/reference/api/unleash/check-license.html +++ b/reference/api/unleash/check-license.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Validates the Unleash license.

    GET /api/admin/license/check

    Validates the Unleash license.

    Request​

    Responses

    licenseCheckSchema

    Schema
    • isValid boolean required

      Whether or not the current Unleash license is considered valid

    • message string

      Message describing the current state of the Unleash license

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/client.html b/reference/api/unleash/client.html index 6ca3257d1d..7bae2a4839 100644 --- a/reference/api/unleash/client.html +++ b/reference/api/unleash/client.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Client

    Endpoints for Unleash server-side clients.

    - + \ No newline at end of file diff --git a/reference/api/unleash/clone-environment.html b/reference/api/unleash/clone-environment.html index ef8c2a044c..8b67a7c910 100644 --- a/reference/api/unleash/clone-environment.html +++ b/reference/api/unleash/clone-environment.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Clones an environment

    POST /api/admin/environments/:name/clone

    Given an existing environment name and a set of options, this will create a copy of that environment

    Request​

    Path Parameters

    • name string required
    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/clone-feature.html b/reference/api/unleash/clone-feature.html index a2343e1093..2a958a956b 100644 --- a/reference/api/unleash/clone-feature.html +++ b/reference/api/unleash/clone-feature.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Clone a feature toggle

    POST /api/admin/projects/:projectId/features/:featureName/clone

    Creates a copy of the specified feature toggle. The copy can be created in any project.

    Request​

    Path Parameters

    • projectId string required
    • featureName string required

    Body

    required

    cloneFeatureSchema

    • name string required

      The name of the new feature

    • replaceGroupId boolean

      Whether to use the new feature name as its group ID or not. Group ID is used for calculating stickiness. Defaults to true.

    Responses

    featureSchema

    Schema
    • name string required

      Unique feature name

    • type string

      Type of the toggle e.g. experiment, kill-switch, release, operational, permission

    • description string nullable

      Detailed description of the feature

    • archived boolean

      true if the feature is archived

    • project string

      Name of the project the feature belongs to

    • enabled boolean

      true if the feature is enabled, otherwise false.

    • stale boolean

      true if the feature is stale based on the age and feature type, otherwise false.

    • favorite boolean

      true if the feature was favorited, otherwise false.

    • impressionData boolean

      true if the impression data collection is enabled for the feature, otherwise false.

    • createdAt date-time nullable

      The date the feature was created

    • archivedAt date-time nullable

      The date the feature was archived

    • lastSeenAt date-time nullable deprecated

      The date when metrics where last collected for the feature. This field is deprecated, use the one in featureEnvironmentSchema

    • environments object[]

      The list of environments where the feature can be used

    • Array [
    • name string required

      The name of the environment

    • featureName string

      The name of the feature

    • environment string

      The name of the environment

    • type string

      The type of the environment

    • enabled boolean required

      true if the feature is enabled for the environment, otherwise false.

    • sortOrder number

      The sort order of the feature environment in the feature environments list

    • variantCount number

      The number of defined variants

    • strategies object[]

      A list of activation strategies for the feature environment

    • Array [
    • id string

      A uuid for the feature strategy

    • name string required

      The name or type of strategy

    • title string nullable

      A descriptive title for the strategy

    • disabled boolean nullable

      A toggle to disable the strategy. defaults to false. Disabled strategies are not evaluated or returned to the SDKs

    • featureName string

      The name or feature the strategy is attached to

    • sortOrder number

      The order of the strategy in the list

    • segments number[]

      A list of segment ids attached to the strategy

    • constraints object[]

      A list of the constraints attached to the strategy. See https://docs.getunleash.io/reference/strategy-constraints

    • Array [
    • contextName string required

      The name of the context field that this constraint should apply to.

    • operator string required

      Possible values: [NOT_IN, IN, STR_ENDS_WITH, STR_STARTS_WITH, STR_CONTAINS, NUM_EQ, NUM_GT, NUM_GTE, NUM_LT, NUM_LTE, DATE_AFTER, DATE_BEFORE, SEMVER_EQ, SEMVER_GT, SEMVER_LT]

      The operator to use when evaluating this constraint. For more information about the various operators, refer to the strategy constraint operator documentation.

    • caseInsensitive boolean

      Default value: false

      Whether the operator should be case sensitive or not. Defaults to false (being case sensitive).

    • inverted boolean

      Default value: false

      Whether the result should be negated or not. If true, will turn a true result into a false result and vice versa.

    • values string[]

      The context values that should be used for constraint evaluation. Use this property instead of value for properties that accept multiple values.

    • value string

      The context value that should be used for constraint evaluation. Use this property instead of values for properties that only accept single values.

    • ]
    • variants object[]

      Strategy level variants

    • Array [
    • name string required

      The variant name. Must be unique for this feature toggle

    • weight integer required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is an integer between 0 and 1000. See the section on variant weights for more information

    • weightType string required

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000. Refer to the variant weight documentation.

    • stickiness string required

      The stickiness to use for distribution of this variant. Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • ]
    • parameters object

      A list of parameters for a strategy

    • property name* string
    • ]
    • variants object[]

      A list of variants for the feature environment

    • Array [
    • name string required

      The variants name. Is unique for this feature toggle

    • weight number required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is a number between 0 and 1000. See the section on variant weights for more information

    • weightType string

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000

    • stickiness string

      Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • overrides object[]

      Overrides assigning specific variants to specific users. The weighting system automatically assigns users to specific groups for you, but any overrides in this list will take precedence.

    • Array [
    • contextName string required

      The name of the context field used to determine overrides

    • values string[] required

      Which values that should be overriden

    • ]
    • ]
    • lastSeenAt date-time nullable

      The date when metrics where last collected for the feature environment

    • hasStrategies boolean

      Whether the feature has any strategies defined.

    • hasEnabledStrategies boolean

      Whether the feature has any enabled strategies defined.

    • ]
    • variants object[]deprecated

      The list of feature variants

    • Array [
    • name string required

      The variants name. Is unique for this feature toggle

    • weight number required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is a number between 0 and 1000. See the section on variant weights for more information

    • weightType string

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000

    • stickiness string

      Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • overrides object[]

      Overrides assigning specific variants to specific users. The weighting system automatically assigns users to specific groups for you, but any overrides in this list will take precedence.

    • Array [
    • contextName string required

      The name of the context field used to determine overrides

    • values string[] required

      Which values that should be overriden

    • ]
    • ]
    • strategies object[] deprecated

      This is a legacy field that will be deprecated

    • tags object[]nullable

      The list of feature tags

    • Array [
    • value string required

      Possible values: >= 2 characters and <= 50 characters

      The value of the tag

    • type string required

      Possible values: >= 2 characters and <= 50 characters

      Default value: simple

      The type of the tag

    • ]
    • children string[]

      The list of child feature names. This is an experimental field and may change.

    • dependencies object[]

      The list of parent dependencies. This is an experimental field and may change.

    • Array [
    • feature string required

      The name of the parent feature

    • enabled boolean

      Whether the parent feature is enabled or not

    • variants string[]

      The list of variants the parent feature should resolve to. Only valid when feature is enabled.

    • ]
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/context.html b/reference/api/unleash/context.html index c8cad2d2d6..02970308f0 100644 --- a/reference/api/unleash/context.html +++ b/reference/api/unleash/context.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Context

    Create, update, and delete context fields that Unleash is aware of.

    - + \ No newline at end of file diff --git a/reference/api/unleash/create-addon.html b/reference/api/unleash/create-addon.html index 6226ca0326..5a19758ee5 100644 --- a/reference/api/unleash/create-addon.html +++ b/reference/api/unleash/create-addon.html @@ -20,7 +20,7 @@ - + @@ -37,7 +37,7 @@
  • webhook for webhooks

    • The provider you choose for your addon dictates what properties the parameters object needs. Refer to the documentation for each provider for more information.

  • description string

    A description of the addon.

  • enabled boolean required

    Whether the addon should be enabled or not.

  • parameters objectrequired

    Parameters for the addon provider. This object has different required and optional properties depending on the provider you choose. Consult the documentation for details.

  • events string[] required

    The event types that will trigger this specific addon.

  • projects string[]

    The projects that this addon will listen to events from. An empty list means it will listen to events from all projects.

  • environments string[]

    The list of environments that this addon will listen to events from. An empty list means it will listen to events from all environments.

    • Responses

    addonSchema

    Schema
    • id integer required

      Possible values: >= 1

      The addon's unique identifier.

    • provider string required

      The addon provider, such as "webhook" or "slack".

    • description string nullable required

      A description of the addon. null if no description exists.

    • enabled boolean required

      Whether the addon is enabled or not.

    • parameters objectrequired

      Parameters for the addon provider. This object has different required and optional properties depending on the provider you choose.

    • events string[] required

      The event types that trigger this specific addon.

    • projects string[]

      The projects that this addon listens to events from. An empty list means it listens to events from all projects.

    • environments string[]

      The list of environments that this addon listens to events from. An empty list means it listens to events from all environments.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/create-api-token.html b/reference/api/unleash/create-api-token.html index f06cde0b8d..84a7abc334 100644 --- a/reference/api/unleash/create-api-token.html +++ b/reference/api/unleash/create-api-token.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Create API token

    POST /api/admin/api-tokens

    Create an API token of a specific type: one of client, admin, frontend.

    Request​

    Body

    required

    createApiTokenSchema

      oneOf
    • expiresAt date-time

      The time when this token should expire.

    • type string required

      Possible values: Value must match regular expression ^[Aa][Dd][Mm][Ii][Nn]$

      An admin token. Must be the string "admin" (not case sensitive).

    • tokenName string required

      The name of the token.

    Responses

    The resource was successfully created.

    Response Headers
    • location string

      The location of the newly created resource.

    Schema
    • secret string required

      The token used for authentication.

    • username string deprecated

      This property was deprecated in Unleash v5. Prefer the tokenName property instead.

    • tokenName string required

      A unique name for this particular token

    • type string required

      Possible values: [client, admin, frontend]

      The type of API token

    • environment string

      The environment the token has access to. * if it has access to all environments.

    • project string required

      The project this token belongs to.

    • projects string[] required

      The list of projects this token has access to. If the token has access to specific projects they will be listed here. If the token has access to all projects it will be represented as [*]

    • expiresAt date-time nullable

      The token's expiration date. NULL if the token doesn't have an expiration set.

    • createdAt date-time required

      When the token was created.

    • seenAt date-time nullable

      When the token was last seen/used to authenticate with. NULL if the token has not yet been used for authentication.

    • alias string nullable

      Alias is no longer in active use and will often be NULL. It's kept around as a way of allowing old proxy tokens created with the old metadata format to keep working.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/create-application.html b/reference/api/unleash/create-application.html index 26b578090c..4d01e7f94e 100644 --- a/reference/api/unleash/create-application.html +++ b/reference/api/unleash/create-application.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Create an application to connect reported metrics

    POST /api/admin/metrics/applications/:appName

    Is used to report usage as well which sdk the application uses

    Request​

    Path Parameters

    • appName string required

    Body

    required

    createApplicationSchema

    • appName string

      Name of the application

    • sdkVersion string

      Which SDK and version the application reporting uses. Typically represented as <identifier>:<version>

    • strategies string[]

      Which strategies the application has loaded. Useful when trying to figure out if your custom strategy has been loaded in the SDK

    • url string

      A link to reference the application reporting the metrics. Could for instance be a GitHub link to the repository of the application

    • color string

      Css color to be used to color the application's entry in the application list

    • icon string

      An URL to an icon file to be used for the applications's entry in the application list

    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/create-banner.html b/reference/api/unleash/create-banner.html index 14164ccee1..8b309ae554 100644 --- a/reference/api/unleash/create-banner.html +++ b/reference/api/unleash/create-banner.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Create a banner.

    POST /api/admin/banners

    Creates a new banner.

    Request​

    Body

    required

    createBannerSchema

    • message string required

      The message to display to all users. Supports markdown.

    • enabled boolean

      Whether the banner should be displayed currently. If not specified, defaults to true.

    • variant string

      The variant of the banner. One of "info", "warning", "error", or "success". If not specified, defaults to "info".

    • sticky boolean

      Whether the banner should be sticky on the screen. If not specified, defaults to false.

    • icon string nullable

      The icon to display on the banner. Can be one of https://fonts.google.com/icons. If not specified, this will be the default icon for the variant. If "none", no icon will be displayed.

    • link string nullable

      The link to display on the banner. Can either be an absolute or a relative link (e.g. absolute: "https://example.com" or relative: "/admin/service-accounts"). If "dialog", will display a dialog when clicked. If not specified, no link will be displayed.

    • linkText string nullable

      The text to display on the link. If not specified, will be displayed as "More info".

    • dialogTitle string nullable

      The title to display on the dialog. If not specified, this will be the same as linkText.

    • dialog string nullable

      The markdown to display on the dialog. If not specified, no dialog will be displayed.

    Responses

    The resource was successfully created.

    Response Headers
    • location string

      The location of the newly created resource.

    Schema
    • id integer required

      Possible values: >= 1

      The banner's ID. Banner IDs are incrementing integers. In other words, a more recently created banner will always have a higher ID than an older one.

    • message string required

      The message to display to all users. Supports markdown.

    • enabled boolean

      Whether the banner should be displayed currently. If not specified, defaults to true.

    • variant string

      The variant of the banner. One of "info", "warning", "error", or "success". If not specified, defaults to "info".

    • sticky boolean

      Whether the banner should be sticky on the screen. If not specified, defaults to false.

    • icon string nullable

      The icon to display on the banner. Can be one of https://fonts.google.com/icons. If not specified, this will be the default icon for the variant. If "none", no icon will be displayed.

    • link string nullable

      The link to display on the banner. Can either be an absolute or a relative link (e.g. absolute: "https://example.com" or relative: "/admin/service-accounts"). If "dialog", will display a dialog when clicked. If not specified, no link will be displayed.

    • linkText string nullable

      The text to display on the link. If not specified, will be displayed as "More info".

    • dialogTitle string nullable

      The title to display on the dialog. If not specified, this will be the same as linkText.

    • dialog string nullable

      The markdown to display on the dialog. If not specified, no dialog will be displayed.

    • createdAt date-time required

      The date and time of when the banner was created.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/create-context-field.html b/reference/api/unleash/create-context-field.html index 09ca6f2af6..3886bc1c89 100644 --- a/reference/api/unleash/create-context-field.html +++ b/reference/api/unleash/create-context-field.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Create a context field

    POST /api/admin/context

    Endpoint that allows creation of custom context fields

    Request​

    Body

    required

    createContextFieldSchema

    • description string

      A description of the context field

    • stickiness boolean

      true if this field should be available for use with custom stickiness, otherwise false

    • sortOrder integer

      How this context field should be sorted if no other sort order is selected

    • legalValues object[]

      A list of allowed values for this context field

    • Array [
    • value string required

      The valid value

    • description string

      Describes this specific legal value

    • ]
    • name string required

      The name of the context field.

    Responses

    The resource was successfully created.

    Response Headers
    • location string

      The location of the newly created resource.

    Schema
    • name string required

      The name of the context field

    • description string nullable

      The description of the context field.

    • stickiness boolean

      Does this context field support being used for stickiness calculations

    • sortOrder integer

      Used when sorting a list of context fields. Is also used as a tiebreaker if a list of context fields is sorted alphabetically.

    • createdAt date-time nullable

      When this context field was created

    • usedInFeatures integer nullable

      Number of projects where this context field is used in

    • usedInProjects integer nullable

      Number of projects where this context field is used in

    • legalValues object[]

      Allowed values for this context field schema. Can be used to narrow down accepted input

    • Array [
    • value string required

      The valid value

    • description string

      Describes this specific legal value

    • ]
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/create-environment.html b/reference/api/unleash/create-environment.html index ad4fb28d2f..43514b910b 100644 --- a/reference/api/unleash/create-environment.html +++ b/reference/api/unleash/create-environment.html @@ -20,7 +20,7 @@ - + @@ -35,7 +35,7 @@
  • production

    • If you pass a string that is not one of the recognized values, Unleash will accept it, but it will carry no special semantics.

  • enabled boolean

    Newly created environments are enabled by default. Set this property to false to create the environment in a disabled state.

  • sortOrder integer

    Defines where in the list of environments to place this environment. The list uses an ascending sort, so lower numbers are shown first. You can change this value later.

    • Responses

    The resource was successfully created.

    Response Headers
    • location string

      The location of the newly created resource.

    Schema
    • name string required

      The name of the environment

    • type string required
    • enabled boolean required

      true if the environment is enabled for the project, otherwise false.

    • protected boolean required

      true if the environment is protected, otherwise false. A protected environment can not be deleted.

    • sortOrder integer required

      Priority of the environment in a list of environments, the lower the value, the higher up in the list the environment will appear. Needs to be an integer

    • projectCount integer nullable

      The number of projects with this environment

    • apiTokenCount integer nullable

      The number of API tokens for the project environment

    • enabledToggleCount integer nullable

      The number of enabled toggles for the project environment

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/create-feature.html b/reference/api/unleash/create-feature.html index 5c340e61a6..b769dc4522 100644 --- a/reference/api/unleash/create-feature.html +++ b/reference/api/unleash/create-feature.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Add a new feature toggle

    POST /api/admin/projects/:projectId/features

    Create a new feature toggle in a specified project.

    Request​

    Path Parameters

    • projectId string required

    Body

    required

    createFeatureSchema

    • name string required

      Unique feature name

    • type string

      The feature toggle's type. One of experiment, kill-switch, release, operational, or permission

    • description string nullable

      Detailed description of the feature

    • impressionData boolean

      true if the impression data collection is enabled for the feature, otherwise false.

    Responses

    featureSchema

    Schema
    • name string required

      Unique feature name

    • type string

      Type of the toggle e.g. experiment, kill-switch, release, operational, permission

    • description string nullable

      Detailed description of the feature

    • archived boolean

      true if the feature is archived

    • project string

      Name of the project the feature belongs to

    • enabled boolean

      true if the feature is enabled, otherwise false.

    • stale boolean

      true if the feature is stale based on the age and feature type, otherwise false.

    • favorite boolean

      true if the feature was favorited, otherwise false.

    • impressionData boolean

      true if the impression data collection is enabled for the feature, otherwise false.

    • createdAt date-time nullable

      The date the feature was created

    • archivedAt date-time nullable

      The date the feature was archived

    • lastSeenAt date-time nullable deprecated

      The date when metrics where last collected for the feature. This field is deprecated, use the one in featureEnvironmentSchema

    • environments object[]

      The list of environments where the feature can be used

    • Array [
    • name string required

      The name of the environment

    • featureName string

      The name of the feature

    • environment string

      The name of the environment

    • type string

      The type of the environment

    • enabled boolean required

      true if the feature is enabled for the environment, otherwise false.

    • sortOrder number

      The sort order of the feature environment in the feature environments list

    • variantCount number

      The number of defined variants

    • strategies object[]

      A list of activation strategies for the feature environment

    • Array [
    • id string

      A uuid for the feature strategy

    • name string required

      The name or type of strategy

    • title string nullable

      A descriptive title for the strategy

    • disabled boolean nullable

      A toggle to disable the strategy. defaults to false. Disabled strategies are not evaluated or returned to the SDKs

    • featureName string

      The name or feature the strategy is attached to

    • sortOrder number

      The order of the strategy in the list

    • segments number[]

      A list of segment ids attached to the strategy

    • constraints object[]

      A list of the constraints attached to the strategy. See https://docs.getunleash.io/reference/strategy-constraints

    • Array [
    • contextName string required

      The name of the context field that this constraint should apply to.

    • operator string required

      Possible values: [NOT_IN, IN, STR_ENDS_WITH, STR_STARTS_WITH, STR_CONTAINS, NUM_EQ, NUM_GT, NUM_GTE, NUM_LT, NUM_LTE, DATE_AFTER, DATE_BEFORE, SEMVER_EQ, SEMVER_GT, SEMVER_LT]

      The operator to use when evaluating this constraint. For more information about the various operators, refer to the strategy constraint operator documentation.

    • caseInsensitive boolean

      Default value: false

      Whether the operator should be case sensitive or not. Defaults to false (being case sensitive).

    • inverted boolean

      Default value: false

      Whether the result should be negated or not. If true, will turn a true result into a false result and vice versa.

    • values string[]

      The context values that should be used for constraint evaluation. Use this property instead of value for properties that accept multiple values.

    • value string

      The context value that should be used for constraint evaluation. Use this property instead of values for properties that only accept single values.

    • ]
    • variants object[]

      Strategy level variants

    • Array [
    • name string required

      The variant name. Must be unique for this feature toggle

    • weight integer required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is an integer between 0 and 1000. See the section on variant weights for more information

    • weightType string required

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000. Refer to the variant weight documentation.

    • stickiness string required

      The stickiness to use for distribution of this variant. Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • ]
    • parameters object

      A list of parameters for a strategy

    • property name* string
    • ]
    • variants object[]

      A list of variants for the feature environment

    • Array [
    • name string required

      The variants name. Is unique for this feature toggle

    • weight number required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is a number between 0 and 1000. See the section on variant weights for more information

    • weightType string

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000

    • stickiness string

      Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • overrides object[]

      Overrides assigning specific variants to specific users. The weighting system automatically assigns users to specific groups for you, but any overrides in this list will take precedence.

    • Array [
    • contextName string required

      The name of the context field used to determine overrides

    • values string[] required

      Which values that should be overriden

    • ]
    • ]
    • lastSeenAt date-time nullable

      The date when metrics where last collected for the feature environment

    • hasStrategies boolean

      Whether the feature has any strategies defined.

    • hasEnabledStrategies boolean

      Whether the feature has any enabled strategies defined.

    • ]
    • variants object[]deprecated

      The list of feature variants

    • Array [
    • name string required

      The variants name. Is unique for this feature toggle

    • weight number required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is a number between 0 and 1000. See the section on variant weights for more information

    • weightType string

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000

    • stickiness string

      Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • overrides object[]

      Overrides assigning specific variants to specific users. The weighting system automatically assigns users to specific groups for you, but any overrides in this list will take precedence.

    • Array [
    • contextName string required

      The name of the context field used to determine overrides

    • values string[] required

      Which values that should be overriden

    • ]
    • ]
    • strategies object[] deprecated

      This is a legacy field that will be deprecated

    • tags object[]nullable

      The list of feature tags

    • Array [
    • value string required

      Possible values: >= 2 characters and <= 50 characters

      The value of the tag

    • type string required

      Possible values: >= 2 characters and <= 50 characters

      Default value: simple

      The type of the tag

    • ]
    • children string[]

      The list of child feature names. This is an experimental field and may change.

    • dependencies object[]

      The list of parent dependencies. This is an experimental field and may change.

    • Array [
    • feature string required

      The name of the parent feature

    • enabled boolean

      Whether the parent feature is enabled or not

    • variants string[]

      The list of variants the parent feature should resolve to. Only valid when feature is enabled.

    • ]
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/create-feedback.html b/reference/api/unleash/create-feedback.html index 27bd0c8137..e624ed54f0 100644 --- a/reference/api/unleash/create-feedback.html +++ b/reference/api/unleash/create-feedback.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Send Unleash feedback

    POST /api/admin/feedback

    Sends feedback gathered from the Unleash UI to the Unleash server. Must be called with a token with an identifiable user (either from being sent from the UI or from using a PAT).

    Request​

    Body

    required

    feedbackCreateSchema

    • neverShow boolean

      true if the user has asked never to see this feedback questionnaire again. Defaults to false.

    • feedbackId string required

      The name of the feedback session

    Responses

    feedbackResponseSchema

    Schema
    • userId integer

      The ID of the user that gave the feedback.

    • neverShow boolean

      true if the user has asked never to see this feedback questionnaire again.

    • given date-time nullable

      When this feedback was given

    • feedbackId string

      The name of the feedback session

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/create-group.html b/reference/api/unleash/create-group.html index 2be78800fd..38594a0ce1 100644 --- a/reference/api/unleash/create-group.html +++ b/reference/api/unleash/create-group.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Create a new group

    POST /api/admin/groups

    Create a new user group for Role-Based Access Control

    Request​

    Body

    required

    createGroupSchema

    • name string required

      The name of the group

    • description string nullable

      A custom description of the group

    • mappingsSSO string[]

      A list of SSO groups that should map to this Unleash group

    • rootRole number nullable

      A role id that is used as the root role for all users in this group. This can be either the id of the Viewer, Editor or Admin role.

    • users object[]

      A list of users belonging to this group

    • Array [
    • user objectrequired

      A minimal user object

    • id integer required

      The user id

    • ]
    Responses

    The resource was successfully created.

    Response Headers
    • location string

      The location of the newly created resource.

    Schema
    • id integer

      The group id

    • name string required

      The name of the group

    • description string nullable

      A custom description of the group

    • mappingsSSO string[]

      A list of SSO groups that should map to this Unleash group

    • rootRole number nullable

      A role id that is used as the root role for all users in this group. This can be either the id of the Viewer, Editor or Admin role.

    • createdBy string nullable

      A user who created this group

    • createdAt date-time nullable

      When was this group created

    • users object[]

      A list of users belonging to this group

    • Array [
    • joinedAt date-time

      The date when the user joined the group

    • createdBy string nullable

      The username of the user who added this user to this group

    • user objectrequired

      An Unleash user

    • id integer required

      The user id

    • isAPI boolean deprecated

      (Deprecated): Used internally to know which operations the user should be allowed to perform

    • name string nullable

      Name of the user

    • email string

      Email of the user

    • username string nullable

      A unique username for the user

    • imageUrl string

      URL used for the userprofile image

    • inviteLink string

      If the user is actively inviting other users, this is the link that can be shared with other users

    • loginAttempts integer

      How many unsuccessful attempts at logging in has the user made

    • emailSent boolean

      Is the welcome email sent to the user or not

    • rootRole integer

      Which root role this user is assigned

    • seenAt date-time nullable

      The last time this user logged in

    • createdAt date-time

      The user was created at this time

    • accountType string

      A user is either an actual User or a Service Account

    • permissions string[]

      Deprecated

    • ]
    • projects string[]

      A list of projects where this group is used

    • userCount integer

      The number of users that belong to this group

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/create-pat.html b/reference/api/unleash/create-pat.html index 13fc1b40df..9ff66d6cd6 100644 --- a/reference/api/unleash/create-pat.html +++ b/reference/api/unleash/create-pat.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Create a new Personal Access Token.

    POST /api/admin/user/tokens

    Creates a new Personal Access Token for the current user.

    Request​

    Body

    required

    patSchema

    • id integer

      Possible values: >= 1

      The unique identification number for this Personal Access Token. (This property is set by Unleash when the token is created and cannot be set manually: if you provide a value when creating a PAT, Unleash will ignore it.)

    • secret string

      The token used for authentication. (This property is set by Unleash when the token is created and cannot be set manually: if you provide a value when creating a PAT, Unleash will ignore it.)

    • expiresAt date-time

      The token's expiration date.

    • createdAt date-time

      When the token was created. (This property is set by Unleash when the token is created and cannot be set manually: if you provide a value when creating a PAT, Unleash will ignore it.)

    • seenAt date-time nullable

      When the token was last seen/used to authenticate with. null if it has not been used yet. (This property is set by Unleash when the token is created and cannot be set manually: if you provide a value when creating a PAT, Unleash will ignore it.)

    Responses

    The resource was successfully created.

    Response Headers
    • location string

      The location of the newly created resource.

    Schema
    • id integer

      Possible values: >= 1

      The unique identification number for this Personal Access Token. (This property is set by Unleash when the token is created and cannot be set manually: if you provide a value when creating a PAT, Unleash will ignore it.)

    • secret string

      The token used for authentication. (This property is set by Unleash when the token is created and cannot be set manually: if you provide a value when creating a PAT, Unleash will ignore it.)

    • expiresAt date-time

      The token's expiration date.

    • createdAt date-time

      When the token was created. (This property is set by Unleash when the token is created and cannot be set manually: if you provide a value when creating a PAT, Unleash will ignore it.)

    • seenAt date-time nullable

      When the token was last seen/used to authenticate with. null if it has not been used yet. (This property is set by Unleash when the token is created and cannot be set manually: if you provide a value when creating a PAT, Unleash will ignore it.)

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/create-project-api-token.html b/reference/api/unleash/create-project-api-token.html index 9e0173abaa..98c99aa6c5 100644 --- a/reference/api/unleash/create-project-api-token.html +++ b/reference/api/unleash/create-project-api-token.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Create a project API token.

    POST /api/admin/projects/:projectId/api-tokens

    Endpoint that allows creation of project API tokens for the specified project.

    Request​

    Path Parameters

    • projectId string required

    Body

    required

    createApiTokenSchema

      oneOf
    • expiresAt date-time

      The time when this token should expire.

    • type string required

      Possible values: Value must match regular expression ^[Aa][Dd][Mm][Ii][Nn]$

      An admin token. Must be the string "admin" (not case sensitive).

    • tokenName string required

      The name of the token.

    Responses

    The resource was successfully created.

    Response Headers
    • location string

      The location of the newly created resource.

    Schema
    • secret string required

      The token used for authentication.

    • username string deprecated

      This property was deprecated in Unleash v5. Prefer the tokenName property instead.

    • tokenName string required

      A unique name for this particular token

    • type string required

      Possible values: [client, admin, frontend]

      The type of API token

    • environment string

      The environment the token has access to. * if it has access to all environments.

    • project string required

      The project this token belongs to.

    • projects string[] required

      The list of projects this token has access to. If the token has access to specific projects they will be listed here. If the token has access to all projects it will be represented as [*]

    • expiresAt date-time nullable

      The token's expiration date. NULL if the token doesn't have an expiration set.

    • createdAt date-time required

      When the token was created.

    • seenAt date-time nullable

      When the token was last seen/used to authenticate with. NULL if the token has not yet been used for authentication.

    • alias string nullable

      Alias is no longer in active use and will often be NULL. It's kept around as a way of allowing old proxy tokens created with the old metadata format to keep working.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/create-project.html b/reference/api/unleash/create-project.html index 0bd0fb8991..684eecc12a 100644 --- a/reference/api/unleash/create-project.html +++ b/reference/api/unleash/create-project.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Create project

    POST /api/admin/projects

    Create a new Unleash project.

    Request​

    Body

    required

    createProjectSchema

    • id string required

      Possible values: Value must match regular expression [A-Za-z0-9_~.-]+

      The project's identifier.

    • name string required

      Possible values: non-empty

      The project's name.

    • description string nullable

      The project's description.

    • mode string

      Possible values: [open, protected, private]

      A mode of the project affecting what actions are possible in this project

    • defaultStickiness string

      A default stickiness for the project affecting the default stickiness value for variants and Gradual Rollout strategy

    Responses

    The resource was successfully created.

    Response Headers
    • location string

      The location of the newly created resource.

    Schema
    • id string required

      Possible values: Value must match regular expression [A-Za-z0-9_~.-]+

      The project's identifier.

    • name string required

      Possible values: non-empty

      The project's name.

    • description string nullable

      The project's description.

    • featureLimit integer nullable

      A limit on the number of features allowed in the project. null if no limit.

    • mode string

      Possible values: [open, protected, private]

      A mode of the project affecting what actions are possible in this project

    • defaultStickiness string

      A default stickiness for the project affecting the default stickiness value for variants and Gradual Rollout strategy

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/create-public-signup-token.html b/reference/api/unleash/create-public-signup-token.html index 5f48b626da..6d4bfa11d9 100644 --- a/reference/api/unleash/create-public-signup-token.html +++ b/reference/api/unleash/create-public-signup-token.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Create a public signup token

    POST /api/admin/invite-link/tokens

    Lets administrators create a invite link to share with colleagues. People that join using the public invite are assigned the Viewer role

    Request​

    Body

    required

    publicSignupTokenCreateSchema

    • name string required

      The token's name.

    • expiresAt date-time required

      The token's expiration date.

    Responses

    The resource was successfully created.

    Response Headers
    • location string

      The location of the newly created resource.

    Schema
    • secret string required

      The actual value of the token. This is the part that is used by Unleash to create an invite link

    • url string nullable required

      The public signup link for the token. Users who follow this link will be taken to a signup page where they can create an Unleash user.

    • name string required

      The token's name. Only for displaying in the UI

    • enabled boolean required

      Whether the token is active. This property will always be false for a token that has expired.

    • expiresAt date-time required

      The time when the token will expire.

    • createdAt date-time required

      When the token was created.

    • createdBy string nullable required

      The creator's email or username

    • users object[]nullable

      Array of users that have signed up using the token.

    • Array [
    • id integer required

      The user id

    • isAPI boolean deprecated

      (Deprecated): Used internally to know which operations the user should be allowed to perform

    • name string nullable

      Name of the user

    • email string

      Email of the user

    • username string nullable

      A unique username for the user

    • imageUrl string

      URL used for the userprofile image

    • inviteLink string

      If the user is actively inviting other users, this is the link that can be shared with other users

    • loginAttempts integer

      How many unsuccessful attempts at logging in has the user made

    • emailSent boolean

      Is the welcome email sent to the user or not

    • rootRole integer

      Which root role this user is assigned

    • seenAt date-time nullable

      The last time this user logged in

    • createdAt date-time

      The user was created at this time

    • accountType string

      A user is either an actual User or a Service Account

    • permissions string[]

      Deprecated

    • ]
    • role objectrequired

      A role holds permissions to allow Unleash to decide what actions a role holder is allowed to perform

    • id integer required

      The role id

    • type string required

      A role can either be a global root role (applies to all projects) or a project role

    • name string required

      The name of the role

    • description string

      A more detailed description of the role and what use it's intended for

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/create-role.html b/reference/api/unleash/create-role.html index 6bd12b883b..1d5b5cb1ec 100644 --- a/reference/api/unleash/create-role.html +++ b/reference/api/unleash/create-role.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Create a new role

    POST /api/admin/roles

    Create a new custom role for Role-Based Access Control

    Request​

    Body

    required

    createRoleWithPermissionsSchema

      anyOf
    • name string required

      The name of the custom role

    • description string

      A more detailed description of the custom role and what use it's intended for

    • type string

      Possible values: [root-custom, custom]

      Custom root roles (type=root-custom) are root roles with a custom set of permissions. Custom project roles (type=custom) contain a specific set of permissions for project resources.

    • permissions object[]

      A list of permissions assigned to this role

    • Array [
    • name string required

      The name of the permission

    • environment string

      The environments of the permission if the permission is environment specific

    • ]
    Responses

    roleWithVersionSchema

    Schema
    • version integer required

      Possible values: >= 1

      The version of this schema

    • roles objectrequired

      A role holds permissions to allow Unleash to decide what actions a role holder is allowed to perform

    • id integer required

      The role id

    • type string required

      A role can either be a global root role (applies to all projects) or a project role

    • name string required

      The name of the role

    • description string

      A more detailed description of the role and what use it's intended for

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/create-segment.html b/reference/api/unleash/create-segment.html index 430a202031..f771f0e195 100644 --- a/reference/api/unleash/create-segment.html +++ b/reference/api/unleash/create-segment.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Create a new segment

    POST /api/admin/segments

    Creates a new segment using the payload provided

    Request​

    Body

    required

    upsertSegmentSchema

    • name string required

      The name of the segment

    • description string nullable

      A description of what the segment is for

    • project string nullable

      The project the segment belongs to if any.

    • constraints object[]required

      The list of constraints that make up this segment

    • Array [
    • contextName string required

      The name of the context field that this constraint should apply to.

    • operator string required

      Possible values: [NOT_IN, IN, STR_ENDS_WITH, STR_STARTS_WITH, STR_CONTAINS, NUM_EQ, NUM_GT, NUM_GTE, NUM_LT, NUM_LTE, DATE_AFTER, DATE_BEFORE, SEMVER_EQ, SEMVER_GT, SEMVER_LT]

      The operator to use when evaluating this constraint. For more information about the various operators, refer to the strategy constraint operator documentation.

    • caseInsensitive boolean

      Default value: false

      Whether the operator should be case sensitive or not. Defaults to false (being case sensitive).

    • inverted boolean

      Default value: false

      Whether the result should be negated or not. If true, will turn a true result into a false result and vice versa.

    • values string[]

      The context values that should be used for constraint evaluation. Use this property instead of value for properties that accept multiple values.

    • value string

      The context value that should be used for constraint evaluation. Use this property instead of values for properties that only accept single values.

    • ]
    Responses

    The resource was successfully created.

    Response Headers
    • location string

      The location of the newly created resource.

    Schema
    • id integer required

      The ID of this segment

    • name string required

      The name of this segment

    • description string nullable

      The description for this segment

    • constraints object[]required

      The list of constraints that are used in this segment

    • Array [
    • contextName string required

      The name of the context field that this constraint should apply to.

    • operator string required

      Possible values: [NOT_IN, IN, STR_ENDS_WITH, STR_STARTS_WITH, STR_CONTAINS, NUM_EQ, NUM_GT, NUM_GTE, NUM_LT, NUM_LTE, DATE_AFTER, DATE_BEFORE, SEMVER_EQ, SEMVER_GT, SEMVER_LT]

      The operator to use when evaluating this constraint. For more information about the various operators, refer to the strategy constraint operator documentation.

    • caseInsensitive boolean

      Default value: false

      Whether the operator should be case sensitive or not. Defaults to false (being case sensitive).

    • inverted boolean

      Default value: false

      Whether the result should be negated or not. If true, will turn a true result into a false result and vice versa.

    • values string[]

      The context values that should be used for constraint evaluation. Use this property instead of value for properties that accept multiple values.

    • value string

      The context value that should be used for constraint evaluation. Use this property instead of values for properties that only accept single values.

    • ]
    • usedInFeatures integer nullable

      The number of feature flags that use this segment. The number also includes the any flags with pending change requests that would add this segment.

    • usedInProjects integer nullable

      The number of projects that use this segment. The number includes any projects with pending change requests that would add this segment.

    • project string nullable

      The project the segment belongs to. Only present if the segment is a project-specific segment.

    • createdBy string nullable

      The creator's email or username

    • createdAt date-time required

      When the segment was created

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/create-service-account-token.html b/reference/api/unleash/create-service-account-token.html index c45b19469d..89f2f8406b 100644 --- a/reference/api/unleash/create-service-account-token.html +++ b/reference/api/unleash/create-service-account-token.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Create a token for a service account.

    POST /api/admin/service-account/:id/token

    Creates a new token for the service account identified by the id.

    Request​

    Path Parameters

    • id string required

    Body

    required

    patSchema

    • id integer

      Possible values: >= 1

      The unique identification number for this Personal Access Token. (This property is set by Unleash when the token is created and cannot be set manually: if you provide a value when creating a PAT, Unleash will ignore it.)

    • secret string

      The token used for authentication. (This property is set by Unleash when the token is created and cannot be set manually: if you provide a value when creating a PAT, Unleash will ignore it.)

    • expiresAt date-time

      The token's expiration date.

    • createdAt date-time

      When the token was created. (This property is set by Unleash when the token is created and cannot be set manually: if you provide a value when creating a PAT, Unleash will ignore it.)

    • seenAt date-time nullable

      When the token was last seen/used to authenticate with. null if it has not been used yet. (This property is set by Unleash when the token is created and cannot be set manually: if you provide a value when creating a PAT, Unleash will ignore it.)

    Responses

    The resource was successfully created.

    Response Headers
    • location string

      The location of the newly created resource.

    Schema
    • id integer

      Possible values: >= 1

      The unique identification number for this Personal Access Token. (This property is set by Unleash when the token is created and cannot be set manually: if you provide a value when creating a PAT, Unleash will ignore it.)

    • secret string

      The token used for authentication. (This property is set by Unleash when the token is created and cannot be set manually: if you provide a value when creating a PAT, Unleash will ignore it.)

    • expiresAt date-time

      The token's expiration date.

    • createdAt date-time

      When the token was created. (This property is set by Unleash when the token is created and cannot be set manually: if you provide a value when creating a PAT, Unleash will ignore it.)

    • seenAt date-time nullable

      When the token was last seen/used to authenticate with. null if it has not been used yet. (This property is set by Unleash when the token is created and cannot be set manually: if you provide a value when creating a PAT, Unleash will ignore it.)

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/create-service-account.html b/reference/api/unleash/create-service-account.html index 42bab01b30..93a4a6a78f 100644 --- a/reference/api/unleash/create-service-account.html +++ b/reference/api/unleash/create-service-account.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Create a service account.

    POST /api/admin/service-account

    Creates a new service account.

    Request​

    Body

    required

    createServiceAccountSchema

    • username string

      The username of the service account

    • name string

      The name of the service account

    • rootRole integer required

      The id of the root role for the service account

    Responses

    The resource was successfully created.

    Response Headers
    • location string

      The location of the newly created resource.

    Schema
    • id number required

      The service account id

    • isAPI boolean deprecated

      Deprecated: for internal use only, should not be exposed through the API

    • name string

      The name of the service account

    • email string deprecated

      Deprecated: service accounts don't have emails associated with them

    • username string

      The service account username

    • imageUrl string

      The service account image url

    • inviteLink string deprecated

      Deprecated: service accounts cannot be invited via an invitation link

    • loginAttempts number deprecated

      Deprecated: service accounts cannot log in to Unleash

    • emailSent boolean deprecated

      Deprecated: internal use only

    • rootRole integer

      The root role id associated with the service account

    • seenAt date-time nullable deprecated

      Deprecated. This property is always null. To find out when a service account was last seen, check its tokens list and refer to each token's lastSeen property instead.

    • createdAt date-time

      The service account creation date

    • tokens object[]

      The list of tokens associated with the service account

    • Array [
    • id integer

      Possible values: >= 1

      The unique identification number for this Personal Access Token. (This property is set by Unleash when the token is created and cannot be set manually: if you provide a value when creating a PAT, Unleash will ignore it.)

    • secret string

      The token used for authentication. (This property is set by Unleash when the token is created and cannot be set manually: if you provide a value when creating a PAT, Unleash will ignore it.)

    • expiresAt date-time

      The token's expiration date.

    • createdAt date-time

      When the token was created. (This property is set by Unleash when the token is created and cannot be set manually: if you provide a value when creating a PAT, Unleash will ignore it.)

    • seenAt date-time nullable

      When the token was last seen/used to authenticate with. null if it has not been used yet. (This property is set by Unleash when the token is created and cannot be set manually: if you provide a value when creating a PAT, Unleash will ignore it.)

    • ]
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/create-strategy.html b/reference/api/unleash/create-strategy.html index 930d612803..1ebb780c62 100644 --- a/reference/api/unleash/create-strategy.html +++ b/reference/api/unleash/create-strategy.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Create a strategy

    POST /api/admin/strategies

    Creates a strategy type based on the supplied data.

    Request​

    Body

    required

    createStrategySchema

    • name string required

      The name of the strategy type. Must be unique.

    • title string

      The title of the strategy

    • description string

      A description of the strategy type.

    • editable boolean

      Whether the strategy type is editable or not. Defaults to true.

    • deprecated boolean

      Whether the strategy type is deprecated or not. Defaults to false.

    • parameters object[]required

      The parameter list lets you pass arguments to your custom activation strategy. These will be made available to your custom strategy implementation.

    • Array [
    • name string required

      The name of the parameter

    • type string required

      Possible values: [string, percentage, list, number, boolean]

    • description string

      A description of this strategy parameter. Use this to indicate to the users what the parameter does.

    • required boolean

      Whether this parameter must be configured when using the strategy. Defaults to false

    • ]
    Responses

    The resource was successfully created.

    Response Headers
    • location string

      The location of the newly created resource.

    Schema
    • title string nullable

      An optional title for the strategy

    • name string required

      The name (type) of the strategy

    • displayName string nullable required

      A human friendly name for the strategy

    • description string nullable required

      A short description of the strategy

    • editable boolean required

      Whether the strategy can be edited or not. Strategies bundled with Unleash cannot be edited.

    • deprecated boolean required
    • parameters object[]required

      A list of relevant parameters for each strategy

    • Array [
    • name string
    • type string
    • description string
    • required boolean
    • ]
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/create-tag-type.html b/reference/api/unleash/create-tag-type.html index c05f78a870..c491541383 100644 --- a/reference/api/unleash/create-tag-type.html +++ b/reference/api/unleash/create-tag-type.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Create a tag type

    POST /api/admin/tag-types

    Create a new tag type.

    Request​

    Body

    required

    tagTypeSchema

    • name string required

      The name of the tag type.

    • description string

      The description of the tag type.

    • icon string nullable

      The icon of the tag type.

    Responses

    The resource was successfully created.

    Response Headers
    • location string

      The location of the newly created resource.

    Schema
    • name string required

      The name of the tag type.

    • description string

      The description of the tag type.

    • icon string nullable

      The icon of the tag type.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/create-tag.html b/reference/api/unleash/create-tag.html index 5f6b08682d..3aaf29fffd 100644 --- a/reference/api/unleash/create-tag.html +++ b/reference/api/unleash/create-tag.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Create a new tag.

    POST /api/admin/tags

    Create a new tag with the specified data.

    Request​

    Body

    required

    tagSchema

    • value string required

      Possible values: >= 2 characters and <= 50 characters

      The value of the tag

    • type string required

      Possible values: >= 2 characters and <= 50 characters

      Default value: simple

      The type of the tag

    Responses

    The resource was successfully created.

    Response Headers
    • location string

      The location of the newly created resource.

    Schema
    • version integer required

      The version of the schema used to model the tag.

    • tag objectrequired

      Representation of a tag

    • value string required

      Possible values: >= 2 characters and <= 50 characters

      The value of the tag

    • type string required

      Possible values: >= 2 characters and <= 50 characters

      Default value: simple

      The type of the tag

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/create-user.html b/reference/api/unleash/create-user.html index 862cf0412d..a8b897fae1 100644 --- a/reference/api/unleash/create-user.html +++ b/reference/api/unleash/create-user.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Create a new user

    POST /api/admin/user-admin

    Creates a new user with the given root role.

    Request​

    Body

    required

    createUserSchema

    • username string

      The user's username. Must be provided if email is not provided.

    • email string

      The user's email address. Must be provided if username is not provided.

    • name string

      The user's name (not the user's username).

    • password string

      Password for the user

    • rootRole objectrequired

      The role to assign to the user. Can be either the role's ID or its unique name.

      oneOf
    • integer
    • sendEmail boolean

      Whether to send a welcome email with a login link to the user or not. Defaults to true.

    Responses

    The resource was successfully created.

    Response Headers
    • location string

      The location of the newly created resource.

    Schema
    • id integer required

      The user id

    • isAPI boolean deprecated

      (Deprecated): Used internally to know which operations the user should be allowed to perform

    • name string nullable

      Name of the user

    • email string

      Email of the user

    • username string nullable

      A unique username for the user

    • imageUrl string

      URL used for the userprofile image

    • inviteLink string

      If the user is actively inviting other users, this is the link that can be shared with other users

    • loginAttempts integer

      How many unsuccessful attempts at logging in has the user made

    • emailSent boolean

      Is the welcome email sent to the user or not

    • rootRole object

      Which root role this user is assigned. Usually a numeric role ID, but can be a string when returning newly created user with an explicit string role.

      oneOf
    • integer
    • seenAt date-time nullable

      The last time this user logged in

    • createdAt date-time

      The user was created at this time

    • accountType string

      A user is either an actual User or a Service Account

    • permissions string[]

      Deprecated

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/delete-addon.html b/reference/api/unleash/delete-addon.html index 89dd5acace..d3919b277e 100644 --- a/reference/api/unleash/delete-addon.html +++ b/reference/api/unleash/delete-addon.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Delete an addon

    DELETE /api/admin/addons/:id

    Delete the addon specified by the ID in the request path.

    Request​

    Path Parameters

    • id string required
    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/delete-api-token.html b/reference/api/unleash/delete-api-token.html index da2d732733..079bc7ce38 100644 --- a/reference/api/unleash/delete-api-token.html +++ b/reference/api/unleash/delete-api-token.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Delete API token

    DELETE /api/admin/api-tokens/:token

    Deletes an existing API token. The token path parameter is the token's secret. If the token does not exist, this endpoint returns a 200 OK, but does nothing.

    Request​

    Path Parameters

    • token string required
    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/delete-application.html b/reference/api/unleash/delete-application.html index 6a3c6bb784..2601454c42 100644 --- a/reference/api/unleash/delete-application.html +++ b/reference/api/unleash/delete-application.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Delete an application

    DELETE /api/admin/metrics/applications/:appName

    Delete the application specified in the request URL. Returns 200 OK if the application was successfully deleted or if it didn't exist

    Request​

    Path Parameters

    • appName string required
    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/delete-banner.html b/reference/api/unleash/delete-banner.html index c7efeb3512..aa1de26d79 100644 --- a/reference/api/unleash/delete-banner.html +++ b/reference/api/unleash/delete-banner.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Delete a banner.

    DELETE /api/admin/banners/:id

    Deletes an existing banner identified by its id.

    Request​

    Path Parameters

    • id string required
    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/delete-change-request.html b/reference/api/unleash/delete-change-request.html index 1d698eb964..526b9108d3 100644 --- a/reference/api/unleash/delete-change-request.html +++ b/reference/api/unleash/delete-change-request.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Deletes a change request by id

    DELETE /api/admin/projects/:projectId/change-requests/:id

    This endpoint will delete one change request if it matches the provided id.

    Request​

    Path Parameters

    • projectId string required
    • id string required
    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/delete-change.html b/reference/api/unleash/delete-change.html index c6f5a67af0..2e1dc3e628 100644 --- a/reference/api/unleash/delete-change.html +++ b/reference/api/unleash/delete-change.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Discards a change from a change request by change id

    DELETE /api/admin/projects/:projectId/change-requests/:changeRequestId/changes/:changeId

    This endpoint will discard one change from a change request if it matches the provided id.

    Request​

    Path Parameters

    • projectId string required
    • changeRequestId string required
    • changeId string required
    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/delete-context-field.html b/reference/api/unleash/delete-context-field.html index 455d109e4f..0cb6839096 100644 --- a/reference/api/unleash/delete-context-field.html +++ b/reference/api/unleash/delete-context-field.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Delete an existing context field

    DELETE /api/admin/context/:contextField

    Endpoint that allows deletion of a custom context field. Does not validate that context field is not in use, but since context field configuration is stored in a json blob for the strategy, existing strategies are safe.

    Request​

    Path Parameters

    • contextField string required
    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/delete-feature-dependencies.html b/reference/api/unleash/delete-feature-dependencies.html index be0ea85942..d05efa73b3 100644 --- a/reference/api/unleash/delete-feature-dependencies.html +++ b/reference/api/unleash/delete-feature-dependencies.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Deletes feature dependencies.

    DELETE /api/admin/projects/:projectId/features/:child/dependencies

    Remove dependencies to all parent features.

    Request​

    Path Parameters

    • projectId string required
    • child string required
    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/delete-feature-dependency.html b/reference/api/unleash/delete-feature-dependency.html index 4663e2da5a..8ac7991826 100644 --- a/reference/api/unleash/delete-feature-dependency.html +++ b/reference/api/unleash/delete-feature-dependency.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Deletes a feature dependency.

    DELETE /api/admin/projects/:projectId/features/:child/dependencies/:parent

    Remove a dependency to a parent feature.

    Request​

    Path Parameters

    • projectId string required
    • child string required
    • parent string required
    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/delete-feature-strategy.html b/reference/api/unleash/delete-feature-strategy.html index ea9fea646f..73065ba997 100644 --- a/reference/api/unleash/delete-feature-strategy.html +++ b/reference/api/unleash/delete-feature-strategy.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Delete a strategy from a feature toggle

    DELETE /api/admin/projects/:projectId/features/:featureName/environments/:environment/strategies/:strategyId

    Delete a strategy configuration from a feature toggle in the specified environment.

    Request​

    Path Parameters

    • projectId string required
    • featureName string required
    • environment string required
    • strategyId string required
    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/delete-feature.html b/reference/api/unleash/delete-feature.html index 27e834c602..63fd660a32 100644 --- a/reference/api/unleash/delete-feature.html +++ b/reference/api/unleash/delete-feature.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Archives a feature

    DELETE /api/admin/archive/:featureName

    This endpoint archives the specified feature.

    Request​

    Path Parameters

    • featureName string required
    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/delete-features.html b/reference/api/unleash/delete-features.html index 7d4e8f51d1..13b98e7643 100644 --- a/reference/api/unleash/delete-features.html +++ b/reference/api/unleash/delete-features.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Deletes a list of features

    POST /api/admin/projects/:projectId/delete

    This endpoint deletes the specified features, that are in archive.

    Request​

    Path Parameters

    • projectId string required

    Body

    required

    batchFeaturesSchema

    • features string[] required

      List of feature toggle names

    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/delete-group.html b/reference/api/unleash/delete-group.html index 27f08029f6..25fa2b13e6 100644 --- a/reference/api/unleash/delete-group.html +++ b/reference/api/unleash/delete-group.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Delete a single group

    DELETE /api/admin/groups/:groupId

    Delete a single user group by group id

    Request​

    Path Parameters

    • groupId string required
    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/delete-pat.html b/reference/api/unleash/delete-pat.html index 8ca8406edc..17aa54d7ee 100644 --- a/reference/api/unleash/delete-pat.html +++ b/reference/api/unleash/delete-pat.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Delete a Personal Access Token.

    DELETE /api/admin/user/tokens/:id

    This endpoint allows for deleting a Personal Access Token belonging to the current user.

    Request​

    Path Parameters

    • id string required
    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/delete-project-api-token.html b/reference/api/unleash/delete-project-api-token.html index 11ed0d2491..5879cfaa26 100644 --- a/reference/api/unleash/delete-project-api-token.html +++ b/reference/api/unleash/delete-project-api-token.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Delete a project API token.

    DELETE /api/admin/projects/:projectId/api-tokens/:token

    This operation deletes the API token specified in the request URL. If the token doesn't exist, returns an OK response (status code 200).

    Request​

    Path Parameters

    • projectId string required
    • token string required
    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/delete-project.html b/reference/api/unleash/delete-project.html index cc12f3f5c0..049273d75e 100644 --- a/reference/api/unleash/delete-project.html +++ b/reference/api/unleash/delete-project.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Delete project

    DELETE /api/admin/projects/:projectId

    Permanently delete the provided project. All feature toggles in the project must be archived before you can delete it. This permanently deletes the project and its archived toggles. It can not be undone.

    Request​

    Path Parameters

    • projectId string required
    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/delete-role.html b/reference/api/unleash/delete-role.html index 6de9d500ef..279aa6831e 100644 --- a/reference/api/unleash/delete-role.html +++ b/reference/api/unleash/delete-role.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Delete a custom role

    DELETE /api/admin/roles/:roleId

    Delete a custom role by id. You cannot delete built-in roles or roles that are in use.

    Request​

    Path Parameters

    • roleId string required
    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/delete-service-account-token.html b/reference/api/unleash/delete-service-account-token.html index 0550646eeb..d0a2ad6aab 100644 --- a/reference/api/unleash/delete-service-account-token.html +++ b/reference/api/unleash/delete-service-account-token.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Delete a token for a service account.

    DELETE /api/admin/service-account/:id/token/:tokenId

    Deletes a token for the service account identified both by the service account's id and the token's id.

    Request​

    Path Parameters

    • id string required
    • tokenId string required
    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/delete-service-account.html b/reference/api/unleash/delete-service-account.html index a45890c1be..7090e52af9 100644 --- a/reference/api/unleash/delete-service-account.html +++ b/reference/api/unleash/delete-service-account.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Delete a service account.

    DELETE /api/admin/service-account/:id

    Deletes an existing service account identified by its id.

    Request​

    Path Parameters

    • id string required
    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/delete-tag-type.html b/reference/api/unleash/delete-tag-type.html index 38fd1d901b..f177249d79 100644 --- a/reference/api/unleash/delete-tag-type.html +++ b/reference/api/unleash/delete-tag-type.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Delete a tag type

    DELETE /api/admin/tag-types/:name

    Deletes a tag type. If any features have tags of this type, those tags will be deleted.

    Request​

    Path Parameters

    • name string required
    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/delete-tag.html b/reference/api/unleash/delete-tag.html index 2082193cce..0b0e4db5ca 100644 --- a/reference/api/unleash/delete-tag.html +++ b/reference/api/unleash/delete-tag.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Delete a tag.

    DELETE /api/admin/tags/:type/:value

    Delete a tag by type and value. When a tag is deleted all references to the tag are removed.

    Request​

    Path Parameters

    • type string required
    • value string required
    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/delete-user.html b/reference/api/unleash/delete-user.html index 1ad5d9e31f..43598affcf 100644 --- a/reference/api/unleash/delete-user.html +++ b/reference/api/unleash/delete-user.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Delete a user

    DELETE /api/admin/user-admin/:id

    Deletes the user with the given userId

    Request​

    Path Parameters

    • id string required
    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/dependencies.html b/reference/api/unleash/dependencies.html index d53c9b747a..3d3fc4f83a 100644 --- a/reference/api/unleash/dependencies.html +++ b/reference/api/unleash/dependencies.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Dependencies

    Manage feature dependencies.

    - + \ No newline at end of file diff --git a/reference/api/unleash/deprecate-strategy.html b/reference/api/unleash/deprecate-strategy.html index 30ed549a51..6782cf43f4 100644 --- a/reference/api/unleash/deprecate-strategy.html +++ b/reference/api/unleash/deprecate-strategy.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Deprecate a strategy

    POST /api/admin/strategies/:strategyName/deprecate

    Marks the specified strategy as deprecated.

    Request​

    Path Parameters

    • strategyName string required
    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/disable-banner.html b/reference/api/unleash/disable-banner.html index 00a9f87b82..cc6176e35c 100644 --- a/reference/api/unleash/disable-banner.html +++ b/reference/api/unleash/disable-banner.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Disables a banner.

    POST /api/admin/banners/:id/off

    Disables an existing banner, identified by its id.

    Request​

    Path Parameters

    • id string required
    Responses

    bannerSchema

    Schema
    • id integer required

      Possible values: >= 1

      The banner's ID. Banner IDs are incrementing integers. In other words, a more recently created banner will always have a higher ID than an older one.

    • message string required

      The message to display to all users. Supports markdown.

    • enabled boolean

      Whether the banner should be displayed currently. If not specified, defaults to true.

    • variant string

      The variant of the banner. One of "info", "warning", "error", or "success". If not specified, defaults to "info".

    • sticky boolean

      Whether the banner should be sticky on the screen. If not specified, defaults to false.

    • icon string nullable

      The icon to display on the banner. Can be one of https://fonts.google.com/icons. If not specified, this will be the default icon for the variant. If "none", no icon will be displayed.

    • link string nullable

      The link to display on the banner. Can either be an absolute or a relative link (e.g. absolute: "https://example.com" or relative: "/admin/service-accounts"). If "dialog", will display a dialog when clicked. If not specified, no link will be displayed.

    • linkText string nullable

      The text to display on the link. If not specified, will be displayed as "More info".

    • dialogTitle string nullable

      The title to display on the dialog. If not specified, this will be the same as linkText.

    • dialog string nullable

      The markdown to display on the dialog. If not specified, no dialog will be displayed.

    • createdAt date-time required

      The date and time of when the banner was created.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/edge.html b/reference/api/unleash/edge.html index 2aa59e083b..4a1db47b66 100644 --- a/reference/api/unleash/edge.html +++ b/reference/api/unleash/edge.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content
    - + \ No newline at end of file diff --git a/reference/api/unleash/edit-change.html b/reference/api/unleash/edit-change.html index 5a6e374a96..fff248e436 100644 --- a/reference/api/unleash/edit-change.html +++ b/reference/api/unleash/edit-change.html @@ -20,7 +20,7 @@ - + @@ -29,7 +29,7 @@
    Skip to main content

    Edits a single change in a change request

    PUT /api/admin/projects/:projectId/change-requests/:changeRequestId/changes/:changeId

    This endpoint will edit one change from a change request if it matches the provided id. The edit removes previous change and inserts a new one. You should not rely on the changeId for subsequent edits and always check the most recent changeId.

    Request​

    Path Parameters

    • projectId string required
    • changeRequestId string required
    • changeId string required

    Body

    required

    changeRequestCreateSchema

      oneOf
    • action string required

      Possible values: [updateSegment]

      The name of this action.

    • payload objectrequired

      Data used to create or update a segment

    • id integer required

      The ID of the segment to update.

    Responses

    changeRequestSchema

    Schema
      oneOf
    • id number required

      This change requests's ID.

    • title string

      A title describing the change request's content.

    • environment string required

      The environment in which the changes should be applied.

    • minApprovals number required

      The minimum number of approvals required before this change request can be applied.

    • project string required

      The project this change request belongs to.

    • features object[]required

      The list of features and their changes that relate to this change request.

    • Array [
    • name string required

      The name of the feature

    • conflict string

      A string describing the conflicts related to this change. Only present if there are any concflicts on the feature level.

    • changes object[]required

      List of changes inside change request. This list may be empty when listing all change requests for a project.

    • Array [
    • id number required

      The ID of this change.

    • action string required

      The kind of action that the change contains information about.

    • conflict string

      A description of the conflict caused by this change. Only present if there are any conflicts.

    • payload objectrequired

      The data required to perform this action.

      oneOf
    • string
    • createdBy object

      The user who created this change.

    • username string nullable

      The user's username.

    • imageUrl uri nullable

      The URL where the user's image can be found.

    • createdAt date-time

      When this change was suggested

    • ]
    • defaultChange object

      A description of a default change that will be applied with the change request to prevent invalid states.

      Default changes are changes that are applied in addition to explicit user-specified changes when a change request is applied. Any default changes are applied in the background and are not a real part of the change request.

    • action string required

      The kind of action this is.

    • payload object required

      The necessary data to perform this change.

    • ]
    • segments object[]required

      The list of segments and their changes that relate to this change request.

    • Array [
    • id number required

      The ID of this change.

    • action string required

      The kind of action that the change contains information about.

    • conflict string

      A description of the conflict caused by this change. Only present if there are any conflicts.

    • payload objectrequired

      The data required to perform this action.

      oneOf
    • string
    • createdBy object

      The user who created this change.

    • username string nullable

      The user's username.

    • imageUrl uri nullable

      The URL where the user's image can be found.

    • createdAt date-time

      When this change was suggested

    • name string required

      The current name of the segment

    • ]
    • approvals object[]

      A list of approvals that this change request has received.

    • Array [
    • createdBy objectrequired

      Information about the user who gave this approval.

    • id number

      The ID of the user who gave this approval.

    • username string

      The approving user's username.

    • imageUrl uri

      The URL where the user's image can be found.

    • createdAt date-time required

      When the approval was given.

    • ]
    • rejections object[]

      A list of rejections that this change request has received.

    • Array [
    • createdBy objectrequired

      Information about the user who gave this approval.

    • id number

      The ID of the user who gave this approval.

    • username string

      The approving user's username.

    • imageUrl uri

      The URL where the user's image can be found.

    • createdAt date-time required

      When the approval was given.

    • ]
    • comments object[]

      All comments that have been made on this change request.

    • Array [
    • id number

      The comment's ID. Unique per change request.

    • text string required

      The content of the comment.

    • createdBy objectrequired

      Information about the user who posted the comment

    • username string nullable

      The user's username.

    • imageUrl uri nullable

      The URL where the user's image can be found.

    • createdAt date-time required

      When the comment was made.

    • ]
    • createdBy objectrequired

      The user who created this change request.

    • username string nullable
    • imageUrl uri nullable

      The URL of the user's profile image.

    • createdAt date-time required

      When this change request was created.

    • state string required

      Possible values: [Draft, In review, Approved, Applied, Cancelled, Rejected]

      The current state of the change request.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/enable-banner.html b/reference/api/unleash/enable-banner.html index 547790e604..2069147192 100644 --- a/reference/api/unleash/enable-banner.html +++ b/reference/api/unleash/enable-banner.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Enables a banner.

    POST /api/admin/banners/:id/on

    Enables an existing banner, identified by its id.

    Request​

    Path Parameters

    • id string required
    Responses

    bannerSchema

    Schema
    • id integer required

      Possible values: >= 1

      The banner's ID. Banner IDs are incrementing integers. In other words, a more recently created banner will always have a higher ID than an older one.

    • message string required

      The message to display to all users. Supports markdown.

    • enabled boolean

      Whether the banner should be displayed currently. If not specified, defaults to true.

    • variant string

      The variant of the banner. One of "info", "warning", "error", or "success". If not specified, defaults to "info".

    • sticky boolean

      Whether the banner should be sticky on the screen. If not specified, defaults to false.

    • icon string nullable

      The icon to display on the banner. Can be one of https://fonts.google.com/icons. If not specified, this will be the default icon for the variant. If "none", no icon will be displayed.

    • link string nullable

      The link to display on the banner. Can either be an absolute or a relative link (e.g. absolute: "https://example.com" or relative: "/admin/service-accounts"). If "dialog", will display a dialog when clicked. If not specified, no link will be displayed.

    • linkText string nullable

      The text to display on the link. If not specified, will be displayed as "More info".

    • dialogTitle string nullable

      The title to display on the dialog. If not specified, this will be the same as linkText.

    • dialog string nullable

      The markdown to display on the dialog. If not specified, no dialog will be displayed.

    • createdAt date-time required

      The date and time of when the banner was created.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/environments.html b/reference/api/unleash/environments.html index dd5c233140..36681db174 100644 --- a/reference/api/unleash/environments.html +++ b/reference/api/unleash/environments.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Environments

    Create, update, delete, enable or disable environments for this Unleash instance.

    - + \ No newline at end of file diff --git a/reference/api/unleash/events.html b/reference/api/unleash/events.html index ec0203fbda..44cbd90423 100644 --- a/reference/api/unleash/events.html +++ b/reference/api/unleash/events.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Events

    Read events from this Unleash instance.

    - + \ No newline at end of file diff --git a/reference/api/unleash/export-features.html b/reference/api/unleash/export-features.html index 1b522b942c..da55493e69 100644 --- a/reference/api/unleash/export-features.html +++ b/reference/api/unleash/export-features.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Export feature toggles from an environment

    POST /api/admin/features-batch/export

    Exports all features listed in the features property from the environment specified in the request body. If set to true, the downloadFile property will let you download a file with the exported data. Otherwise, the export data is returned directly as JSON. Refer to the documentation for more information about Unleash's export functionality.

    Request​

    Body

    required

    exportQuerySchema

      anyOf
    • environment string required

      The environment to export from

    • downloadFile boolean

      Whether to return a downloadable file

    • features string[] required

      Possible values: non-empty

      Selects features to export by name. If the list is empty all features are returned.

    Responses

    exportResultSchema

    Schema
    • features object[]required

      All the exported features.

    • Array [
    • name string required

      Unique feature name

    • type string

      Type of the toggle e.g. experiment, kill-switch, release, operational, permission

    • description string nullable

      Detailed description of the feature

    • archived boolean

      true if the feature is archived

    • project string

      Name of the project the feature belongs to

    • enabled boolean

      true if the feature is enabled, otherwise false.

    • stale boolean

      true if the feature is stale based on the age and feature type, otherwise false.

    • favorite boolean

      true if the feature was favorited, otherwise false.

    • impressionData boolean

      true if the impression data collection is enabled for the feature, otherwise false.

    • createdAt date-time nullable

      The date the feature was created

    • archivedAt date-time nullable

      The date the feature was archived

    • lastSeenAt date-time nullable deprecated

      The date when metrics where last collected for the feature. This field is deprecated, use the one in featureEnvironmentSchema

    • environments object[]

      The list of environments where the feature can be used

    • Array [
    • name string required

      The name of the environment

    • featureName string

      The name of the feature

    • environment string

      The name of the environment

    • type string

      The type of the environment

    • enabled boolean required

      true if the feature is enabled for the environment, otherwise false.

    • sortOrder number

      The sort order of the feature environment in the feature environments list

    • variantCount number

      The number of defined variants

    • strategies object[]

      A list of activation strategies for the feature environment

    • Array [
    • id string

      A uuid for the feature strategy

    • name string required

      The name or type of strategy

    • title string nullable

      A descriptive title for the strategy

    • disabled boolean nullable

      A toggle to disable the strategy. defaults to false. Disabled strategies are not evaluated or returned to the SDKs

    • featureName string

      The name or feature the strategy is attached to

    • sortOrder number

      The order of the strategy in the list

    • segments number[]

      A list of segment ids attached to the strategy

    • constraints object[]

      A list of the constraints attached to the strategy. See https://docs.getunleash.io/reference/strategy-constraints

    • Array [
    • contextName string required

      The name of the context field that this constraint should apply to.

    • operator string required

      Possible values: [NOT_IN, IN, STR_ENDS_WITH, STR_STARTS_WITH, STR_CONTAINS, NUM_EQ, NUM_GT, NUM_GTE, NUM_LT, NUM_LTE, DATE_AFTER, DATE_BEFORE, SEMVER_EQ, SEMVER_GT, SEMVER_LT]

      The operator to use when evaluating this constraint. For more information about the various operators, refer to the strategy constraint operator documentation.

    • caseInsensitive boolean

      Default value: false

      Whether the operator should be case sensitive or not. Defaults to false (being case sensitive).

    • inverted boolean

      Default value: false

      Whether the result should be negated or not. If true, will turn a true result into a false result and vice versa.

    • values string[]

      The context values that should be used for constraint evaluation. Use this property instead of value for properties that accept multiple values.

    • value string

      The context value that should be used for constraint evaluation. Use this property instead of values for properties that only accept single values.

    • ]
    • variants object[]

      Strategy level variants

    • Array [
    • name string required

      The variant name. Must be unique for this feature toggle

    • weight integer required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is an integer between 0 and 1000. See the section on variant weights for more information

    • weightType string required

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000. Refer to the variant weight documentation.

    • stickiness string required

      The stickiness to use for distribution of this variant. Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • ]
    • parameters object

      A list of parameters for a strategy

    • property name* string
    • ]
    • variants object[]

      A list of variants for the feature environment

    • Array [
    • name string required

      The variants name. Is unique for this feature toggle

    • weight number required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is a number between 0 and 1000. See the section on variant weights for more information

    • weightType string

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000

    • stickiness string

      Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • overrides object[]

      Overrides assigning specific variants to specific users. The weighting system automatically assigns users to specific groups for you, but any overrides in this list will take precedence.

    • Array [
    • contextName string required

      The name of the context field used to determine overrides

    • values string[] required

      Which values that should be overriden

    • ]
    • ]
    • lastSeenAt date-time nullable

      The date when metrics where last collected for the feature environment

    • hasStrategies boolean

      Whether the feature has any strategies defined.

    • hasEnabledStrategies boolean

      Whether the feature has any enabled strategies defined.

    • ]
    • variants object[]deprecated

      The list of feature variants

    • Array [
    • name string required

      The variants name. Is unique for this feature toggle

    • weight number required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is a number between 0 and 1000. See the section on variant weights for more information

    • weightType string

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000

    • stickiness string

      Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • overrides object[]

      Overrides assigning specific variants to specific users. The weighting system automatically assigns users to specific groups for you, but any overrides in this list will take precedence.

    • Array [
    • contextName string required

      The name of the context field used to determine overrides

    • values string[] required

      Which values that should be overriden

    • ]
    • ]
    • strategies object[] deprecated

      This is a legacy field that will be deprecated

    • tags object[]nullable

      The list of feature tags

    • Array [
    • value string required

      Possible values: >= 2 characters and <= 50 characters

      The value of the tag

    • type string required

      Possible values: >= 2 characters and <= 50 characters

      Default value: simple

      The type of the tag

    • ]
    • children string[]

      The list of child feature names. This is an experimental field and may change.

    • dependencies object[]

      The list of parent dependencies. This is an experimental field and may change.

    • Array [
    • feature string required

      The name of the parent feature

    • enabled boolean

      Whether the parent feature is enabled or not

    • variants string[]

      The list of variants the parent feature should resolve to. Only valid when feature is enabled.

    • ]
    • ]
    • featureStrategies object[]required

      All strategy instances that are used by the exported features in the features list.

    • Array [
    • id string

      A uuid for the feature strategy

    • name string required

      The name or type of strategy

    • title string nullable

      A descriptive title for the strategy

    • disabled boolean nullable

      A toggle to disable the strategy. defaults to false. Disabled strategies are not evaluated or returned to the SDKs

    • featureName string

      The name or feature the strategy is attached to

    • sortOrder number

      The order of the strategy in the list

    • segments number[]

      A list of segment ids attached to the strategy

    • constraints object[]

      A list of the constraints attached to the strategy. See https://docs.getunleash.io/reference/strategy-constraints

    • Array [
    • contextName string required

      The name of the context field that this constraint should apply to.

    • operator string required

      Possible values: [NOT_IN, IN, STR_ENDS_WITH, STR_STARTS_WITH, STR_CONTAINS, NUM_EQ, NUM_GT, NUM_GTE, NUM_LT, NUM_LTE, DATE_AFTER, DATE_BEFORE, SEMVER_EQ, SEMVER_GT, SEMVER_LT]

      The operator to use when evaluating this constraint. For more information about the various operators, refer to the strategy constraint operator documentation.

    • caseInsensitive boolean

      Default value: false

      Whether the operator should be case sensitive or not. Defaults to false (being case sensitive).

    • inverted boolean

      Default value: false

      Whether the result should be negated or not. If true, will turn a true result into a false result and vice versa.

    • values string[]

      The context values that should be used for constraint evaluation. Use this property instead of value for properties that accept multiple values.

    • value string

      The context value that should be used for constraint evaluation. Use this property instead of values for properties that only accept single values.

    • ]
    • variants object[]

      Strategy level variants

    • Array [
    • name string required

      The variant name. Must be unique for this feature toggle

    • weight integer required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is an integer between 0 and 1000. See the section on variant weights for more information

    • weightType string required

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000. Refer to the variant weight documentation.

    • stickiness string required

      The stickiness to use for distribution of this variant. Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • ]
    • parameters object

      A list of parameters for a strategy

    • property name* string
    • ]
    • featureEnvironments object[]

      Environment-specific configuration for all the features in the features list. Includes data such as whether the feature is enabled in the selected export environment, whether there are any variants assigned, etc.

    • Array [
    • name string required

      The name of the environment

    • featureName string

      The name of the feature

    • environment string

      The name of the environment

    • type string

      The type of the environment

    • enabled boolean required

      true if the feature is enabled for the environment, otherwise false.

    • sortOrder number

      The sort order of the feature environment in the feature environments list

    • variantCount number

      The number of defined variants

    • strategies object[]

      A list of activation strategies for the feature environment

    • Array [
    • id string

      A uuid for the feature strategy

    • name string required

      The name or type of strategy

    • title string nullable

      A descriptive title for the strategy

    • disabled boolean nullable

      A toggle to disable the strategy. defaults to false. Disabled strategies are not evaluated or returned to the SDKs

    • featureName string

      The name or feature the strategy is attached to

    • sortOrder number

      The order of the strategy in the list

    • segments number[]

      A list of segment ids attached to the strategy

    • constraints object[]

      A list of the constraints attached to the strategy. See https://docs.getunleash.io/reference/strategy-constraints

    • Array [
    • contextName string required

      The name of the context field that this constraint should apply to.

    • operator string required

      Possible values: [NOT_IN, IN, STR_ENDS_WITH, STR_STARTS_WITH, STR_CONTAINS, NUM_EQ, NUM_GT, NUM_GTE, NUM_LT, NUM_LTE, DATE_AFTER, DATE_BEFORE, SEMVER_EQ, SEMVER_GT, SEMVER_LT]

      The operator to use when evaluating this constraint. For more information about the various operators, refer to the strategy constraint operator documentation.

    • caseInsensitive boolean

      Default value: false

      Whether the operator should be case sensitive or not. Defaults to false (being case sensitive).

    • inverted boolean

      Default value: false

      Whether the result should be negated or not. If true, will turn a true result into a false result and vice versa.

    • values string[]

      The context values that should be used for constraint evaluation. Use this property instead of value for properties that accept multiple values.

    • value string

      The context value that should be used for constraint evaluation. Use this property instead of values for properties that only accept single values.

    • ]
    • variants object[]

      Strategy level variants

    • Array [
    • name string required

      The variant name. Must be unique for this feature toggle

    • weight integer required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is an integer between 0 and 1000. See the section on variant weights for more information

    • weightType string required

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000. Refer to the variant weight documentation.

    • stickiness string required

      The stickiness to use for distribution of this variant. Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • ]
    • parameters object

      A list of parameters for a strategy

    • property name* string
    • ]
    • variants object[]

      A list of variants for the feature environment

    • Array [
    • name string required

      The variants name. Is unique for this feature toggle

    • weight number required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is a number between 0 and 1000. See the section on variant weights for more information

    • weightType string

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000

    • stickiness string

      Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • overrides object[]

      Overrides assigning specific variants to specific users. The weighting system automatically assigns users to specific groups for you, but any overrides in this list will take precedence.

    • Array [
    • contextName string required

      The name of the context field used to determine overrides

    • values string[] required

      Which values that should be overriden

    • ]
    • ]
    • lastSeenAt date-time nullable

      The date when metrics where last collected for the feature environment

    • hasStrategies boolean

      Whether the feature has any strategies defined.

    • hasEnabledStrategies boolean

      Whether the feature has any enabled strategies defined.

    • ]
    • contextFields object[]

      A list of all the context fields that are in use by any of the strategies in the featureStrategies list.

    • Array [
    • name string required

      The name of the context field

    • description string nullable

      The description of the context field.

    • stickiness boolean

      Does this context field support being used for stickiness calculations

    • sortOrder integer

      Used when sorting a list of context fields. Is also used as a tiebreaker if a list of context fields is sorted alphabetically.

    • createdAt date-time nullable

      When this context field was created

    • usedInFeatures integer nullable

      Number of projects where this context field is used in

    • usedInProjects integer nullable

      Number of projects where this context field is used in

    • legalValues object[]

      Allowed values for this context field schema. Can be used to narrow down accepted input

    • Array [
    • value string required

      The valid value

    • description string

      Describes this specific legal value

    • ]
    • ]
    • featureTags object[]

      A list of all the tags that have been applied to any of the features in the features list.

    • Array [
    • featureName string required

      The name of the feature this tag is applied to

    • tagType string

      The [type](https://docs.getunleash.io/reference/tags#tag-types tag types) of the tag

    • tagValue string required

      The value of the tag

    • type string deprecated

      The [type](https://docs.getunleash.io/reference/tags#tag-types tag types) of the tag. This property is deprecated and will be removed in a future version of Unleash. Superseded by the tagType property.

    • value string deprecated

      The value of the tag. This property is deprecated and will be removed in a future version of Unleash. Superseded by the tagValue property.

    • createdByUserId number nullable

      The id of the user who created this tag

    • ]
    • segments object[]

      A list of all the segments that are used by the strategies in the featureStrategies list.

    • Array [
    • id number required
    • name string required
    • ]
    • tagTypes object[]required

      A list of all of the tag types that are used in the featureTags list.

    • Array [
    • name string required

      The name of the tag type.

    • description string

      The description of the tag type.

    • icon string nullable

      The icon of the tag type.

    • ]
    • dependencies object[]

      A list of all the dependencies for features in features list.

    • Array [
    • feature string required

      The name of the child feature.

    • dependencies object[]required

      List of parent features for the child feature

    • Array [
    • feature string required

      The name of the feature we depend on.

    • enabled boolean

      Whether the parent feature should be enabled. When false variants are ignored. true by default.

    • variants string[]

      The list of variants the parent feature should resolve to. Leave empty when you only want to check the enabled status.

    • ]
    • ]
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/export.html b/reference/api/unleash/export.html index 92b9ce7eb0..ec7f111a44 100644 --- a/reference/api/unleash/export.html +++ b/reference/api/unleash/export.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Export state (deprecated)

    GET /api/admin/state/export
    deprecated

    This endpoint has been deprecated and may be removed in future versions of the API.

    Exports the current state of the system. Deprecated in favor of /api/admin/features-batch/export

    Request​

    Query Parameters

    • format string

      Possible values: [json, yaml]

      Default value: json

      Desired export format. Must be either json or yaml.

    • download any

      Whether exported data should be downloaded as a file.

    • strategies any

      Whether strategies should be included in the exported data.

    • featureToggles any

      Whether feature toggles should be included in the exported data.

    • projects any

      Whether projects should be included in the exported data.

    • tags any

      Whether tag types, tags, and feature_tags should be included in the exported data.

    • environments any

      Whether environments should be included in the exported data.

    Responses

    stateSchema

    Schema
    • version integer required

      The version of the schema used to describe the state

    • features object[]

      A list of features

    • Array [
    • name string required

      Unique feature name

    • type string

      Type of the toggle e.g. experiment, kill-switch, release, operational, permission

    • description string nullable

      Detailed description of the feature

    • archived boolean

      true if the feature is archived

    • project string

      Name of the project the feature belongs to

    • enabled boolean

      true if the feature is enabled, otherwise false.

    • stale boolean

      true if the feature is stale based on the age and feature type, otherwise false.

    • favorite boolean

      true if the feature was favorited, otherwise false.

    • impressionData boolean

      true if the impression data collection is enabled for the feature, otherwise false.

    • createdAt date-time nullable

      The date the feature was created

    • archivedAt date-time nullable

      The date the feature was archived

    • lastSeenAt date-time nullable deprecated

      The date when metrics where last collected for the feature. This field is deprecated, use the one in featureEnvironmentSchema

    • environments object[]

      The list of environments where the feature can be used

    • Array [
    • name string required

      The name of the environment

    • featureName string

      The name of the feature

    • environment string

      The name of the environment

    • type string

      The type of the environment

    • enabled boolean required

      true if the feature is enabled for the environment, otherwise false.

    • sortOrder number

      The sort order of the feature environment in the feature environments list

    • variantCount number

      The number of defined variants

    • strategies object[]

      A list of activation strategies for the feature environment

    • Array [
    • id string

      A uuid for the feature strategy

    • name string required

      The name or type of strategy

    • title string nullable

      A descriptive title for the strategy

    • disabled boolean nullable

      A toggle to disable the strategy. defaults to false. Disabled strategies are not evaluated or returned to the SDKs

    • featureName string

      The name or feature the strategy is attached to

    • sortOrder number

      The order of the strategy in the list

    • segments number[]

      A list of segment ids attached to the strategy

    • constraints object[]

      A list of the constraints attached to the strategy. See https://docs.getunleash.io/reference/strategy-constraints

    • Array [
    • contextName string required

      The name of the context field that this constraint should apply to.

    • operator string required

      Possible values: [NOT_IN, IN, STR_ENDS_WITH, STR_STARTS_WITH, STR_CONTAINS, NUM_EQ, NUM_GT, NUM_GTE, NUM_LT, NUM_LTE, DATE_AFTER, DATE_BEFORE, SEMVER_EQ, SEMVER_GT, SEMVER_LT]

      The operator to use when evaluating this constraint. For more information about the various operators, refer to the strategy constraint operator documentation.

    • caseInsensitive boolean

      Default value: false

      Whether the operator should be case sensitive or not. Defaults to false (being case sensitive).

    • inverted boolean

      Default value: false

      Whether the result should be negated or not. If true, will turn a true result into a false result and vice versa.

    • values string[]

      The context values that should be used for constraint evaluation. Use this property instead of value for properties that accept multiple values.

    • value string

      The context value that should be used for constraint evaluation. Use this property instead of values for properties that only accept single values.

    • ]
    • variants object[]

      Strategy level variants

    • Array [
    • name string required

      The variant name. Must be unique for this feature toggle

    • weight integer required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is an integer between 0 and 1000. See the section on variant weights for more information

    • weightType string required

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000. Refer to the variant weight documentation.

    • stickiness string required

      The stickiness to use for distribution of this variant. Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • ]
    • parameters object

      A list of parameters for a strategy

    • property name* string
    • ]
    • variants object[]

      A list of variants for the feature environment

    • Array [
    • name string required

      The variants name. Is unique for this feature toggle

    • weight number required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is a number between 0 and 1000. See the section on variant weights for more information

    • weightType string

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000

    • stickiness string

      Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • overrides object[]

      Overrides assigning specific variants to specific users. The weighting system automatically assigns users to specific groups for you, but any overrides in this list will take precedence.

    • Array [
    • contextName string required

      The name of the context field used to determine overrides

    • values string[] required

      Which values that should be overriden

    • ]
    • ]
    • lastSeenAt date-time nullable

      The date when metrics where last collected for the feature environment

    • hasStrategies boolean

      Whether the feature has any strategies defined.

    • hasEnabledStrategies boolean

      Whether the feature has any enabled strategies defined.

    • ]
    • variants object[]deprecated

      The list of feature variants

    • Array [
    • name string required

      The variants name. Is unique for this feature toggle

    • weight number required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is a number between 0 and 1000. See the section on variant weights for more information

    • weightType string

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000

    • stickiness string

      Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • overrides object[]

      Overrides assigning specific variants to specific users. The weighting system automatically assigns users to specific groups for you, but any overrides in this list will take precedence.

    • Array [
    • contextName string required

      The name of the context field used to determine overrides

    • values string[] required

      Which values that should be overriden

    • ]
    • ]
    • strategies object[] deprecated

      This is a legacy field that will be deprecated

    • tags object[]nullable

      The list of feature tags

    • Array [
    • value string required

      Possible values: >= 2 characters and <= 50 characters

      The value of the tag

    • type string required

      Possible values: >= 2 characters and <= 50 characters

      Default value: simple

      The type of the tag

    • ]
    • children string[]

      The list of child feature names. This is an experimental field and may change.

    • dependencies object[]

      The list of parent dependencies. This is an experimental field and may change.

    • Array [
    • feature string required

      The name of the parent feature

    • enabled boolean

      Whether the parent feature is enabled or not

    • variants string[]

      The list of variants the parent feature should resolve to. Only valid when feature is enabled.

    • ]
    • ]
    • strategies object[]

      A list of strategies

    • Array [
    • title string nullable

      An optional title for the strategy

    • name string required

      The name (type) of the strategy

    • displayName string nullable required

      A human friendly name for the strategy

    • description string nullable required

      A short description of the strategy

    • editable boolean required

      Whether the strategy can be edited or not. Strategies bundled with Unleash cannot be edited.

    • deprecated boolean required
    • parameters object[]required

      A list of relevant parameters for each strategy

    • Array [
    • name string
    • type string
    • description string
    • required boolean
    • ]
    • ]
    • tags object[]

      A list of tags

    • Array [
    • value string required

      Possible values: >= 2 characters and <= 50 characters

      The value of the tag

    • type string required

      Possible values: >= 2 characters and <= 50 characters

      Default value: simple

      The type of the tag

    • ]
    • tagTypes object[]

      A list of tag types

    • Array [
    • name string required

      The name of the tag type.

    • description string

      The description of the tag type.

    • icon string nullable

      The icon of the tag type.

    • ]
    • featureTags object[]

      A list of tags applied to features

    • Array [
    • featureName string required

      The name of the feature this tag is applied to

    • tagType string

      The [type](https://docs.getunleash.io/reference/tags#tag-types tag types) of the tag

    • tagValue string required

      The value of the tag

    • type string deprecated

      The [type](https://docs.getunleash.io/reference/tags#tag-types tag types) of the tag. This property is deprecated and will be removed in a future version of Unleash. Superseded by the tagType property.

    • value string deprecated

      The value of the tag. This property is deprecated and will be removed in a future version of Unleash. Superseded by the tagValue property.

    • createdByUserId number nullable

      The id of the user who created this tag

    • ]
    • projects object[]

      A list of projects

    • Array [
    • id string required

      The id of this project

    • name string required

      The name of this project

    • description string nullable

      Additional information about the project

    • health number

      An indicator of the project's health on a scale from 0 to 100

    • featureCount number

      The number of features this project has

    • memberCount number

      The number of members this project has

    • createdAt date-time

      When this project was created.

    • updatedAt date-time nullable

      When this project was last updated.

    • favorite boolean

      true if the project was favorited, otherwise false.

    • mode string

      Possible values: [open, protected, private]

      The project's collaboration mode. Determines whether non-project members can submit change requests or not.

    • defaultStickiness string

      A default stickiness for the project affecting the default stickiness value for variants and Gradual Rollout strategy

    • ]
    • featureStrategies object[]

      A list of feature strategies as applied to features

    • Array [
    • id string

      A uuid for the feature strategy

    • name string required

      The name or type of strategy

    • title string nullable

      A descriptive title for the strategy

    • disabled boolean nullable

      A toggle to disable the strategy. defaults to false. Disabled strategies are not evaluated or returned to the SDKs

    • featureName string

      The name or feature the strategy is attached to

    • sortOrder number

      The order of the strategy in the list

    • segments number[]

      A list of segment ids attached to the strategy

    • constraints object[]

      A list of the constraints attached to the strategy. See https://docs.getunleash.io/reference/strategy-constraints

    • Array [
    • contextName string required

      The name of the context field that this constraint should apply to.

    • operator string required

      Possible values: [NOT_IN, IN, STR_ENDS_WITH, STR_STARTS_WITH, STR_CONTAINS, NUM_EQ, NUM_GT, NUM_GTE, NUM_LT, NUM_LTE, DATE_AFTER, DATE_BEFORE, SEMVER_EQ, SEMVER_GT, SEMVER_LT]

      The operator to use when evaluating this constraint. For more information about the various operators, refer to the strategy constraint operator documentation.

    • caseInsensitive boolean

      Default value: false

      Whether the operator should be case sensitive or not. Defaults to false (being case sensitive).

    • inverted boolean

      Default value: false

      Whether the result should be negated or not. If true, will turn a true result into a false result and vice versa.

    • values string[]

      The context values that should be used for constraint evaluation. Use this property instead of value for properties that accept multiple values.

    • value string

      The context value that should be used for constraint evaluation. Use this property instead of values for properties that only accept single values.

    • ]
    • variants object[]

      Strategy level variants

    • Array [
    • name string required

      The variant name. Must be unique for this feature toggle

    • weight integer required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is an integer between 0 and 1000. See the section on variant weights for more information

    • weightType string required

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000. Refer to the variant weight documentation.

    • stickiness string required

      The stickiness to use for distribution of this variant. Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • ]
    • parameters object

      A list of parameters for a strategy

    • property name* string
    • ]
    • featureEnvironments object[]

      A list of feature environment configurations

    • Array [
    • name string required

      The name of the environment

    • featureName string

      The name of the feature

    • environment string

      The name of the environment

    • type string

      The type of the environment

    • enabled boolean required

      true if the feature is enabled for the environment, otherwise false.

    • sortOrder number

      The sort order of the feature environment in the feature environments list

    • variantCount number

      The number of defined variants

    • strategies object[]

      A list of activation strategies for the feature environment

    • Array [
    • id string

      A uuid for the feature strategy

    • name string required

      The name or type of strategy

    • title string nullable

      A descriptive title for the strategy

    • disabled boolean nullable

      A toggle to disable the strategy. defaults to false. Disabled strategies are not evaluated or returned to the SDKs

    • featureName string

      The name or feature the strategy is attached to

    • sortOrder number

      The order of the strategy in the list

    • segments number[]

      A list of segment ids attached to the strategy

    • constraints object[]

      A list of the constraints attached to the strategy. See https://docs.getunleash.io/reference/strategy-constraints

    • Array [
    • contextName string required

      The name of the context field that this constraint should apply to.

    • operator string required

      Possible values: [NOT_IN, IN, STR_ENDS_WITH, STR_STARTS_WITH, STR_CONTAINS, NUM_EQ, NUM_GT, NUM_GTE, NUM_LT, NUM_LTE, DATE_AFTER, DATE_BEFORE, SEMVER_EQ, SEMVER_GT, SEMVER_LT]

      The operator to use when evaluating this constraint. For more information about the various operators, refer to the strategy constraint operator documentation.

    • caseInsensitive boolean

      Default value: false

      Whether the operator should be case sensitive or not. Defaults to false (being case sensitive).

    • inverted boolean

      Default value: false

      Whether the result should be negated or not. If true, will turn a true result into a false result and vice versa.

    • values string[]

      The context values that should be used for constraint evaluation. Use this property instead of value for properties that accept multiple values.

    • value string

      The context value that should be used for constraint evaluation. Use this property instead of values for properties that only accept single values.

    • ]
    • variants object[]

      Strategy level variants

    • Array [
    • name string required

      The variant name. Must be unique for this feature toggle

    • weight integer required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is an integer between 0 and 1000. See the section on variant weights for more information

    • weightType string required

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000. Refer to the variant weight documentation.

    • stickiness string required

      The stickiness to use for distribution of this variant. Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • ]
    • parameters object

      A list of parameters for a strategy

    • property name* string
    • ]
    • variants object[]

      A list of variants for the feature environment

    • Array [
    • name string required

      The variants name. Is unique for this feature toggle

    • weight number required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is a number between 0 and 1000. See the section on variant weights for more information

    • weightType string

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000

    • stickiness string

      Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • overrides object[]

      Overrides assigning specific variants to specific users. The weighting system automatically assigns users to specific groups for you, but any overrides in this list will take precedence.

    • Array [
    • contextName string required

      The name of the context field used to determine overrides

    • values string[] required

      Which values that should be overriden

    • ]
    • ]
    • lastSeenAt date-time nullable

      The date when metrics where last collected for the feature environment

    • hasStrategies boolean

      Whether the feature has any strategies defined.

    • hasEnabledStrategies boolean

      Whether the feature has any enabled strategies defined.

    • ]
    • environments object[]

      A list of environments

    • Array [
    • name string required

      The name of the environment

    • type string required
    • enabled boolean required

      true if the environment is enabled for the project, otherwise false.

    • protected boolean required

      true if the environment is protected, otherwise false. A protected environment can not be deleted.

    • sortOrder integer required

      Priority of the environment in a list of environments, the lower the value, the higher up in the list the environment will appear. Needs to be an integer

    • projectCount integer nullable

      The number of projects with this environment

    • apiTokenCount integer nullable

      The number of API tokens for the project environment

    • enabledToggleCount integer nullable

      The number of enabled toggles for the project environment

    • ]
    • segments object[]

      A list of segments

    • Array [
    • id number required

      The segment's id.

    • name string

      The name of the segment.

    • constraints object[]required

      List of constraints that determine which users are part of the segment

    • Array [
    • contextName string required

      The name of the context field that this constraint should apply to.

    • operator string required

      Possible values: [NOT_IN, IN, STR_ENDS_WITH, STR_STARTS_WITH, STR_CONTAINS, NUM_EQ, NUM_GT, NUM_GTE, NUM_LT, NUM_LTE, DATE_AFTER, DATE_BEFORE, SEMVER_EQ, SEMVER_GT, SEMVER_LT]

      The operator to use when evaluating this constraint. For more information about the various operators, refer to the strategy constraint operator documentation.

    • caseInsensitive boolean

      Default value: false

      Whether the operator should be case sensitive or not. Defaults to false (being case sensitive).

    • inverted boolean

      Default value: false

      Whether the result should be negated or not. If true, will turn a true result into a false result and vice versa.

    • values string[]

      The context values that should be used for constraint evaluation. Use this property instead of value for properties that accept multiple values.

    • value string

      The context value that should be used for constraint evaluation. Use this property instead of values for properties that only accept single values.

    • ]
    • description string nullable

      The description of the segment.

    • createdAt date-time

      The time the segment was created as a RFC 3339-conformant timestamp.

    • createdBy string

      Which user created this segment

    • project string nullable

      The project the segment relates to, if applicable.

    • ]
    • featureStrategySegments object[]

      A list of segment/strategy pairings

    • Array [
    • segmentId integer required

      The ID of the segment

    • featureStrategyId string required

      The ID of the strategy

    • ]
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/feature-types.html b/reference/api/unleash/feature-types.html index ec6b19fe30..6ccf5daf70 100644 --- a/reference/api/unleash/feature-types.html +++ b/reference/api/unleash/feature-types.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Feature Types

    Manage feature toggle types.

    - + \ No newline at end of file diff --git a/reference/api/unleash/features.html b/reference/api/unleash/features.html index 8faef84f06..b1b8c9b779 100644 --- a/reference/api/unleash/features.html +++ b/reference/api/unleash/features.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Features

    Create, update, and delete features toggles.

    - + \ No newline at end of file diff --git a/reference/api/unleash/frontend-api.html b/reference/api/unleash/frontend-api.html index 7f293230af..7e1ed02957 100644 --- a/reference/api/unleash/frontend-api.html +++ b/reference/api/unleash/frontend-api.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Frontend API

    API for connecting client-side (frontend) applications to Unleash.

    - + \ No newline at end of file diff --git a/reference/api/unleash/get-access-overview.html b/reference/api/unleash/get-access-overview.html index 42091af519..1dbe66d2eb 100644 --- a/reference/api/unleash/get-access-overview.html +++ b/reference/api/unleash/get-access-overview.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Gets access overview

    GET /api/admin/access/overview

    Gets an overview of what access all users have to all projects and groups

    Request​

    Responses

    accessOverviewSchema

    Schema
    • overview object[]

      A list of user access details

    • Array [
    • userId integer required

      The identifier for the user

    • createdAt date-time nullable

      When the user was created

    • userName string nullable

      The name of the user

    • lastSeen date-time nullable

      The last time the user logged in

    • accessibleProjects string[] required

      A list of project ids that this user has access to

    • groups string[] required

      A list of group names that this user is a member of

    • rootRole string required

      The name of the root role that this user has

    • userEmail string required

      The email address of the user

    • ]
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-addon.html b/reference/api/unleash/get-addon.html index acaf295b06..1c4007b848 100644 --- a/reference/api/unleash/get-addon.html +++ b/reference/api/unleash/get-addon.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Get a specific addon

    GET /api/admin/addons/:id

    Retrieve information about the addon whose ID matches the ID in the request URL.

    Request​

    Path Parameters

    • id string required
    Responses

    addonSchema

    Schema
    • id integer required

      Possible values: >= 1

      The addon's unique identifier.

    • provider string required

      The addon provider, such as "webhook" or "slack".

    • description string nullable required

      A description of the addon. null if no description exists.

    • enabled boolean required

      Whether the addon is enabled or not.

    • parameters objectrequired

      Parameters for the addon provider. This object has different required and optional properties depending on the provider you choose.

    • events string[] required

      The event types that trigger this specific addon.

    • projects string[]

      The projects that this addon listens to events from. An empty list means it listens to events from all projects.

    • environments string[]

      The list of environments that this addon listens to events from. An empty list means it listens to events from all environments.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-addons.html b/reference/api/unleash/get-addons.html index f1be3f1a07..fba7303285 100644 --- a/reference/api/unleash/get-addons.html +++ b/reference/api/unleash/get-addons.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Get all addons and providers

    GET /api/admin/addons

    Retrieve all addons and providers that are defined on this Unleash instance.

    Request​

    Responses

    addonsSchema

    Schema
    • addons object[]required

      All the addons that exist on this instance of Unleash.

    • Array [
    • id integer required

      Possible values: >= 1

      The addon's unique identifier.

    • provider string required

      The addon provider, such as "webhook" or "slack".

    • description string nullable required

      A description of the addon. null if no description exists.

    • enabled boolean required

      Whether the addon is enabled or not.

    • parameters objectrequired

      Parameters for the addon provider. This object has different required and optional properties depending on the provider you choose.

    • events string[] required

      The event types that trigger this specific addon.

    • projects string[]

      The projects that this addon listens to events from. An empty list means it listens to events from all projects.

    • environments string[]

      The list of environments that this addon listens to events from. An empty list means it listens to events from all environments.

    • ]
    • providers object[]required

      A list of all available addon providers, along with their parameters and descriptions.

    • Array [
    • name string required

      The name of the addon type. When creating new addons, this goes in the payload's type field.

    • displayName string required

      The addon type's name as it should be displayed in the admin UI.

    • documentationUrl string required

      A URL to where you can find more information about using this addon type.

    • description string required

      A description of the addon type.

    • howTo string

      A long description of how to use this addon type. This will be displayed on the top of configuration page. Can contain markdown.

    • tagTypes object[]

      A list of Unleash tag types that this addon uses. These tags will be added to the Unleash instance when an addon of this type is created.

    • Array [
    • name string required

      The name of the tag type.

    • description string

      The description of the tag type.

    • icon string nullable

      The icon of the tag type.

    • ]
    • parameters object[]

      The addon provider's parameters. Use these to configure an addon of this provider type. Items with required: true must be provided.

    • Array [
    • name string required

      The name of the parameter as it is used in code. References to this parameter should use this value.

    • displayName string required

      The name of the parameter as it is shown to the end user in the Admin UI.

    • type string required

      The type of the parameter. Corresponds roughly to HTML input field types. Multi-line inut fields are indicated as textfield (equivalent to the HTML textarea tag).

    • description string

      A description of the parameter. This should explain to the end user what the parameter is used for.

    • placeholder string

      The default value for this parameter. This value is used if no other value is provided.

    • required boolean required

      Whether this parameter is required or not. If a parameter is required, you must give it a value when you create the addon. If it is not required it can be left out. It may receive a default value in those cases.

    • sensitive boolean required

      Indicates whether this parameter is sensitive or not. Unleash will not return sensitive parameters to API requests. It will instead use a number of asterisks to indicate that a value is set, e.g. "******". The number of asterisks does not correlate to the parameter's value.

    • ]
    • events string[]

      All the event types that are available for this addon provider.

    • installation object

      The installation configuration for this addon type.

    • url string required

      A URL to where the addon configuration should redirect to install addons of this type.

    • title string

      The title of the installation configuration. This will be displayed to the user when installing addons of this type.

    • helpText string

      The help text of the installation configuration. This will be displayed to the user when installing addons of this type.

    • alerts object[]

      A list of alerts to display to the user when installing addons of this type.

    • Array [
    • type string required

      Possible values: [success, info, warning, error]

      The type of alert. This determines the color of the alert.

    • text string required

      The text of the alert. This is what will be displayed to the user.

    • ]
    • deprecated string

      This should be used to inform the user that this addon type is deprecated and should not be used. Deprecated addons will show a badge with this information on the UI.

    • ]
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-admin-count.html b/reference/api/unleash/get-admin-count.html index 35a67e38ec..247095b674 100644 --- a/reference/api/unleash/get-admin-count.html +++ b/reference/api/unleash/get-admin-count.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Get total count of admin accounts

    GET /api/admin/user-admin/admin-count

    Get a total count of admins with password, without password and admin service accounts

    Request​

    Responses

    adminCountSchema

    Schema
    • password number required

      Total number of admins that have a password set.

    • noPassword number required

      Total number of admins that do not have a password set. May be SSO, but may also be users that did not set a password yet.

    • service number required

      Total number of service accounts that have the admin root role.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-advanced-playground.html b/reference/api/unleash/get-advanced-playground.html index 92599d2892..395ee64bd2 100644 --- a/reference/api/unleash/get-advanced-playground.html +++ b/reference/api/unleash/get-advanced-playground.html @@ -20,7 +20,7 @@ - + @@ -40,7 +40,7 @@ variant. If a feature is disabled or doesn't have any variants, you would get the disabled variant. Otherwise, you'll get one of the feature's defined variants.

  • name string required

    The variant's name. If there is no variant or if the toggle is disabled, this will be disabled

  • enabled boolean required

    Whether the variant is enabled or not. If the feature is disabled or if it doesn't have variants, this property will be false

  • payload object

    An optional payload attached to the variant.

  • type string required

    The format of the payload.

  • value string required

    The payload value stringified.

  • variants object[]required

    The feature variants.

  • Array [
  • name string required

    The variants name. Is unique for this feature toggle

  • weight number required

    Possible values: <= 1000

    The weight is the likelihood of any one user getting this variant. It is a number between 0 and 1000. See the section on variant weights for more information

  • weightType string

    Possible values: [variable, fix]

    Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000

  • stickiness string

    Stickiness is how Unleash guarantees that the same user gets the same variant every time

  • payload object

    Extra data configured for this variant

  • type string required

    Possible values: [json, csv, string, number]

    The type of the value. Commonly used types are string, number, json and csv.

  • value string required

    The actual value of payload

  • overrides object[]

    Overrides assigning specific variants to specific users. The weighting system automatically assigns users to specific groups for you, but any overrides in this list will take precedence.

  • Array [
  • contextName string required

    The name of the context field used to determine overrides

  • values string[] required

    Which values that should be overriden

  • ]
  • ]
  • ]
  • ]
    • Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-all-api-tokens.html b/reference/api/unleash/get-all-api-tokens.html index 2af05a83a7..436ee4a6e1 100644 --- a/reference/api/unleash/get-all-api-tokens.html +++ b/reference/api/unleash/get-all-api-tokens.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Get API tokens

    GET /api/admin/api-tokens

    Retrieves all API tokens that exist in the Unleash instance.

    Request​

    Responses

    apiTokensSchema

    Schema
    • tokens object[]required

      A list of Unleash API tokens.

    • Array [
    • secret string required

      The token used for authentication.

    • username string deprecated

      This property was deprecated in Unleash v5. Prefer the tokenName property instead.

    • tokenName string required

      A unique name for this particular token

    • type string required

      Possible values: [client, admin, frontend]

      The type of API token

    • environment string

      The environment the token has access to. * if it has access to all environments.

    • project string required

      The project this token belongs to.

    • projects string[] required

      The list of projects this token has access to. If the token has access to specific projects they will be listed here. If the token has access to all projects it will be represented as [*]

    • expiresAt date-time nullable

      The token's expiration date. NULL if the token doesn't have an expiration set.

    • createdAt date-time required

      When the token was created.

    • seenAt date-time nullable

      When the token was last seen/used to authenticate with. NULL if the token has not yet been used for authentication.

    • alias string nullable

      Alias is no longer in active use and will often be NULL. It's kept around as a way of allowing old proxy tokens created with the old metadata format to keep working.

    • ]
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-all-client-features.html b/reference/api/unleash/get-all-client-features.html index 8a426089d8..f1385fbad2 100644 --- a/reference/api/unleash/get-all-client-features.html +++ b/reference/api/unleash/get-all-client-features.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Get all toggles (SDK)

    GET /api/client/features

    Returns the SDK configuration for all feature toggles that are available to the provided API key. Used by SDKs to configure local evaluation

    Request​

    Responses

    clientFeaturesSchema

    Schema
    • version number required

      A version number for the format used in the response. Most Unleash instances now return version 2, which includes segments as a separate array

    • features object[]required

      A list of feature toggles with their configuration

    • Array [
    • name string required

      The unique name of a feature toggle. Is validated to be URL safe on creation

    • type string

      What kind of feature flag is this. Refer to the documentation on feature toggle types for more information

    • description string nullable

      A description of the toggle

    • enabled boolean required

      Whether the feature flag is enabled for the current API key or not. This is ANDed with the evaluation results of the strategies list, so if this is false, the evaluation result will always be false

    • stale boolean

      If this is true Unleash believes this feature toggle has been active longer than Unleash expects a toggle of this type to be active

    • impressionData boolean nullable

      Set to true if SDKs should trigger impression events when this toggle is evaluated

    • project string

      Which project this feature toggle belongs to

    • strategies object[]

      Evaluation strategies for this toggle. Each entry in this list will be evaluated and ORed together

    • Array [
    • id string

      A uuid for the feature strategy

    • name string required

      The name or type of strategy

    • title string nullable

      A descriptive title for the strategy

    • disabled boolean nullable

      A toggle to disable the strategy. defaults to false. Disabled strategies are not evaluated or returned to the SDKs

    • featureName string

      The name or feature the strategy is attached to

    • sortOrder number

      The order of the strategy in the list

    • segments number[]

      A list of segment ids attached to the strategy

    • constraints object[]

      A list of the constraints attached to the strategy. See https://docs.getunleash.io/reference/strategy-constraints

    • Array [
    • contextName string required

      The name of the context field that this constraint should apply to.

    • operator string required

      Possible values: [NOT_IN, IN, STR_ENDS_WITH, STR_STARTS_WITH, STR_CONTAINS, NUM_EQ, NUM_GT, NUM_GTE, NUM_LT, NUM_LTE, DATE_AFTER, DATE_BEFORE, SEMVER_EQ, SEMVER_GT, SEMVER_LT]

      The operator to use when evaluating this constraint. For more information about the various operators, refer to the strategy constraint operator documentation.

    • caseInsensitive boolean

      Default value: false

      Whether the operator should be case sensitive or not. Defaults to false (being case sensitive).

    • inverted boolean

      Default value: false

      Whether the result should be negated or not. If true, will turn a true result into a false result and vice versa.

    • values string[]

      The context values that should be used for constraint evaluation. Use this property instead of value for properties that accept multiple values.

    • value string

      The context value that should be used for constraint evaluation. Use this property instead of values for properties that only accept single values.

    • ]
    • variants object[]

      Strategy level variants

    • Array [
    • name string required

      The variant name. Must be unique for this feature toggle

    • weight integer required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is an integer between 0 and 1000. See the section on variant weights for more information

    • weightType string required

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000. Refer to the variant weight documentation.

    • stickiness string required

      The stickiness to use for distribution of this variant. Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • ]
    • parameters object

      A list of parameters for a strategy

    • property name* string
    • ]
    • variants object[]nullable

      Variants configured for this toggle

    • Array [
    • name string required

      The variants name. Is unique for this feature toggle

    • weight number required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is a number between 0 and 1000. See the section on variant weights for more information

    • weightType string

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000

    • stickiness string

      Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • overrides object[]

      Overrides assigning specific variants to specific users. The weighting system automatically assigns users to specific groups for you, but any overrides in this list will take precedence.

    • Array [
    • contextName string required

      The name of the context field used to determine overrides

    • values string[] required

      Which values that should be overriden

    • ]
    • ]
    • dependencies object[]

      Feature dependencies for this toggle

    • Array [
    • feature string required

      The name of the feature we depend on.

    • enabled boolean

      Whether the parent feature should be enabled. When false variants are ignored. true by default.

    • variants string[]

      The list of variants the parent feature should resolve to. Leave empty when you only want to check the enabled status.

    • ]
    • ]
    • segments object[]

      A list of Segments configured for this Unleash instance

    • Array [
    • id number required

      The segment's id.

    • name string

      The name of the segment.

    • constraints object[]required

      List of constraints that determine which users are part of the segment

    • Array [
    • contextName string required

      The name of the context field that this constraint should apply to.

    • operator string required

      Possible values: [NOT_IN, IN, STR_ENDS_WITH, STR_STARTS_WITH, STR_CONTAINS, NUM_EQ, NUM_GT, NUM_GTE, NUM_LT, NUM_LTE, DATE_AFTER, DATE_BEFORE, SEMVER_EQ, SEMVER_GT, SEMVER_LT]

      The operator to use when evaluating this constraint. For more information about the various operators, refer to the strategy constraint operator documentation.

    • caseInsensitive boolean

      Default value: false

      Whether the operator should be case sensitive or not. Defaults to false (being case sensitive).

    • inverted boolean

      Default value: false

      Whether the result should be negated or not. If true, will turn a true result into a false result and vice versa.

    • values string[]

      The context values that should be used for constraint evaluation. Use this property instead of value for properties that accept multiple values.

    • value string

      The context value that should be used for constraint evaluation. Use this property instead of values for properties that only accept single values.

    • ]
    • ]
    • query object

      A summary of filters and parameters sent to the endpoint. Used by the server to build the features and segments response

    • tag array[]

      Features tagged with one of these tags are included

    • project string[] deprecated

      Features that are part of these projects are included in this response. (DEPRECATED) - Handled by API tokens

    • namePrefix string

      Features are filtered to only include features whose name starts with this prefix

    • environment string deprecated

      Strategies for the feature toggle configured for this environment are included. (DEPRECATED) - Handled by API tokens

    • inlineSegmentConstraints boolean

      Set to true if requesting client does not support Unleash-Client-Specification 4.2.2 or newer. Modern SDKs will have this set to false, since they will be able to merge constraints and segments themselves

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-all-environments.html b/reference/api/unleash/get-all-environments.html index 9f3af7d454..c3262ebe0c 100644 --- a/reference/api/unleash/get-all-environments.html +++ b/reference/api/unleash/get-all-environments.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Get all environments

    GET /api/admin/environments

    Retrieves all environments that exist in this Unleash instance.

    Request​

    Responses

    environmentsSchema

    Schema
    • version integer required

      Version of the environments schema

    • environments object[]required

      List of environments

    • Array [
    • name string required

      The name of the environment

    • type string required
    • enabled boolean required

      true if the environment is enabled for the project, otherwise false.

    • protected boolean required

      true if the environment is protected, otherwise false. A protected environment can not be deleted.

    • sortOrder integer required

      Priority of the environment in a list of environments, the lower the value, the higher up in the list the environment will appear. Needs to be an integer

    • projectCount integer nullable

      The number of projects with this environment

    • apiTokenCount integer nullable

      The number of API tokens for the project environment

    • enabledToggleCount integer nullable

      The number of enabled toggles for the project environment

    • ]
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-all-feature-types.html b/reference/api/unleash/get-all-feature-types.html index b0e4e3b98a..5197186750 100644 --- a/reference/api/unleash/get-all-feature-types.html +++ b/reference/api/unleash/get-all-feature-types.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Get all feature types

    GET /api/admin/feature-types

    Retrieves all feature types that exist in this Unleash instance, along with their descriptions and lifetimes.

    Request​

    Responses

    featureTypesSchema

    Schema
    • version integer required

      Possible values: [1]

      The schema version used to describe the feature toggle types listed in the types property.

    • types object[]required

      The list of feature toggle types.

    • Array [
    • id string required

      The identifier of this feature toggle type.

    • name string required

      The display name of this feature toggle type.

    • description string required

      A description of what this feature toggle type is intended to be used for.

    • lifetimeDays integer nullable required

      How many days it takes before a feature toggle of this typed is flagged as potentially stale by Unleash. If this value is null, Unleash will never mark it as potentially stale.

    • ]
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-all-public-signup-tokens.html b/reference/api/unleash/get-all-public-signup-tokens.html index 76b33201c2..b877696d3c 100644 --- a/reference/api/unleash/get-all-public-signup-tokens.html +++ b/reference/api/unleash/get-all-public-signup-tokens.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Get public signup tokens

    GET /api/admin/invite-link/tokens

    Retrieves all existing public signup tokens.

    Request​

    Responses

    publicSignupTokensSchema

    Schema
    • tokens object[]required

      An array of all the public signup tokens

    • Array [
    • secret string required

      The actual value of the token. This is the part that is used by Unleash to create an invite link

    • url string nullable required

      The public signup link for the token. Users who follow this link will be taken to a signup page where they can create an Unleash user.

    • name string required

      The token's name. Only for displaying in the UI

    • enabled boolean required

      Whether the token is active. This property will always be false for a token that has expired.

    • expiresAt date-time required

      The time when the token will expire.

    • createdAt date-time required

      When the token was created.

    • createdBy string nullable required

      The creator's email or username

    • users object[]nullable

      Array of users that have signed up using the token.

    • Array [
    • id integer required

      The user id

    • isAPI boolean deprecated

      (Deprecated): Used internally to know which operations the user should be allowed to perform

    • name string nullable

      Name of the user

    • email string

      Email of the user

    • username string nullable

      A unique username for the user

    • imageUrl string

      URL used for the userprofile image

    • inviteLink string

      If the user is actively inviting other users, this is the link that can be shared with other users

    • loginAttempts integer

      How many unsuccessful attempts at logging in has the user made

    • emailSent boolean

      Is the welcome email sent to the user or not

    • rootRole integer

      Which root role this user is assigned

    • seenAt date-time nullable

      The last time this user logged in

    • createdAt date-time

      The user was created at this time

    • accountType string

      A user is either an actual User or a Service Account

    • permissions string[]

      Deprecated

    • ]
    • role objectrequired

      A role holds permissions to allow Unleash to decide what actions a role holder is allowed to perform

    • id integer required

      The role id

    • type string required

      A role can either be a global root role (applies to all projects) or a project role

    • name string required

      The name of the role

    • description string

      A more detailed description of the role and what use it's intended for

    • ]
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-all-strategies.html b/reference/api/unleash/get-all-strategies.html index b25e4f69b4..38085881a0 100644 --- a/reference/api/unleash/get-all-strategies.html +++ b/reference/api/unleash/get-all-strategies.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Get all strategies

    GET /api/admin/strategies

    Retrieves all strategy types (predefined and custom strategies) that are defined on this Unleash instance.

    Request​

    Responses

    strategiesSchema

    Schema
    • version integer required

      Possible values: [1]

      Version of the strategies schema

    • strategies object[]required

      List of strategies

    • Array [
    • title string nullable

      An optional title for the strategy

    • name string required

      The name (type) of the strategy

    • displayName string nullable required

      A human friendly name for the strategy

    • description string nullable required

      A short description of the strategy

    • editable boolean required

      Whether the strategy can be edited or not. Strategies bundled with Unleash cannot be edited.

    • deprecated boolean required
    • parameters object[]required

      A list of relevant parameters for each strategy

    • Array [
    • name string
    • type string
    • description string
    • required boolean
    • ]
    • ]
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-all-toggles.html b/reference/api/unleash/get-all-toggles.html index 931dd1c866..84817296e2 100644 --- a/reference/api/unleash/get-all-toggles.html +++ b/reference/api/unleash/get-all-toggles.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Get all feature toggles (deprecated)

    GET /api/admin/features
    deprecated

    This endpoint has been deprecated and may be removed in future versions of the API.

    Gets all feature toggles with their full configuration. This endpoint is deprecated. You should use the project-based endpoint instead (/api/admin/projects/<project-id>/features).

    Request​

    Responses

    featuresSchema

    Schema
    • version integer required

      The version of the feature's schema

    • features object[]required

      A list of features

    • Array [
    • name string required

      Unique feature name

    • type string

      Type of the toggle e.g. experiment, kill-switch, release, operational, permission

    • description string nullable

      Detailed description of the feature

    • archived boolean

      true if the feature is archived

    • project string

      Name of the project the feature belongs to

    • enabled boolean

      true if the feature is enabled, otherwise false.

    • stale boolean

      true if the feature is stale based on the age and feature type, otherwise false.

    • favorite boolean

      true if the feature was favorited, otherwise false.

    • impressionData boolean

      true if the impression data collection is enabled for the feature, otherwise false.

    • createdAt date-time nullable

      The date the feature was created

    • archivedAt date-time nullable

      The date the feature was archived

    • lastSeenAt date-time nullable deprecated

      The date when metrics where last collected for the feature. This field is deprecated, use the one in featureEnvironmentSchema

    • environments object[]

      The list of environments where the feature can be used

    • Array [
    • name string required

      The name of the environment

    • featureName string

      The name of the feature

    • environment string

      The name of the environment

    • type string

      The type of the environment

    • enabled boolean required

      true if the feature is enabled for the environment, otherwise false.

    • sortOrder number

      The sort order of the feature environment in the feature environments list

    • variantCount number

      The number of defined variants

    • strategies object[]

      A list of activation strategies for the feature environment

    • Array [
    • id string

      A uuid for the feature strategy

    • name string required

      The name or type of strategy

    • title string nullable

      A descriptive title for the strategy

    • disabled boolean nullable

      A toggle to disable the strategy. defaults to false. Disabled strategies are not evaluated or returned to the SDKs

    • featureName string

      The name or feature the strategy is attached to

    • sortOrder number

      The order of the strategy in the list

    • segments number[]

      A list of segment ids attached to the strategy

    • constraints object[]

      A list of the constraints attached to the strategy. See https://docs.getunleash.io/reference/strategy-constraints

    • Array [
    • contextName string required

      The name of the context field that this constraint should apply to.

    • operator string required

      Possible values: [NOT_IN, IN, STR_ENDS_WITH, STR_STARTS_WITH, STR_CONTAINS, NUM_EQ, NUM_GT, NUM_GTE, NUM_LT, NUM_LTE, DATE_AFTER, DATE_BEFORE, SEMVER_EQ, SEMVER_GT, SEMVER_LT]

      The operator to use when evaluating this constraint. For more information about the various operators, refer to the strategy constraint operator documentation.

    • caseInsensitive boolean

      Default value: false

      Whether the operator should be case sensitive or not. Defaults to false (being case sensitive).

    • inverted boolean

      Default value: false

      Whether the result should be negated or not. If true, will turn a true result into a false result and vice versa.

    • values string[]

      The context values that should be used for constraint evaluation. Use this property instead of value for properties that accept multiple values.

    • value string

      The context value that should be used for constraint evaluation. Use this property instead of values for properties that only accept single values.

    • ]
    • variants object[]

      Strategy level variants

    • Array [
    • name string required

      The variant name. Must be unique for this feature toggle

    • weight integer required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is an integer between 0 and 1000. See the section on variant weights for more information

    • weightType string required

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000. Refer to the variant weight documentation.

    • stickiness string required

      The stickiness to use for distribution of this variant. Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • ]
    • parameters object

      A list of parameters for a strategy

    • property name* string
    • ]
    • variants object[]

      A list of variants for the feature environment

    • Array [
    • name string required

      The variants name. Is unique for this feature toggle

    • weight number required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is a number between 0 and 1000. See the section on variant weights for more information

    • weightType string

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000

    • stickiness string

      Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • overrides object[]

      Overrides assigning specific variants to specific users. The weighting system automatically assigns users to specific groups for you, but any overrides in this list will take precedence.

    • Array [
    • contextName string required

      The name of the context field used to determine overrides

    • values string[] required

      Which values that should be overriden

    • ]
    • ]
    • lastSeenAt date-time nullable

      The date when metrics where last collected for the feature environment

    • hasStrategies boolean

      Whether the feature has any strategies defined.

    • hasEnabledStrategies boolean

      Whether the feature has any enabled strategies defined.

    • ]
    • variants object[]deprecated

      The list of feature variants

    • Array [
    • name string required

      The variants name. Is unique for this feature toggle

    • weight number required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is a number between 0 and 1000. See the section on variant weights for more information

    • weightType string

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000

    • stickiness string

      Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • overrides object[]

      Overrides assigning specific variants to specific users. The weighting system automatically assigns users to specific groups for you, but any overrides in this list will take precedence.

    • Array [
    • contextName string required

      The name of the context field used to determine overrides

    • values string[] required

      Which values that should be overriden

    • ]
    • ]
    • strategies object[] deprecated

      This is a legacy field that will be deprecated

    • tags object[]nullable

      The list of feature tags

    • Array [
    • value string required

      Possible values: >= 2 characters and <= 50 characters

      The value of the tag

    • type string required

      Possible values: >= 2 characters and <= 50 characters

      Default value: simple

      The type of the tag

    • ]
    • children string[]

      The list of child feature names. This is an experimental field and may change.

    • dependencies object[]

      The list of parent dependencies. This is an experimental field and may change.

    • Array [
    • feature string required

      The name of the parent feature

    • enabled boolean

      Whether the parent feature is enabled or not

    • variants string[]

      The list of variants the parent feature should resolve to. Only valid when feature is enabled.

    • ]
    • ]
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-api-tokens-by-name.html b/reference/api/unleash/get-api-tokens-by-name.html index 7170c7db38..019b90e7e3 100644 --- a/reference/api/unleash/get-api-tokens-by-name.html +++ b/reference/api/unleash/get-api-tokens-by-name.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Get API tokens by name

    GET /api/admin/api-tokens/:name

    Retrieves all API tokens that match a given token name. Because token names are not unique, this endpoint will always return a list. If no tokens with the provided name exist, the list will be empty. Otherwise, it will contain all the tokens with the given name.

    Request​

    Path Parameters

    • name string required
    Responses

    apiTokensSchema

    Schema
    • tokens object[]required

      A list of Unleash API tokens.

    • Array [
    • secret string required

      The token used for authentication.

    • username string deprecated

      This property was deprecated in Unleash v5. Prefer the tokenName property instead.

    • tokenName string required

      A unique name for this particular token

    • type string required

      Possible values: [client, admin, frontend]

      The type of API token

    • environment string

      The environment the token has access to. * if it has access to all environments.

    • project string required

      The project this token belongs to.

    • projects string[] required

      The list of projects this token has access to. If the token has access to specific projects they will be listed here. If the token has access to all projects it will be represented as [*]

    • expiresAt date-time nullable

      The token's expiration date. NULL if the token doesn't have an expiration set.

    • createdAt date-time required

      When the token was created.

    • seenAt date-time nullable

      When the token was last seen/used to authenticate with. NULL if the token has not yet been used for authentication.

    • alias string nullable

      Alias is no longer in active use and will often be NULL. It's kept around as a way of allowing old proxy tokens created with the old metadata format to keep working.

    • ]
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-application.html b/reference/api/unleash/get-application.html index 06fcb2a0b3..4466ba180f 100644 --- a/reference/api/unleash/get-application.html +++ b/reference/api/unleash/get-application.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Get application data

    GET /api/admin/metrics/applications/:appName

    Returns data about the specified application (appName). The data contains information on the name of the application, sdkVersion (which sdk reported these metrics, typically unleash-client-node:3.4.1 or unleash-client-java:7.1.0), as well as data about how to display this application in a list.

    Request​

    Path Parameters

    • appName string required
    Responses

    applicationSchema

    Schema
    • appName string required

      Name of the application

    • sdkVersion string

      Which SDK and version the application reporting uses. Typically represented as <identifier>:<version>

    • strategies string[]

      Which strategies the application has loaded. Useful when trying to figure out if your custom strategy has been loaded in the SDK

    • description string

      Extra information added about the application reporting the metrics. Only present if added via the Unleash Admin interface

    • url string

      A link to reference the application reporting the metrics. Could for instance be a GitHub link to the repository of the application

    • color string

      The CSS color that is used to color the application's entry in the application list

    • icon string

      An URL to an icon file to be used for the applications's entry in the application list

    • usage object[]

      The list of projects the application has been using.

    • Array [
    • project string required

      Name of the project

    • environments string[] required

      Which environments have been accessed in this project.

    • ]
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-applications.html b/reference/api/unleash/get-applications.html index 230f96b675..89c679bb47 100644 --- a/reference/api/unleash/get-applications.html +++ b/reference/api/unleash/get-applications.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Get all applications

    GET /api/admin/metrics/applications

    Returns all applications registered with Unleash. Applications can be created via metrics reporting or manual creation

    Request​

    Responses

    applicationsSchema

    Schema
    • applications object[]

      The list of applications that have connected to this Unleash instance.

    • Array [
    • appName string required

      Name of the application

    • sdkVersion string

      Which SDK and version the application reporting uses. Typically represented as <identifier>:<version>

    • strategies string[]

      Which strategies the application has loaded. Useful when trying to figure out if your custom strategy has been loaded in the SDK

    • description string

      Extra information added about the application reporting the metrics. Only present if added via the Unleash Admin interface

    • url string

      A link to reference the application reporting the metrics. Could for instance be a GitHub link to the repository of the application

    • color string

      The CSS color that is used to color the application's entry in the application list

    • icon string

      An URL to an icon file to be used for the applications's entry in the application list

    • usage object[]

      The list of projects the application has been using.

    • Array [
    • project string required

      Name of the project

    • environments string[] required

      Which environments have been accessed in this project.

    • ]
    • ]
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-archived-features-by-project-id.html b/reference/api/unleash/get-archived-features-by-project-id.html index 5e2c1e840a..5a4335bd21 100644 --- a/reference/api/unleash/get-archived-features-by-project-id.html +++ b/reference/api/unleash/get-archived-features-by-project-id.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Get archived features in project

    GET /api/admin/archive/features/:projectId
    deprecated

    This endpoint has been deprecated and may be removed in future versions of the API.

    Retrieves a list of archived features that belong to the provided project.

    Request​

    Path Parameters

    • projectId string required
    Responses

    featuresSchema

    Schema
    • version integer required

      The version of the feature's schema

    • features object[]required

      A list of features

    • Array [
    • name string required

      Unique feature name

    • type string

      Type of the toggle e.g. experiment, kill-switch, release, operational, permission

    • description string nullable

      Detailed description of the feature

    • archived boolean

      true if the feature is archived

    • project string

      Name of the project the feature belongs to

    • enabled boolean

      true if the feature is enabled, otherwise false.

    • stale boolean

      true if the feature is stale based on the age and feature type, otherwise false.

    • favorite boolean

      true if the feature was favorited, otherwise false.

    • impressionData boolean

      true if the impression data collection is enabled for the feature, otherwise false.

    • createdAt date-time nullable

      The date the feature was created

    • archivedAt date-time nullable

      The date the feature was archived

    • lastSeenAt date-time nullable deprecated

      The date when metrics where last collected for the feature. This field is deprecated, use the one in featureEnvironmentSchema

    • environments object[]

      The list of environments where the feature can be used

    • Array [
    • name string required

      The name of the environment

    • featureName string

      The name of the feature

    • environment string

      The name of the environment

    • type string

      The type of the environment

    • enabled boolean required

      true if the feature is enabled for the environment, otherwise false.

    • sortOrder number

      The sort order of the feature environment in the feature environments list

    • variantCount number

      The number of defined variants

    • strategies object[]

      A list of activation strategies for the feature environment

    • Array [
    • id string

      A uuid for the feature strategy

    • name string required

      The name or type of strategy

    • title string nullable

      A descriptive title for the strategy

    • disabled boolean nullable

      A toggle to disable the strategy. defaults to false. Disabled strategies are not evaluated or returned to the SDKs

    • featureName string

      The name or feature the strategy is attached to

    • sortOrder number

      The order of the strategy in the list

    • segments number[]

      A list of segment ids attached to the strategy

    • constraints object[]

      A list of the constraints attached to the strategy. See https://docs.getunleash.io/reference/strategy-constraints

    • Array [
    • contextName string required

      The name of the context field that this constraint should apply to.

    • operator string required

      Possible values: [NOT_IN, IN, STR_ENDS_WITH, STR_STARTS_WITH, STR_CONTAINS, NUM_EQ, NUM_GT, NUM_GTE, NUM_LT, NUM_LTE, DATE_AFTER, DATE_BEFORE, SEMVER_EQ, SEMVER_GT, SEMVER_LT]

      The operator to use when evaluating this constraint. For more information about the various operators, refer to the strategy constraint operator documentation.

    • caseInsensitive boolean

      Default value: false

      Whether the operator should be case sensitive or not. Defaults to false (being case sensitive).

    • inverted boolean

      Default value: false

      Whether the result should be negated or not. If true, will turn a true result into a false result and vice versa.

    • values string[]

      The context values that should be used for constraint evaluation. Use this property instead of value for properties that accept multiple values.

    • value string

      The context value that should be used for constraint evaluation. Use this property instead of values for properties that only accept single values.

    • ]
    • variants object[]

      Strategy level variants

    • Array [
    • name string required

      The variant name. Must be unique for this feature toggle

    • weight integer required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is an integer between 0 and 1000. See the section on variant weights for more information

    • weightType string required

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000. Refer to the variant weight documentation.

    • stickiness string required

      The stickiness to use for distribution of this variant. Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • ]
    • parameters object

      A list of parameters for a strategy

    • property name* string
    • ]
    • variants object[]

      A list of variants for the feature environment

    • Array [
    • name string required

      The variants name. Is unique for this feature toggle

    • weight number required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is a number between 0 and 1000. See the section on variant weights for more information

    • weightType string

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000

    • stickiness string

      Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • overrides object[]

      Overrides assigning specific variants to specific users. The weighting system automatically assigns users to specific groups for you, but any overrides in this list will take precedence.

    • Array [
    • contextName string required

      The name of the context field used to determine overrides

    • values string[] required

      Which values that should be overriden

    • ]
    • ]
    • lastSeenAt date-time nullable

      The date when metrics where last collected for the feature environment

    • hasStrategies boolean

      Whether the feature has any strategies defined.

    • hasEnabledStrategies boolean

      Whether the feature has any enabled strategies defined.

    • ]
    • variants object[]deprecated

      The list of feature variants

    • Array [
    • name string required

      The variants name. Is unique for this feature toggle

    • weight number required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is a number between 0 and 1000. See the section on variant weights for more information

    • weightType string

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000

    • stickiness string

      Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • overrides object[]

      Overrides assigning specific variants to specific users. The weighting system automatically assigns users to specific groups for you, but any overrides in this list will take precedence.

    • Array [
    • contextName string required

      The name of the context field used to determine overrides

    • values string[] required

      Which values that should be overriden

    • ]
    • ]
    • strategies object[] deprecated

      This is a legacy field that will be deprecated

    • tags object[]nullable

      The list of feature tags

    • Array [
    • value string required

      Possible values: >= 2 characters and <= 50 characters

      The value of the tag

    • type string required

      Possible values: >= 2 characters and <= 50 characters

      Default value: simple

      The type of the tag

    • ]
    • children string[]

      The list of child feature names. This is an experimental field and may change.

    • dependencies object[]

      The list of parent dependencies. This is an experimental field and may change.

    • Array [
    • feature string required

      The name of the parent feature

    • enabled boolean

      Whether the parent feature is enabled or not

    • variants string[]

      The list of variants the parent feature should resolve to. Only valid when feature is enabled.

    • ]
    • ]
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-archived-features.html b/reference/api/unleash/get-archived-features.html index 85a4fc7446..283470ecb2 100644 --- a/reference/api/unleash/get-archived-features.html +++ b/reference/api/unleash/get-archived-features.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Get archived features

    GET /api/admin/archive/features
    deprecated

    This endpoint has been deprecated and may be removed in future versions of the API.

    Retrieve a list of all archived feature toggles.

    Request​

    Responses

    featuresSchema

    Schema
    • version integer required

      The version of the feature's schema

    • features object[]required

      A list of features

    • Array [
    • name string required

      Unique feature name

    • type string

      Type of the toggle e.g. experiment, kill-switch, release, operational, permission

    • description string nullable

      Detailed description of the feature

    • archived boolean

      true if the feature is archived

    • project string

      Name of the project the feature belongs to

    • enabled boolean

      true if the feature is enabled, otherwise false.

    • stale boolean

      true if the feature is stale based on the age and feature type, otherwise false.

    • favorite boolean

      true if the feature was favorited, otherwise false.

    • impressionData boolean

      true if the impression data collection is enabled for the feature, otherwise false.

    • createdAt date-time nullable

      The date the feature was created

    • archivedAt date-time nullable

      The date the feature was archived

    • lastSeenAt date-time nullable deprecated

      The date when metrics where last collected for the feature. This field is deprecated, use the one in featureEnvironmentSchema

    • environments object[]

      The list of environments where the feature can be used

    • Array [
    • name string required

      The name of the environment

    • featureName string

      The name of the feature

    • environment string

      The name of the environment

    • type string

      The type of the environment

    • enabled boolean required

      true if the feature is enabled for the environment, otherwise false.

    • sortOrder number

      The sort order of the feature environment in the feature environments list

    • variantCount number

      The number of defined variants

    • strategies object[]

      A list of activation strategies for the feature environment

    • Array [
    • id string

      A uuid for the feature strategy

    • name string required

      The name or type of strategy

    • title string nullable

      A descriptive title for the strategy

    • disabled boolean nullable

      A toggle to disable the strategy. defaults to false. Disabled strategies are not evaluated or returned to the SDKs

    • featureName string

      The name or feature the strategy is attached to

    • sortOrder number

      The order of the strategy in the list

    • segments number[]

      A list of segment ids attached to the strategy

    • constraints object[]

      A list of the constraints attached to the strategy. See https://docs.getunleash.io/reference/strategy-constraints

    • Array [
    • contextName string required

      The name of the context field that this constraint should apply to.

    • operator string required

      Possible values: [NOT_IN, IN, STR_ENDS_WITH, STR_STARTS_WITH, STR_CONTAINS, NUM_EQ, NUM_GT, NUM_GTE, NUM_LT, NUM_LTE, DATE_AFTER, DATE_BEFORE, SEMVER_EQ, SEMVER_GT, SEMVER_LT]

      The operator to use when evaluating this constraint. For more information about the various operators, refer to the strategy constraint operator documentation.

    • caseInsensitive boolean

      Default value: false

      Whether the operator should be case sensitive or not. Defaults to false (being case sensitive).

    • inverted boolean

      Default value: false

      Whether the result should be negated or not. If true, will turn a true result into a false result and vice versa.

    • values string[]

      The context values that should be used for constraint evaluation. Use this property instead of value for properties that accept multiple values.

    • value string

      The context value that should be used for constraint evaluation. Use this property instead of values for properties that only accept single values.

    • ]
    • variants object[]

      Strategy level variants

    • Array [
    • name string required

      The variant name. Must be unique for this feature toggle

    • weight integer required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is an integer between 0 and 1000. See the section on variant weights for more information

    • weightType string required

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000. Refer to the variant weight documentation.

    • stickiness string required

      The stickiness to use for distribution of this variant. Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • ]
    • parameters object

      A list of parameters for a strategy

    • property name* string
    • ]
    • variants object[]

      A list of variants for the feature environment

    • Array [
    • name string required

      The variants name. Is unique for this feature toggle

    • weight number required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is a number between 0 and 1000. See the section on variant weights for more information

    • weightType string

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000

    • stickiness string

      Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • overrides object[]

      Overrides assigning specific variants to specific users. The weighting system automatically assigns users to specific groups for you, but any overrides in this list will take precedence.

    • Array [
    • contextName string required

      The name of the context field used to determine overrides

    • values string[] required

      Which values that should be overriden

    • ]
    • ]
    • lastSeenAt date-time nullable

      The date when metrics where last collected for the feature environment

    • hasStrategies boolean

      Whether the feature has any strategies defined.

    • hasEnabledStrategies boolean

      Whether the feature has any enabled strategies defined.

    • ]
    • variants object[]deprecated

      The list of feature variants

    • Array [
    • name string required

      The variants name. Is unique for this feature toggle

    • weight number required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is a number between 0 and 1000. See the section on variant weights for more information

    • weightType string

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000

    • stickiness string

      Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • overrides object[]

      Overrides assigning specific variants to specific users. The weighting system automatically assigns users to specific groups for you, but any overrides in this list will take precedence.

    • Array [
    • contextName string required

      The name of the context field used to determine overrides

    • values string[] required

      Which values that should be overriden

    • ]
    • ]
    • strategies object[] deprecated

      This is a legacy field that will be deprecated

    • tags object[]nullable

      The list of feature tags

    • Array [
    • value string required

      Possible values: >= 2 characters and <= 50 characters

      The value of the tag

    • type string required

      Possible values: >= 2 characters and <= 50 characters

      Default value: simple

      The type of the tag

    • ]
    • children string[]

      The list of child feature names. This is an experimental field and may change.

    • dependencies object[]

      The list of parent dependencies. This is an experimental field and may change.

    • Array [
    • feature string required

      The name of the parent feature

    • enabled boolean

      Whether the parent feature is enabled or not

    • variants string[]

      The list of variants the parent feature should resolve to. Only valid when feature is enabled.

    • ]
    • ]
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-banners.html b/reference/api/unleash/get-banners.html index 116a984cee..fe3438e212 100644 --- a/reference/api/unleash/get-banners.html +++ b/reference/api/unleash/get-banners.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Get all banners.

    GET /api/admin/banners

    Returns a list of all configured banners.

    Request​

    Responses

    bannersSchema

    Schema
    • banners object[]required

      A list of banners.

    • Array [
    • id integer required

      Possible values: >= 1

      The banner's ID. Banner IDs are incrementing integers. In other words, a more recently created banner will always have a higher ID than an older one.

    • message string required

      The message to display to all users. Supports markdown.

    • enabled boolean

      Whether the banner should be displayed currently. If not specified, defaults to true.

    • variant string

      The variant of the banner. One of "info", "warning", "error", or "success". If not specified, defaults to "info".

    • sticky boolean

      Whether the banner should be sticky on the screen. If not specified, defaults to false.

    • icon string nullable

      The icon to display on the banner. Can be one of https://fonts.google.com/icons. If not specified, this will be the default icon for the variant. If "none", no icon will be displayed.

    • link string nullable

      The link to display on the banner. Can either be an absolute or a relative link (e.g. absolute: "https://example.com" or relative: "/admin/service-accounts"). If "dialog", will display a dialog when clicked. If not specified, no link will be displayed.

    • linkText string nullable

      The text to display on the link. If not specified, will be displayed as "More info".

    • dialogTitle string nullable

      The title to display on the dialog. If not specified, this will be the same as linkText.

    • dialog string nullable

      The markdown to display on the dialog. If not specified, no dialog will be displayed.

    • createdAt date-time required

      The date and time of when the banner was created.

    • ]
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-base-users-and-groups.html b/reference/api/unleash/get-base-users-and-groups.html index 95dac9a9dc..c135cbd3de 100644 --- a/reference/api/unleash/get-base-users-and-groups.html +++ b/reference/api/unleash/get-base-users-and-groups.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Get basic user and group information

    GET /api/admin/user-admin/access

    Get a subset of user and group information eligible even for non-admin users

    Request​

    Responses

    usersGroupsBaseSchema

    Schema
    • groups object[]

      A list of user groups and their configuration.

    • Array [
    • id integer

      The group id

    • name string required

      The name of the group

    • description string nullable

      A custom description of the group

    • mappingsSSO string[]

      A list of SSO groups that should map to this Unleash group

    • rootRole number nullable

      A role id that is used as the root role for all users in this group. This can be either the id of the Viewer, Editor or Admin role.

    • createdBy string nullable

      A user who created this group

    • createdAt date-time nullable

      When was this group created

    • users object[]

      A list of users belonging to this group

    • Array [
    • joinedAt date-time

      The date when the user joined the group

    • createdBy string nullable

      The username of the user who added this user to this group

    • user objectrequired

      An Unleash user

    • id integer required

      The user id

    • isAPI boolean deprecated

      (Deprecated): Used internally to know which operations the user should be allowed to perform

    • name string nullable

      Name of the user

    • email string

      Email of the user

    • username string nullable

      A unique username for the user

    • imageUrl string

      URL used for the userprofile image

    • inviteLink string

      If the user is actively inviting other users, this is the link that can be shared with other users

    • loginAttempts integer

      How many unsuccessful attempts at logging in has the user made

    • emailSent boolean

      Is the welcome email sent to the user or not

    • rootRole integer

      Which root role this user is assigned

    • seenAt date-time nullable

      The last time this user logged in

    • createdAt date-time

      The user was created at this time

    • accountType string

      A user is either an actual User or a Service Account

    • permissions string[]

      Deprecated

    • ]
    • projects string[]

      A list of projects where this group is used

    • userCount integer

      The number of users that belong to this group

    • ]
    • users object[]

      A list of users.

    • Array [
    • id integer required

      The user id

    • isAPI boolean deprecated

      (Deprecated): Used internally to know which operations the user should be allowed to perform

    • name string nullable

      Name of the user

    • email string

      Email of the user

    • username string nullable

      A unique username for the user

    • imageUrl string

      URL used for the userprofile image

    • inviteLink string

      If the user is actively inviting other users, this is the link that can be shared with other users

    • loginAttempts integer

      How many unsuccessful attempts at logging in has the user made

    • emailSent boolean

      Is the welcome email sent to the user or not

    • rootRole integer

      Which root role this user is assigned

    • seenAt date-time nullable

      The last time this user logged in

    • createdAt date-time

      The user was created at this time

    • accountType string

      A user is either an actual User or a Service Account

    • permissions string[]

      Deprecated

    • ]
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-change-request.html b/reference/api/unleash/get-change-request.html index 9c7a4be476..ca750d6160 100644 --- a/reference/api/unleash/get-change-request.html +++ b/reference/api/unleash/get-change-request.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Retrieves one change request by id

    GET /api/admin/projects/:projectId/change-requests/:id

    This endpoint will retrieve one change request if it matches the provided id.

    Request​

    Path Parameters

    • projectId string required
    • id string required
    Responses

    changeRequestSchema

    Schema
      oneOf
    • id number required

      This change requests's ID.

    • title string

      A title describing the change request's content.

    • environment string required

      The environment in which the changes should be applied.

    • minApprovals number required

      The minimum number of approvals required before this change request can be applied.

    • project string required

      The project this change request belongs to.

    • features object[]required

      The list of features and their changes that relate to this change request.

    • Array [
    • name string required

      The name of the feature

    • conflict string

      A string describing the conflicts related to this change. Only present if there are any concflicts on the feature level.

    • changes object[]required

      List of changes inside change request. This list may be empty when listing all change requests for a project.

    • Array [
    • id number required

      The ID of this change.

    • action string required

      The kind of action that the change contains information about.

    • conflict string

      A description of the conflict caused by this change. Only present if there are any conflicts.

    • payload objectrequired

      The data required to perform this action.

      oneOf
    • string
    • createdBy object

      The user who created this change.

    • username string nullable

      The user's username.

    • imageUrl uri nullable

      The URL where the user's image can be found.

    • createdAt date-time

      When this change was suggested

    • ]
    • defaultChange object

      A description of a default change that will be applied with the change request to prevent invalid states.

      Default changes are changes that are applied in addition to explicit user-specified changes when a change request is applied. Any default changes are applied in the background and are not a real part of the change request.

    • action string required

      The kind of action this is.

    • payload object required

      The necessary data to perform this change.

    • ]
    • segments object[]required

      The list of segments and their changes that relate to this change request.

    • Array [
    • id number required

      The ID of this change.

    • action string required

      The kind of action that the change contains information about.

    • conflict string

      A description of the conflict caused by this change. Only present if there are any conflicts.

    • payload objectrequired

      The data required to perform this action.

      oneOf
    • string
    • createdBy object

      The user who created this change.

    • username string nullable

      The user's username.

    • imageUrl uri nullable

      The URL where the user's image can be found.

    • createdAt date-time

      When this change was suggested

    • name string required

      The current name of the segment

    • ]
    • approvals object[]

      A list of approvals that this change request has received.

    • Array [
    • createdBy objectrequired

      Information about the user who gave this approval.

    • id number

      The ID of the user who gave this approval.

    • username string

      The approving user's username.

    • imageUrl uri

      The URL where the user's image can be found.

    • createdAt date-time required

      When the approval was given.

    • ]
    • rejections object[]

      A list of rejections that this change request has received.

    • Array [
    • createdBy objectrequired

      Information about the user who gave this approval.

    • id number

      The ID of the user who gave this approval.

    • username string

      The approving user's username.

    • imageUrl uri

      The URL where the user's image can be found.

    • createdAt date-time required

      When the approval was given.

    • ]
    • comments object[]

      All comments that have been made on this change request.

    • Array [
    • id number

      The comment's ID. Unique per change request.

    • text string required

      The content of the comment.

    • createdBy objectrequired

      Information about the user who posted the comment

    • username string nullable

      The user's username.

    • imageUrl uri nullable

      The URL where the user's image can be found.

    • createdAt date-time required

      When the comment was made.

    • ]
    • createdBy objectrequired

      The user who created this change request.

    • username string nullable
    • imageUrl uri nullable

      The URL of the user's profile image.

    • createdAt date-time required

      When this change request was created.

    • state string required

      Possible values: [Draft, In review, Approved, Applied, Cancelled, Rejected]

      The current state of the change request.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-change-requests-for-project.html b/reference/api/unleash/get-change-requests-for-project.html index d8d19e104b..838a211837 100644 --- a/reference/api/unleash/get-change-requests-for-project.html +++ b/reference/api/unleash/get-change-requests-for-project.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Retrieves all change requests for a project

    GET /api/admin/projects/:projectId/change-requests

    This endpoint will retrieve all change requests regardless of status for a given project. There's an upper limit of last 300 change requests ordered by creation date.

    Request​

    Path Parameters

    • projectId string required
    Responses

    changeRequestsSchema

    Schema
    • Array [
      • oneOf
    • id number required

      This change requests's ID.

    • title string

      A title describing the change request's content.

    • environment string required

      The environment in which the changes should be applied.

    • minApprovals number required

      The minimum number of approvals required before this change request can be applied.

    • project string required

      The project this change request belongs to.

    • features object[]required

      The list of features and their changes that relate to this change request.

    • Array [
    • name string required

      The name of the feature

    • conflict string

      A string describing the conflicts related to this change. Only present if there are any concflicts on the feature level.

    • changes object[]required

      List of changes inside change request. This list may be empty when listing all change requests for a project.

    • Array [
    • id number required

      The ID of this change.

    • action string required

      The kind of action that the change contains information about.

    • conflict string

      A description of the conflict caused by this change. Only present if there are any conflicts.

    • payload objectrequired

      The data required to perform this action.

      oneOf
    • string
    • createdBy object

      The user who created this change.

    • username string nullable

      The user's username.

    • imageUrl uri nullable

      The URL where the user's image can be found.

    • createdAt date-time

      When this change was suggested

    • ]
    • defaultChange object

      A description of a default change that will be applied with the change request to prevent invalid states.

      Default changes are changes that are applied in addition to explicit user-specified changes when a change request is applied. Any default changes are applied in the background and are not a real part of the change request.

    • action string required

      The kind of action this is.

    • payload object required

      The necessary data to perform this change.

    • ]
    • segments object[]required

      The list of segments and their changes that relate to this change request.

    • Array [
    • id number required

      The ID of this change.

    • action string required

      The kind of action that the change contains information about.

    • conflict string

      A description of the conflict caused by this change. Only present if there are any conflicts.

    • payload objectrequired

      The data required to perform this action.

      oneOf
    • string
    • createdBy object

      The user who created this change.

    • username string nullable

      The user's username.

    • imageUrl uri nullable

      The URL where the user's image can be found.

    • createdAt date-time

      When this change was suggested

    • name string required

      The current name of the segment

    • ]
    • approvals object[]

      A list of approvals that this change request has received.

    • Array [
    • createdBy objectrequired

      Information about the user who gave this approval.

    • id number

      The ID of the user who gave this approval.

    • username string

      The approving user's username.

    • imageUrl uri

      The URL where the user's image can be found.

    • createdAt date-time required

      When the approval was given.

    • ]
    • rejections object[]

      A list of rejections that this change request has received.

    • Array [
    • createdBy objectrequired

      Information about the user who gave this approval.

    • id number

      The ID of the user who gave this approval.

    • username string

      The approving user's username.

    • imageUrl uri

      The URL where the user's image can be found.

    • createdAt date-time required

      When the approval was given.

    • ]
    • comments object[]

      All comments that have been made on this change request.

    • Array [
    • id number

      The comment's ID. Unique per change request.

    • text string required

      The content of the comment.

    • createdBy objectrequired

      Information about the user who posted the comment

    • username string nullable

      The user's username.

    • imageUrl uri nullable

      The URL where the user's image can be found.

    • createdAt date-time required

      When the comment was made.

    • ]
    • createdBy objectrequired

      The user who created this change request.

    • username string nullable
    • imageUrl uri nullable

      The URL of the user's profile image.

    • createdAt date-time required

      When this change request was created.

    • state string required

      Possible values: [Draft, In review, Approved, Applied, Cancelled, Rejected]

      The current state of the change request.

    • ]
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-client-feature.html b/reference/api/unleash/get-client-feature.html index 900b4bafed..f018822499 100644 --- a/reference/api/unleash/get-client-feature.html +++ b/reference/api/unleash/get-client-feature.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Get a single feature toggle

    GET /api/client/features/:featureName

    Gets all the client data for a single toggle. Contains the exact same information about a toggle as the /api/client/features endpoint does, but only contains data about the specified toggle. All SDKs should use /api/client/features

    Request​

    Path Parameters

    • featureName string required
    Responses

    clientFeatureSchema

    Schema
    • name string required

      The unique name of a feature toggle. Is validated to be URL safe on creation

    • type string

      What kind of feature flag is this. Refer to the documentation on feature toggle types for more information

    • description string nullable

      A description of the toggle

    • enabled boolean required

      Whether the feature flag is enabled for the current API key or not. This is ANDed with the evaluation results of the strategies list, so if this is false, the evaluation result will always be false

    • stale boolean

      If this is true Unleash believes this feature toggle has been active longer than Unleash expects a toggle of this type to be active

    • impressionData boolean nullable

      Set to true if SDKs should trigger impression events when this toggle is evaluated

    • project string

      Which project this feature toggle belongs to

    • strategies object[]

      Evaluation strategies for this toggle. Each entry in this list will be evaluated and ORed together

    • Array [
    • id string

      A uuid for the feature strategy

    • name string required

      The name or type of strategy

    • title string nullable

      A descriptive title for the strategy

    • disabled boolean nullable

      A toggle to disable the strategy. defaults to false. Disabled strategies are not evaluated or returned to the SDKs

    • featureName string

      The name or feature the strategy is attached to

    • sortOrder number

      The order of the strategy in the list

    • segments number[]

      A list of segment ids attached to the strategy

    • constraints object[]

      A list of the constraints attached to the strategy. See https://docs.getunleash.io/reference/strategy-constraints

    • Array [
    • contextName string required

      The name of the context field that this constraint should apply to.

    • operator string required

      Possible values: [NOT_IN, IN, STR_ENDS_WITH, STR_STARTS_WITH, STR_CONTAINS, NUM_EQ, NUM_GT, NUM_GTE, NUM_LT, NUM_LTE, DATE_AFTER, DATE_BEFORE, SEMVER_EQ, SEMVER_GT, SEMVER_LT]

      The operator to use when evaluating this constraint. For more information about the various operators, refer to the strategy constraint operator documentation.

    • caseInsensitive boolean

      Default value: false

      Whether the operator should be case sensitive or not. Defaults to false (being case sensitive).

    • inverted boolean

      Default value: false

      Whether the result should be negated or not. If true, will turn a true result into a false result and vice versa.

    • values string[]

      The context values that should be used for constraint evaluation. Use this property instead of value for properties that accept multiple values.

    • value string

      The context value that should be used for constraint evaluation. Use this property instead of values for properties that only accept single values.

    • ]
    • variants object[]

      Strategy level variants

    • Array [
    • name string required

      The variant name. Must be unique for this feature toggle

    • weight integer required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is an integer between 0 and 1000. See the section on variant weights for more information

    • weightType string required

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000. Refer to the variant weight documentation.

    • stickiness string required

      The stickiness to use for distribution of this variant. Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • ]
    • parameters object

      A list of parameters for a strategy

    • property name* string
    • ]
    • variants object[]nullable

      Variants configured for this toggle

    • Array [
    • name string required

      The variants name. Is unique for this feature toggle

    • weight number required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is a number between 0 and 1000. See the section on variant weights for more information

    • weightType string

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000

    • stickiness string

      Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • overrides object[]

      Overrides assigning specific variants to specific users. The weighting system automatically assigns users to specific groups for you, but any overrides in this list will take precedence.

    • Array [
    • contextName string required

      The name of the context field used to determine overrides

    • values string[] required

      Which values that should be overriden

    • ]
    • ]
    • dependencies object[]

      Feature dependencies for this toggle

    • Array [
    • feature string required

      The name of the feature we depend on.

    • enabled boolean

      Whether the parent feature should be enabled. When false variants are ignored. true by default.

    • variants string[]

      The list of variants the parent feature should resolve to. Leave empty when you only want to check the enabled status.

    • ]
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-context-field.html b/reference/api/unleash/get-context-field.html index 65f160d869..88fee6334f 100644 --- a/reference/api/unleash/get-context-field.html +++ b/reference/api/unleash/get-context-field.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Gets context field

    GET /api/admin/context/:contextField

    Returns specific context field identified by the name in the path

    Request​

    Path Parameters

    • contextField string required
    Responses

    contextFieldSchema

    Schema
    • name string required

      The name of the context field

    • description string nullable

      The description of the context field.

    • stickiness boolean

      Does this context field support being used for stickiness calculations

    • sortOrder integer

      Used when sorting a list of context fields. Is also used as a tiebreaker if a list of context fields is sorted alphabetically.

    • createdAt date-time nullable

      When this context field was created

    • usedInFeatures integer nullable

      Number of projects where this context field is used in

    • usedInProjects integer nullable

      Number of projects where this context field is used in

    • legalValues object[]

      Allowed values for this context field schema. Can be used to narrow down accepted input

    • Array [
    • value string required

      The valid value

    • description string

      Describes this specific legal value

    • ]
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-context-fields.html b/reference/api/unleash/get-context-fields.html index c3a538a190..5f8ebcccd7 100644 --- a/reference/api/unleash/get-context-fields.html +++ b/reference/api/unleash/get-context-fields.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Gets configured context fields

    GET /api/admin/context

    Returns all configured Context fields that have been created.

    Request​

    Responses

    contextFieldsSchema

    Schema
    • Array [
    • name string required

      The name of the context field

    • description string nullable

      The description of the context field.

    • stickiness boolean

      Does this context field support being used for stickiness calculations

    • sortOrder integer

      Used when sorting a list of context fields. Is also used as a tiebreaker if a list of context fields is sorted alphabetically.

    • createdAt date-time nullable

      When this context field was created

    • usedInFeatures integer nullable

      Number of projects where this context field is used in

    • usedInProjects integer nullable

      Number of projects where this context field is used in

    • legalValues object[]

      Allowed values for this context field schema. Can be used to narrow down accepted input

    • Array [
    • value string required

      The valid value

    • description string

      Describes this specific legal value

    • ]
    • ]
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-deprecated-project-overview.html b/reference/api/unleash/get-deprecated-project-overview.html index b512596848..7aec0953d5 100644 --- a/reference/api/unleash/get-deprecated-project-overview.html +++ b/reference/api/unleash/get-deprecated-project-overview.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Get an overview of a project. (deprecated)

    GET /api/admin/projects/:projectId
    deprecated

    This endpoint has been deprecated and may be removed in future versions of the API.

    This endpoint returns an overview of the specified projects stats, project health, number of members, which environments are configured, and the features in the project.

    Request​

    Path Parameters

    • projectId string required
    Responses

    deprecatedProjectOverviewSchema

    Schema
    • stats object

      Project statistics

    • avgTimeToProdCurrentWindow number required

      The average time from when a feature was created to when it was enabled in the "production" environment during the current window

    • createdCurrentWindow number required

      The number of feature toggles created during the current window

    • createdPastWindow number required

      The number of feature toggles created during the previous window

    • archivedCurrentWindow number required

      The number of feature toggles that were archived during the current window

    • archivedPastWindow number required

      The number of feature toggles that were archived during the previous window

    • projectActivityCurrentWindow number required

      The number of project events that occurred during the current window

    • projectActivityPastWindow number required

      The number of project events that occurred during the previous window

    • projectMembersAddedCurrentWindow number required

      The number of members that were added to the project during the current window

    • version integer required

      The schema version used to describe the project overview

    • name string required

      The name of this project

    • description string nullable

      Additional information about the project

    • defaultStickiness string

      A default stickiness for the project affecting the default stickiness value for variants and Gradual Rollout strategy

    • mode string

      Possible values: [open, protected, private]

      The project's collaboration mode. Determines whether non-project members can submit change requests or not.

    • featureLimit number nullable

      A limit on the number of features allowed in the project. Null if no limit.

    • featureNaming object

      Create a feature naming pattern

    • pattern string nullable required

      A JavaScript regular expression pattern, without the start and end delimiters. Optional flags are not allowed.

    • example string nullable

      An example of a feature name that matches the pattern. Must itself match the pattern supplied.

    • description string nullable

      A description of the pattern in a human-readable format. Will be shown to users when they create a new feature flag.

    • members number

      The number of members this project has

    • health number

      An indicator of the project's health on a scale from 0 to 100

    • environments object[]

      The environments that are enabled for this project

    • Array [
    • environment string required

      The environment to add to the project

    • changeRequestsEnabled boolean

      Whether change requests should be enabled or for this environment on the project or not

    • defaultStrategy object

      A default strategy to create for this environment on the project.

    • name string required

      The name of the strategy type

    • title string nullable

      A descriptive title for the strategy

    • disabled boolean nullable

      A toggle to disable the strategy. defaults to false. Disabled strategies are not evaluated or returned to the SDKs

    • sortOrder number

      The order of the strategy in the list

    • constraints object[]

      A list of the constraints attached to the strategy. See https://docs.getunleash.io/reference/strategy-constraints

    • Array [
    • contextName string required

      The name of the context field that this constraint should apply to.

    • operator string required

      Possible values: [NOT_IN, IN, STR_ENDS_WITH, STR_STARTS_WITH, STR_CONTAINS, NUM_EQ, NUM_GT, NUM_GTE, NUM_LT, NUM_LTE, DATE_AFTER, DATE_BEFORE, SEMVER_EQ, SEMVER_GT, SEMVER_LT]

      The operator to use when evaluating this constraint. For more information about the various operators, refer to the strategy constraint operator documentation.

    • caseInsensitive boolean

      Default value: false

      Whether the operator should be case sensitive or not. Defaults to false (being case sensitive).

    • inverted boolean

      Default value: false

      Whether the result should be negated or not. If true, will turn a true result into a false result and vice versa.

    • values string[]

      The context values that should be used for constraint evaluation. Use this property instead of value for properties that accept multiple values.

    • value string

      The context value that should be used for constraint evaluation. Use this property instead of values for properties that only accept single values.

    • ]
    • variants object[]

      Strategy level variants

    • Array [
    • name string required

      The variant name. Must be unique for this feature toggle

    • weight integer required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is an integer between 0 and 1000. See the section on variant weights for more information

    • weightType string required

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000. Refer to the variant weight documentation.

    • stickiness string required

      The stickiness to use for distribution of this variant. Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • ]
    • parameters object

      A list of parameters for a strategy

    • property name* string
    • segments number[]

      Ids of segments to use for this strategy

    • ]
    • features object[]

      The full list of features in this project (excluding archived features)

    • Array [
    • name string required

      Unique feature name

    • type string

      Type of the toggle e.g. experiment, kill-switch, release, operational, permission

    • description string nullable

      Detailed description of the feature

    • archived boolean

      true if the feature is archived

    • project string

      Name of the project the feature belongs to

    • enabled boolean

      true if the feature is enabled, otherwise false.

    • stale boolean

      true if the feature is stale based on the age and feature type, otherwise false.

    • favorite boolean

      true if the feature was favorited, otherwise false.

    • impressionData boolean

      true if the impression data collection is enabled for the feature, otherwise false.

    • createdAt date-time nullable

      The date the feature was created

    • archivedAt date-time nullable

      The date the feature was archived

    • lastSeenAt date-time nullable deprecated

      The date when metrics where last collected for the feature. This field is deprecated, use the one in featureEnvironmentSchema

    • environments object[]

      The list of environments where the feature can be used

    • Array [
    • name string required

      The name of the environment

    • featureName string

      The name of the feature

    • environment string

      The name of the environment

    • type string

      The type of the environment

    • enabled boolean required

      true if the feature is enabled for the environment, otherwise false.

    • sortOrder number

      The sort order of the feature environment in the feature environments list

    • variantCount number

      The number of defined variants

    • strategies object[]

      A list of activation strategies for the feature environment

    • Array [
    • id string

      A uuid for the feature strategy

    • name string required

      The name or type of strategy

    • title string nullable

      A descriptive title for the strategy

    • disabled boolean nullable

      A toggle to disable the strategy. defaults to false. Disabled strategies are not evaluated or returned to the SDKs

    • featureName string

      The name or feature the strategy is attached to

    • sortOrder number

      The order of the strategy in the list

    • segments number[]

      A list of segment ids attached to the strategy

    • constraints object[]

      A list of the constraints attached to the strategy. See https://docs.getunleash.io/reference/strategy-constraints

    • Array [
    • contextName string required

      The name of the context field that this constraint should apply to.

    • operator string required

      Possible values: [NOT_IN, IN, STR_ENDS_WITH, STR_STARTS_WITH, STR_CONTAINS, NUM_EQ, NUM_GT, NUM_GTE, NUM_LT, NUM_LTE, DATE_AFTER, DATE_BEFORE, SEMVER_EQ, SEMVER_GT, SEMVER_LT]

      The operator to use when evaluating this constraint. For more information about the various operators, refer to the strategy constraint operator documentation.

    • caseInsensitive boolean

      Default value: false

      Whether the operator should be case sensitive or not. Defaults to false (being case sensitive).

    • inverted boolean

      Default value: false

      Whether the result should be negated or not. If true, will turn a true result into a false result and vice versa.

    • values string[]

      The context values that should be used for constraint evaluation. Use this property instead of value for properties that accept multiple values.

    • value string

      The context value that should be used for constraint evaluation. Use this property instead of values for properties that only accept single values.

    • ]
    • variants object[]

      Strategy level variants

    • Array [
    • name string required

      The variant name. Must be unique for this feature toggle

    • weight integer required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is an integer between 0 and 1000. See the section on variant weights for more information

    • weightType string required

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000. Refer to the variant weight documentation.

    • stickiness string required

      The stickiness to use for distribution of this variant. Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • ]
    • parameters object

      A list of parameters for a strategy

    • property name* string
    • ]
    • variants object[]

      A list of variants for the feature environment

    • Array [
    • name string required

      The variants name. Is unique for this feature toggle

    • weight number required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is a number between 0 and 1000. See the section on variant weights for more information

    • weightType string

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000

    • stickiness string

      Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • overrides object[]

      Overrides assigning specific variants to specific users. The weighting system automatically assigns users to specific groups for you, but any overrides in this list will take precedence.

    • Array [
    • contextName string required

      The name of the context field used to determine overrides

    • values string[] required

      Which values that should be overriden

    • ]
    • ]
    • lastSeenAt date-time nullable

      The date when metrics where last collected for the feature environment

    • hasStrategies boolean

      Whether the feature has any strategies defined.

    • hasEnabledStrategies boolean

      Whether the feature has any enabled strategies defined.

    • ]
    • variants object[]deprecated

      The list of feature variants

    • Array [
    • name string required

      The variants name. Is unique for this feature toggle

    • weight number required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is a number between 0 and 1000. See the section on variant weights for more information

    • weightType string

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000

    • stickiness string

      Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • overrides object[]

      Overrides assigning specific variants to specific users. The weighting system automatically assigns users to specific groups for you, but any overrides in this list will take precedence.

    • Array [
    • contextName string required

      The name of the context field used to determine overrides

    • values string[] required

      Which values that should be overriden

    • ]
    • ]
    • strategies object[] deprecated

      This is a legacy field that will be deprecated

    • tags object[]nullable

      The list of feature tags

    • Array [
    • value string required

      Possible values: >= 2 characters and <= 50 characters

      The value of the tag

    • type string required

      Possible values: >= 2 characters and <= 50 characters

      Default value: simple

      The type of the tag

    • ]
    • children string[]

      The list of child feature names. This is an experimental field and may change.

    • dependencies object[]

      The list of parent dependencies. This is an experimental field and may change.

    • Array [
    • feature string required

      The name of the parent feature

    • enabled boolean

      Whether the parent feature is enabled or not

    • variants string[]

      The list of variants the parent feature should resolve to. Only valid when feature is enabled.

    • ]
    • ]
    • updatedAt date-time nullable

      When the project was last updated.

    • createdAt date-time nullable

      When the project was created.

    • favorite boolean

      true if the project was favorited, otherwise false.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-environment-feature-variants.html b/reference/api/unleash/get-environment-feature-variants.html index e848be5bd2..9536196863 100644 --- a/reference/api/unleash/get-environment-feature-variants.html +++ b/reference/api/unleash/get-environment-feature-variants.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Get variants for a feature in an environment

    GET /api/admin/projects/:projectId/features/:featureName/environments/:environment/variants

    Returns the variants for a feature in a specific environment. If the feature has no variants it will return an empty array of variants

    Request​

    Path Parameters

    • projectId string required
    • featureName string required
    • environment string required
    Responses

    featureVariantsSchema

    Schema
    • version integer required

      The version of the feature variants schema.

    • variants object[]required

      All variants defined for a specific feature toggle.

    • Array [
    • name string required

      The variants name. Is unique for this feature toggle

    • weight number required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is a number between 0 and 1000. See the section on variant weights for more information

    • weightType string

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000

    • stickiness string

      Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • overrides object[]

      Overrides assigning specific variants to specific users. The weighting system automatically assigns users to specific groups for you, but any overrides in this list will take precedence.

    • Array [
    • contextName string required

      The name of the context field used to determine overrides

    • values string[] required

      Which values that should be overriden

    • ]
    • ]
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-environment.html b/reference/api/unleash/get-environment.html index b635e0f1ce..f899e83cd2 100644 --- a/reference/api/unleash/get-environment.html +++ b/reference/api/unleash/get-environment.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Get the environment with `name`

    GET /api/admin/environments/:name

    Retrieves the environment with name if it exists in this Unleash instance

    Request​

    Path Parameters

    • name string required
    Responses

    environmentSchema

    Schema
    • name string required

      The name of the environment

    • type string required
    • enabled boolean required

      true if the environment is enabled for the project, otherwise false.

    • protected boolean required

      true if the environment is protected, otherwise false. A protected environment can not be deleted.

    • sortOrder integer required

      Priority of the environment in a list of environments, the lower the value, the higher up in the list the environment will appear. Needs to be an integer

    • projectCount integer nullable

      The number of projects with this environment

    • apiTokenCount integer nullable

      The number of API tokens for the project environment

    • enabledToggleCount integer nullable

      The number of enabled toggles for the project environment

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-events-for-toggle.html b/reference/api/unleash/get-events-for-toggle.html index 4752078e1f..7913ee54c1 100644 --- a/reference/api/unleash/get-events-for-toggle.html +++ b/reference/api/unleash/get-events-for-toggle.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Get all events related to a specific feature toggle.

    GET /api/admin/events/:featureName

    Returns all events related to the specified feature toggle. If the feature toggle does not exist, the list of events will be empty.

    Request​

    Path Parameters

    • featureName string required
    Responses

    featureEventsSchema

    Schema
    • version integer

      Possible values: >= 1, [1]

      An API versioning number

    • toggleName string

      The name of the feature toggle these events relate to

    • events object[]required

      The list of events

    • Array [
    • id integer required

      Possible values: >= 1

      The ID of the event. An increasing natural number.

    • createdAt date-time required

      The time the event happened as a RFC 3339-conformant timestamp.

    • type string required

      Possible values: [application-created, feature-created, feature-deleted, feature-updated, feature-metadata-updated, feature-variants-updated, feature-environment-variants-updated, feature-project-change, feature-archived, feature-revived, feature-import, feature-tagged, feature-tag-import, feature-strategy-update, feature-strategy-add, feature-strategy-remove, feature-type-updated, strategy-order-changed, drop-feature-tags, feature-untagged, feature-stale-on, feature-stale-off, drop-features, feature-environment-enabled, feature-environment-disabled, strategy-created, strategy-deleted, strategy-deprecated, strategy-reactivated, strategy-updated, strategy-import, drop-strategies, context-field-created, context-field-updated, context-field-deleted, project-access-added, project-access-user-roles-updated, project-access-group-roles-updated, project-access-user-roles-deleted, project-access-group-roles-deleted, project-access-updated, project-created, project-updated, project-deleted, project-import, project-user-added, project-user-removed, project-user-role-changed, project-group-role-changed, project-group-added, project-group-removed, role-created, role-updated, role-deleted, drop-projects, tag-created, tag-deleted, tag-import, drop-tags, tag-type-created, tag-type-deleted, tag-type-updated, tag-type-import, drop-tag-types, addon-config-created, addon-config-updated, addon-config-deleted, db-pool-update, user-created, user-updated, user-deleted, drop-environments, environment-import, environment-created, environment-updated, environment-deleted, segment-created, segment-updated, segment-deleted, group-created, group-updated, group-deleted, group-user-added, group-user-removed, setting-created, setting-updated, setting-deleted, client-metrics, client-register, pat-created, pat-deleted, public-signup-token-created, public-signup-token-user-added, public-signup-token-updated, change-request-created, change-request-discarded, change-added, change-discarded, change-edited, change-request-rejected, change-request-approved, change-request-approval-added, change-request-cancelled, change-request-sent-to-review, scheduled-change-request-executed, change-request-applied, change-request-scheduled, change-request-scheduled-application-success, change-request-scheduled-application-failure, change-request-configuration-updated, api-token-created, api-token-updated, api-token-deleted, feature-favorited, feature-unfavorited, project-favorited, project-unfavorited, features-exported, features-imported, service-account-created, service-account-deleted, service-account-updated, feature-potentially-stale-on, feature-dependency-added, feature-dependency-removed, feature-dependencies-removed, banner-created, banner-updated, banner-deleted, project-environment-added, project-environment-removed, default-strategy-updated, segment-import, incoming-webhook-created, incoming-webhook-updated, incoming-webhook-deleted, incoming-webhook-token-created, incoming-webhook-token-updated, incoming-webhook-token-deleted]

      What type of event this is

    • createdBy string required

      Which user created this event

    • createdByUserId number nullable

      The is of the user that created this event

    • environment string nullable

      The feature toggle environment the event relates to, if applicable.

    • project string nullable

      The project the event relates to, if applicable.

    • featureName string nullable

      The name of the feature toggle the event relates to, if applicable.

    • data object nullable

      Extra associated data related to the event, such as feature toggle state, segment configuration, etc., if applicable.

    • preData object nullable

      Data relating to the previous state of the event's subject.

    • tags object[]nullable

      Any tags related to the event, if applicable.

    • Array [
    • value string required

      Possible values: >= 2 characters and <= 50 characters

      The value of the tag

    • type string required

      Possible values: >= 2 characters and <= 50 characters

      Default value: simple

      The type of the tag

    • ]
    • ]
    • totalEvents integer

      How many events are there for this feature toggle

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-events.html b/reference/api/unleash/get-events.html index 0af1e52459..9d55f7804c 100644 --- a/reference/api/unleash/get-events.html +++ b/reference/api/unleash/get-events.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Get the most recent events from the Unleash instance or all events related to a project.

    GET /api/admin/events

    Returns the last 100 events from the Unleash instance when called without a query parameter. When called with a project parameter, returns all events for the specified project.

    If the provided project does not exist, the list of events will be empty.

    Request​

    Query Parameters

    • project string

      The name of the project whose events you want to retrieve

    Responses

    eventsSchema

    Schema
    • version integer required

      Possible values: >= 1, [1]

      The api version of this response. A natural increasing number. Only increases if format changes

    • events object[]required

      The list of events

    • Array [
    • id integer required

      Possible values: >= 1

      The ID of the event. An increasing natural number.

    • createdAt date-time required

      The time the event happened as a RFC 3339-conformant timestamp.

    • type string required

      Possible values: [application-created, feature-created, feature-deleted, feature-updated, feature-metadata-updated, feature-variants-updated, feature-environment-variants-updated, feature-project-change, feature-archived, feature-revived, feature-import, feature-tagged, feature-tag-import, feature-strategy-update, feature-strategy-add, feature-strategy-remove, feature-type-updated, strategy-order-changed, drop-feature-tags, feature-untagged, feature-stale-on, feature-stale-off, drop-features, feature-environment-enabled, feature-environment-disabled, strategy-created, strategy-deleted, strategy-deprecated, strategy-reactivated, strategy-updated, strategy-import, drop-strategies, context-field-created, context-field-updated, context-field-deleted, project-access-added, project-access-user-roles-updated, project-access-group-roles-updated, project-access-user-roles-deleted, project-access-group-roles-deleted, project-access-updated, project-created, project-updated, project-deleted, project-import, project-user-added, project-user-removed, project-user-role-changed, project-group-role-changed, project-group-added, project-group-removed, role-created, role-updated, role-deleted, drop-projects, tag-created, tag-deleted, tag-import, drop-tags, tag-type-created, tag-type-deleted, tag-type-updated, tag-type-import, drop-tag-types, addon-config-created, addon-config-updated, addon-config-deleted, db-pool-update, user-created, user-updated, user-deleted, drop-environments, environment-import, environment-created, environment-updated, environment-deleted, segment-created, segment-updated, segment-deleted, group-created, group-updated, group-deleted, group-user-added, group-user-removed, setting-created, setting-updated, setting-deleted, client-metrics, client-register, pat-created, pat-deleted, public-signup-token-created, public-signup-token-user-added, public-signup-token-updated, change-request-created, change-request-discarded, change-added, change-discarded, change-edited, change-request-rejected, change-request-approved, change-request-approval-added, change-request-cancelled, change-request-sent-to-review, scheduled-change-request-executed, change-request-applied, change-request-scheduled, change-request-scheduled-application-success, change-request-scheduled-application-failure, change-request-configuration-updated, api-token-created, api-token-updated, api-token-deleted, feature-favorited, feature-unfavorited, project-favorited, project-unfavorited, features-exported, features-imported, service-account-created, service-account-deleted, service-account-updated, feature-potentially-stale-on, feature-dependency-added, feature-dependency-removed, feature-dependencies-removed, banner-created, banner-updated, banner-deleted, project-environment-added, project-environment-removed, default-strategy-updated, segment-import, incoming-webhook-created, incoming-webhook-updated, incoming-webhook-deleted, incoming-webhook-token-created, incoming-webhook-token-updated, incoming-webhook-token-deleted]

      What type of event this is

    • createdBy string required

      Which user created this event

    • createdByUserId number nullable

      The is of the user that created this event

    • environment string nullable

      The feature toggle environment the event relates to, if applicable.

    • project string nullable

      The project the event relates to, if applicable.

    • featureName string nullable

      The name of the feature toggle the event relates to, if applicable.

    • data object nullable

      Extra associated data related to the event, such as feature toggle state, segment configuration, etc., if applicable.

    • preData object nullable

      Data relating to the previous state of the event's subject.

    • tags object[]nullable

      Any tags related to the event, if applicable.

    • Array [
    • value string required

      Possible values: >= 2 characters and <= 50 characters

      The value of the tag

    • type string required

      Possible values: >= 2 characters and <= 50 characters

      Default value: simple

      The type of the tag

    • ]
    • ]
    • totalEvents integer

      The total count of events

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-feature-environment.html b/reference/api/unleash/get-feature-environment.html index 3d55767326..1351460ef0 100644 --- a/reference/api/unleash/get-feature-environment.html +++ b/reference/api/unleash/get-feature-environment.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Get a feature environment

    GET /api/admin/projects/:projectId/features/:featureName/environments/:environment

    Information about the enablement status and strategies for a feature toggle in specified environment.

    Request​

    Path Parameters

    • projectId string required
    • featureName string required
    • environment string required
    Responses

    featureEnvironmentSchema

    Schema
    • name string required

      The name of the environment

    • featureName string

      The name of the feature

    • environment string

      The name of the environment

    • type string

      The type of the environment

    • enabled boolean required

      true if the feature is enabled for the environment, otherwise false.

    • sortOrder number

      The sort order of the feature environment in the feature environments list

    • variantCount number

      The number of defined variants

    • strategies object[]

      A list of activation strategies for the feature environment

    • Array [
    • id string

      A uuid for the feature strategy

    • name string required

      The name or type of strategy

    • title string nullable

      A descriptive title for the strategy

    • disabled boolean nullable

      A toggle to disable the strategy. defaults to false. Disabled strategies are not evaluated or returned to the SDKs

    • featureName string

      The name or feature the strategy is attached to

    • sortOrder number

      The order of the strategy in the list

    • segments number[]

      A list of segment ids attached to the strategy

    • constraints object[]

      A list of the constraints attached to the strategy. See https://docs.getunleash.io/reference/strategy-constraints

    • Array [
    • contextName string required

      The name of the context field that this constraint should apply to.

    • operator string required

      Possible values: [NOT_IN, IN, STR_ENDS_WITH, STR_STARTS_WITH, STR_CONTAINS, NUM_EQ, NUM_GT, NUM_GTE, NUM_LT, NUM_LTE, DATE_AFTER, DATE_BEFORE, SEMVER_EQ, SEMVER_GT, SEMVER_LT]

      The operator to use when evaluating this constraint. For more information about the various operators, refer to the strategy constraint operator documentation.

    • caseInsensitive boolean

      Default value: false

      Whether the operator should be case sensitive or not. Defaults to false (being case sensitive).

    • inverted boolean

      Default value: false

      Whether the result should be negated or not. If true, will turn a true result into a false result and vice versa.

    • values string[]

      The context values that should be used for constraint evaluation. Use this property instead of value for properties that accept multiple values.

    • value string

      The context value that should be used for constraint evaluation. Use this property instead of values for properties that only accept single values.

    • ]
    • variants object[]

      Strategy level variants

    • Array [
    • name string required

      The variant name. Must be unique for this feature toggle

    • weight integer required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is an integer between 0 and 1000. See the section on variant weights for more information

    • weightType string required

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000. Refer to the variant weight documentation.

    • stickiness string required

      The stickiness to use for distribution of this variant. Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • ]
    • parameters object

      A list of parameters for a strategy

    • property name* string
    • ]
    • variants object[]

      A list of variants for the feature environment

    • Array [
    • name string required

      The variants name. Is unique for this feature toggle

    • weight number required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is a number between 0 and 1000. See the section on variant weights for more information

    • weightType string

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000

    • stickiness string

      Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • overrides object[]

      Overrides assigning specific variants to specific users. The weighting system automatically assigns users to specific groups for you, but any overrides in this list will take precedence.

    • Array [
    • contextName string required

      The name of the context field used to determine overrides

    • values string[] required

      Which values that should be overriden

    • ]
    • ]
    • lastSeenAt date-time nullable

      The date when metrics where last collected for the feature environment

    • hasStrategies boolean

      Whether the feature has any strategies defined.

    • hasEnabledStrategies boolean

      Whether the feature has any enabled strategies defined.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-feature-strategies.html b/reference/api/unleash/get-feature-strategies.html index 19c6f6d2c2..22a0e0532e 100644 --- a/reference/api/unleash/get-feature-strategies.html +++ b/reference/api/unleash/get-feature-strategies.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Get feature toggle strategies

    GET /api/admin/projects/:projectId/features/:featureName/environments/:environment/strategies

    Get strategies defined for a feature toggle in the specified environment.

    Request​

    Path Parameters

    • projectId string required
    • featureName string required
    • environment string required
    Responses

    featureStrategySchema

    Schema
    • id string

      A uuid for the feature strategy

    • name string required

      The name or type of strategy

    • title string nullable

      A descriptive title for the strategy

    • disabled boolean nullable

      A toggle to disable the strategy. defaults to false. Disabled strategies are not evaluated or returned to the SDKs

    • featureName string

      The name or feature the strategy is attached to

    • sortOrder number

      The order of the strategy in the list

    • segments number[]

      A list of segment ids attached to the strategy

    • constraints object[]

      A list of the constraints attached to the strategy. See https://docs.getunleash.io/reference/strategy-constraints

    • Array [
    • contextName string required

      The name of the context field that this constraint should apply to.

    • operator string required

      Possible values: [NOT_IN, IN, STR_ENDS_WITH, STR_STARTS_WITH, STR_CONTAINS, NUM_EQ, NUM_GT, NUM_GTE, NUM_LT, NUM_LTE, DATE_AFTER, DATE_BEFORE, SEMVER_EQ, SEMVER_GT, SEMVER_LT]

      The operator to use when evaluating this constraint. For more information about the various operators, refer to the strategy constraint operator documentation.

    • caseInsensitive boolean

      Default value: false

      Whether the operator should be case sensitive or not. Defaults to false (being case sensitive).

    • inverted boolean

      Default value: false

      Whether the result should be negated or not. If true, will turn a true result into a false result and vice versa.

    • values string[]

      The context values that should be used for constraint evaluation. Use this property instead of value for properties that accept multiple values.

    • value string

      The context value that should be used for constraint evaluation. Use this property instead of values for properties that only accept single values.

    • ]
    • variants object[]

      Strategy level variants

    • Array [
    • name string required

      The variant name. Must be unique for this feature toggle

    • weight integer required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is an integer between 0 and 1000. See the section on variant weights for more information

    • weightType string required

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000. Refer to the variant weight documentation.

    • stickiness string required

      The stickiness to use for distribution of this variant. Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • ]
    • parameters object

      A list of parameters for a strategy

    • property name* string
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-feature-strategy.html b/reference/api/unleash/get-feature-strategy.html index 3dd54028d8..86a7ed82ff 100644 --- a/reference/api/unleash/get-feature-strategy.html +++ b/reference/api/unleash/get-feature-strategy.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Get a strategy configuration

    GET /api/admin/projects/:projectId/features/:featureName/environments/:environment/strategies/:strategyId

    Get a strategy configuration for an environment in a feature toggle.

    Request​

    Path Parameters

    • projectId string required
    • featureName string required
    • environment string required
    • strategyId string required
    Responses

    featureStrategySchema

    Schema
    • id string

      A uuid for the feature strategy

    • name string required

      The name or type of strategy

    • title string nullable

      A descriptive title for the strategy

    • disabled boolean nullable

      A toggle to disable the strategy. defaults to false. Disabled strategies are not evaluated or returned to the SDKs

    • featureName string

      The name or feature the strategy is attached to

    • sortOrder number

      The order of the strategy in the list

    • segments number[]

      A list of segment ids attached to the strategy

    • constraints object[]

      A list of the constraints attached to the strategy. See https://docs.getunleash.io/reference/strategy-constraints

    • Array [
    • contextName string required

      The name of the context field that this constraint should apply to.

    • operator string required

      Possible values: [NOT_IN, IN, STR_ENDS_WITH, STR_STARTS_WITH, STR_CONTAINS, NUM_EQ, NUM_GT, NUM_GTE, NUM_LT, NUM_LTE, DATE_AFTER, DATE_BEFORE, SEMVER_EQ, SEMVER_GT, SEMVER_LT]

      The operator to use when evaluating this constraint. For more information about the various operators, refer to the strategy constraint operator documentation.

    • caseInsensitive boolean

      Default value: false

      Whether the operator should be case sensitive or not. Defaults to false (being case sensitive).

    • inverted boolean

      Default value: false

      Whether the result should be negated or not. If true, will turn a true result into a false result and vice versa.

    • values string[]

      The context values that should be used for constraint evaluation. Use this property instead of value for properties that accept multiple values.

    • value string

      The context value that should be used for constraint evaluation. Use this property instead of values for properties that only accept single values.

    • ]
    • variants object[]

      Strategy level variants

    • Array [
    • name string required

      The variant name. Must be unique for this feature toggle

    • weight integer required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is an integer between 0 and 1000. See the section on variant weights for more information

    • weightType string required

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000. Refer to the variant weight documentation.

    • stickiness string required

      The stickiness to use for distribution of this variant. Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • ]
    • parameters object

      A list of parameters for a strategy

    • property name* string
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-feature-usage-summary.html b/reference/api/unleash/get-feature-usage-summary.html index 45eb460c2e..c4b2b7e4ac 100644 --- a/reference/api/unleash/get-feature-usage-summary.html +++ b/reference/api/unleash/get-feature-usage-summary.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Last hour of usage and a list of applications that have reported seeing this feature toggle

    GET /api/admin/client-metrics/features/:name

    Separate counts for yes (enabled), no (disabled), as well as how many times each variant was selected during the last hour

    Request​

    Path Parameters

    • name string required
    Responses

    featureUsageSchema

    Schema
    • version integer required

      Possible values: >= 1

      The version of this schema

    • maturity string required

      The maturity level of this API (alpha, beta, stable, deprecated)

    • featureName string required

      The name of the feature

    • lastHourUsage object[]required

      Last hour statistics. Accumulated per feature per environment. Contains counts for evaluations to true (yes) and to false (no)

    • Array [
    • featureName string

      The name of the feature

    • appName string

      The name of the application the SDK is being used in

    • environment string required

      Which environment the SDK is being used in

    • timestamp objectrequired

      The start of the time window these metrics are valid for. The window is usually 1 hour wide

      oneOf
    • string date-time

      An RFC-3339-compliant timestamp.

    • yes integer required

      How many times the toggle evaluated to true

    • no integer required

      How many times the toggle evaluated to false

    • variants object

      How many times each variant was returned

    • property name* integer
    • ]
    • seenApplications string[] required

      A list of applications seen using this feature

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-feature-variants.html b/reference/api/unleash/get-feature-variants.html index 8bdc907eb4..4518124e81 100644 --- a/reference/api/unleash/get-feature-variants.html +++ b/reference/api/unleash/get-feature-variants.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Retrieve variants for a feature (deprecated) 

    GET /api/admin/projects/:projectId/features/:featureName/variants
    deprecated

    This endpoint has been deprecated and may be removed in future versions of the API.

    (deprecated from 4.21) Retrieve the variants for the specified feature. From Unleash 4.21 onwards, this endpoint will attempt to choose a production-type environment as the source of truth. If more than one production environment is found, the first one will be used.

    Request​

    Path Parameters

    • projectId string required
    • featureName string required
    Responses

    featureVariantsSchema

    Schema
    • version integer required

      The version of the feature variants schema.

    • variants object[]required

      All variants defined for a specific feature toggle.

    • Array [
    • name string required

      The variants name. Is unique for this feature toggle

    • weight number required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is a number between 0 and 1000. See the section on variant weights for more information

    • weightType string

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000

    • stickiness string

      Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • overrides object[]

      Overrides assigning specific variants to specific users. The weighting system automatically assigns users to specific groups for you, but any overrides in this list will take precedence.

    • Array [
    • contextName string required

      The name of the context field used to determine overrides

    • values string[] required

      Which values that should be overriden

    • ]
    • ]
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-feature.html b/reference/api/unleash/get-feature.html index d428907b5a..48d9ee8246 100644 --- a/reference/api/unleash/get-feature.html +++ b/reference/api/unleash/get-feature.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Get a feature

    GET /api/admin/projects/:projectId/features/:featureName

    This endpoint returns the information about the requested feature if the feature belongs to the specified project.

    Request​

    Path Parameters

    • projectId string required
    • featureName string required
    Responses

    featureSchema

    Schema
    • name string required

      Unique feature name

    • type string

      Type of the toggle e.g. experiment, kill-switch, release, operational, permission

    • description string nullable

      Detailed description of the feature

    • archived boolean

      true if the feature is archived

    • project string

      Name of the project the feature belongs to

    • enabled boolean

      true if the feature is enabled, otherwise false.

    • stale boolean

      true if the feature is stale based on the age and feature type, otherwise false.

    • favorite boolean

      true if the feature was favorited, otherwise false.

    • impressionData boolean

      true if the impression data collection is enabled for the feature, otherwise false.

    • createdAt date-time nullable

      The date the feature was created

    • archivedAt date-time nullable

      The date the feature was archived

    • lastSeenAt date-time nullable deprecated

      The date when metrics where last collected for the feature. This field is deprecated, use the one in featureEnvironmentSchema

    • environments object[]

      The list of environments where the feature can be used

    • Array [
    • name string required

      The name of the environment

    • featureName string

      The name of the feature

    • environment string

      The name of the environment

    • type string

      The type of the environment

    • enabled boolean required

      true if the feature is enabled for the environment, otherwise false.

    • sortOrder number

      The sort order of the feature environment in the feature environments list

    • variantCount number

      The number of defined variants

    • strategies object[]

      A list of activation strategies for the feature environment

    • Array [
    • id string

      A uuid for the feature strategy

    • name string required

      The name or type of strategy

    • title string nullable

      A descriptive title for the strategy

    • disabled boolean nullable

      A toggle to disable the strategy. defaults to false. Disabled strategies are not evaluated or returned to the SDKs

    • featureName string

      The name or feature the strategy is attached to

    • sortOrder number

      The order of the strategy in the list

    • segments number[]

      A list of segment ids attached to the strategy

    • constraints object[]

      A list of the constraints attached to the strategy. See https://docs.getunleash.io/reference/strategy-constraints

    • Array [
    • contextName string required

      The name of the context field that this constraint should apply to.

    • operator string required

      Possible values: [NOT_IN, IN, STR_ENDS_WITH, STR_STARTS_WITH, STR_CONTAINS, NUM_EQ, NUM_GT, NUM_GTE, NUM_LT, NUM_LTE, DATE_AFTER, DATE_BEFORE, SEMVER_EQ, SEMVER_GT, SEMVER_LT]

      The operator to use when evaluating this constraint. For more information about the various operators, refer to the strategy constraint operator documentation.

    • caseInsensitive boolean

      Default value: false

      Whether the operator should be case sensitive or not. Defaults to false (being case sensitive).

    • inverted boolean

      Default value: false

      Whether the result should be negated or not. If true, will turn a true result into a false result and vice versa.

    • values string[]

      The context values that should be used for constraint evaluation. Use this property instead of value for properties that accept multiple values.

    • value string

      The context value that should be used for constraint evaluation. Use this property instead of values for properties that only accept single values.

    • ]
    • variants object[]

      Strategy level variants

    • Array [
    • name string required

      The variant name. Must be unique for this feature toggle

    • weight integer required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is an integer between 0 and 1000. See the section on variant weights for more information

    • weightType string required

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000. Refer to the variant weight documentation.

    • stickiness string required

      The stickiness to use for distribution of this variant. Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • ]
    • parameters object

      A list of parameters for a strategy

    • property name* string
    • ]
    • variants object[]

      A list of variants for the feature environment

    • Array [
    • name string required

      The variants name. Is unique for this feature toggle

    • weight number required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is a number between 0 and 1000. See the section on variant weights for more information

    • weightType string

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000

    • stickiness string

      Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • overrides object[]

      Overrides assigning specific variants to specific users. The weighting system automatically assigns users to specific groups for you, but any overrides in this list will take precedence.

    • Array [
    • contextName string required

      The name of the context field used to determine overrides

    • values string[] required

      Which values that should be overriden

    • ]
    • ]
    • lastSeenAt date-time nullable

      The date when metrics where last collected for the feature environment

    • hasStrategies boolean

      Whether the feature has any strategies defined.

    • hasEnabledStrategies boolean

      Whether the feature has any enabled strategies defined.

    • ]
    • variants object[]deprecated

      The list of feature variants

    • Array [
    • name string required

      The variants name. Is unique for this feature toggle

    • weight number required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is a number between 0 and 1000. See the section on variant weights for more information

    • weightType string

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000

    • stickiness string

      Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • overrides object[]

      Overrides assigning specific variants to specific users. The weighting system automatically assigns users to specific groups for you, but any overrides in this list will take precedence.

    • Array [
    • contextName string required

      The name of the context field used to determine overrides

    • values string[] required

      Which values that should be overriden

    • ]
    • ]
    • strategies object[] deprecated

      This is a legacy field that will be deprecated

    • tags object[]nullable

      The list of feature tags

    • Array [
    • value string required

      Possible values: >= 2 characters and <= 50 characters

      The value of the tag

    • type string required

      Possible values: >= 2 characters and <= 50 characters

      Default value: simple

      The type of the tag

    • ]
    • children string[]

      The list of child feature names. This is an experimental field and may change.

    • dependencies object[]

      The list of parent dependencies. This is an experimental field and may change.

    • Array [
    • feature string required

      The name of the parent feature

    • enabled boolean

      Whether the parent feature is enabled or not

    • variants string[]

      The list of variants the parent feature should resolve to. Only valid when feature is enabled.

    • ]
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-features.html b/reference/api/unleash/get-features.html index 6d8aa6f77f..58bc6cca88 100644 --- a/reference/api/unleash/get-features.html +++ b/reference/api/unleash/get-features.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Get all features in a project

    GET /api/admin/projects/:projectId/features

    A list of all features for the specified project.

    Request​

    Path Parameters

    • projectId string required
    Responses

    featuresSchema

    Schema
    • version integer required

      The version of the feature's schema

    • features object[]required

      A list of features

    • Array [
    • name string required

      Unique feature name

    • type string

      Type of the toggle e.g. experiment, kill-switch, release, operational, permission

    • description string nullable

      Detailed description of the feature

    • archived boolean

      true if the feature is archived

    • project string

      Name of the project the feature belongs to

    • enabled boolean

      true if the feature is enabled, otherwise false.

    • stale boolean

      true if the feature is stale based on the age and feature type, otherwise false.

    • favorite boolean

      true if the feature was favorited, otherwise false.

    • impressionData boolean

      true if the impression data collection is enabled for the feature, otherwise false.

    • createdAt date-time nullable

      The date the feature was created

    • archivedAt date-time nullable

      The date the feature was archived

    • lastSeenAt date-time nullable deprecated

      The date when metrics where last collected for the feature. This field is deprecated, use the one in featureEnvironmentSchema

    • environments object[]

      The list of environments where the feature can be used

    • Array [
    • name string required

      The name of the environment

    • featureName string

      The name of the feature

    • environment string

      The name of the environment

    • type string

      The type of the environment

    • enabled boolean required

      true if the feature is enabled for the environment, otherwise false.

    • sortOrder number

      The sort order of the feature environment in the feature environments list

    • variantCount number

      The number of defined variants

    • strategies object[]

      A list of activation strategies for the feature environment

    • Array [
    • id string

      A uuid for the feature strategy

    • name string required

      The name or type of strategy

    • title string nullable

      A descriptive title for the strategy

    • disabled boolean nullable

      A toggle to disable the strategy. defaults to false. Disabled strategies are not evaluated or returned to the SDKs

    • featureName string

      The name or feature the strategy is attached to

    • sortOrder number

      The order of the strategy in the list

    • segments number[]

      A list of segment ids attached to the strategy

    • constraints object[]

      A list of the constraints attached to the strategy. See https://docs.getunleash.io/reference/strategy-constraints

    • Array [
    • contextName string required

      The name of the context field that this constraint should apply to.

    • operator string required

      Possible values: [NOT_IN, IN, STR_ENDS_WITH, STR_STARTS_WITH, STR_CONTAINS, NUM_EQ, NUM_GT, NUM_GTE, NUM_LT, NUM_LTE, DATE_AFTER, DATE_BEFORE, SEMVER_EQ, SEMVER_GT, SEMVER_LT]

      The operator to use when evaluating this constraint. For more information about the various operators, refer to the strategy constraint operator documentation.

    • caseInsensitive boolean

      Default value: false

      Whether the operator should be case sensitive or not. Defaults to false (being case sensitive).

    • inverted boolean

      Default value: false

      Whether the result should be negated or not. If true, will turn a true result into a false result and vice versa.

    • values string[]

      The context values that should be used for constraint evaluation. Use this property instead of value for properties that accept multiple values.

    • value string

      The context value that should be used for constraint evaluation. Use this property instead of values for properties that only accept single values.

    • ]
    • variants object[]

      Strategy level variants

    • Array [
    • name string required

      The variant name. Must be unique for this feature toggle

    • weight integer required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is an integer between 0 and 1000. See the section on variant weights for more information

    • weightType string required

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000. Refer to the variant weight documentation.

    • stickiness string required

      The stickiness to use for distribution of this variant. Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • ]
    • parameters object

      A list of parameters for a strategy

    • property name* string
    • ]
    • variants object[]

      A list of variants for the feature environment

    • Array [
    • name string required

      The variants name. Is unique for this feature toggle

    • weight number required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is a number between 0 and 1000. See the section on variant weights for more information

    • weightType string

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000

    • stickiness string

      Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • overrides object[]

      Overrides assigning specific variants to specific users. The weighting system automatically assigns users to specific groups for you, but any overrides in this list will take precedence.

    • Array [
    • contextName string required

      The name of the context field used to determine overrides

    • values string[] required

      Which values that should be overriden

    • ]
    • ]
    • lastSeenAt date-time nullable

      The date when metrics where last collected for the feature environment

    • hasStrategies boolean

      Whether the feature has any strategies defined.

    • hasEnabledStrategies boolean

      Whether the feature has any enabled strategies defined.

    • ]
    • variants object[]deprecated

      The list of feature variants

    • Array [
    • name string required

      The variants name. Is unique for this feature toggle

    • weight number required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is a number between 0 and 1000. See the section on variant weights for more information

    • weightType string

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000

    • stickiness string

      Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • overrides object[]

      Overrides assigning specific variants to specific users. The weighting system automatically assigns users to specific groups for you, but any overrides in this list will take precedence.

    • Array [
    • contextName string required

      The name of the context field used to determine overrides

    • values string[] required

      Which values that should be overriden

    • ]
    • ]
    • strategies object[] deprecated

      This is a legacy field that will be deprecated

    • tags object[]nullable

      The list of feature tags

    • Array [
    • value string required

      Possible values: >= 2 characters and <= 50 characters

      The value of the tag

    • type string required

      Possible values: >= 2 characters and <= 50 characters

      Default value: simple

      The type of the tag

    • ]
    • children string[]

      The list of child feature names. This is an experimental field and may change.

    • dependencies object[]

      The list of parent dependencies. This is an experimental field and may change.

    • Array [
    • feature string required

      The name of the parent feature

    • enabled boolean

      Whether the parent feature is enabled or not

    • variants string[]

      The list of variants the parent feature should resolve to. Only valid when feature is enabled.

    • ]
    • ]
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-feedback.html b/reference/api/unleash/get-feedback.html index 615dbd4477..4b345d0b33 100644 --- a/reference/api/unleash/get-feedback.html +++ b/reference/api/unleash/get-feedback.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Get all feedback events.

    GET /api/admin/feedback

    Get all feedback events.

    Request​

    Responses

    feedbackListSchema

    Schema
    • Array [
    • id number required

      The unique identifier of the feedback.

    • createdAt date-time required

      The date and time when the feedback was provided.

    • category string required

      The category of the feedback.

    • userType string nullable required

      The type of user providing the feedback.

    • difficultyScore number nullable required

      A score indicating the difficulty experienced by the user.

    • positive string nullable required

      This field is for users to mention what they liked.

    • areasForImprovement string nullable required

      Details aspects of the service or product that could benefit from enhancements or modifications. Aids in pinpointing areas needing attention for improvement.

    • ]
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-frontend-features.html b/reference/api/unleash/get-frontend-features.html index f930b20ca7..98c368a200 100644 --- a/reference/api/unleash/get-frontend-features.html +++ b/reference/api/unleash/get-frontend-features.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Retrieve enabled feature toggles for the provided context.

    GET /api/frontend

    This endpoint returns the list of feature toggles that the proxy evaluates to enabled for the given context. Context values are provided as query parameters. If the Frontend API is disabled 404 is returned.

    Request​

    Responses

    proxyFeaturesSchema

    Schema
    • toggles object[]required

      The actual features returned to the Frontend SDK

    • Array [
    • name string required

      Unique feature name.

    • enabled boolean required

      Always set to true.

    • impressionData boolean required

      true if the impression data collection is enabled for the feature, otherwise false.

    • variant object

      Variant details

    • name string required

      The variants name. Is unique for this feature toggle

    • enabled boolean required

      Whether the variant is enabled or not.

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string]

      The format of the payload.

    • value string required

      The payload value stringified.

    • ]
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-google-settings.html b/reference/api/unleash/get-google-settings.html index a2f4c87604..f0555eda1d 100644 --- a/reference/api/unleash/get-google-settings.html +++ b/reference/api/unleash/get-google-settings.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Get Google auth settings

    GET /api/admin/auth/google/settings
    deprecated

    This endpoint has been deprecated and may be removed in future versions of the API.

    Returns the current settings for Google Authentication (deprecated, please use OpenID instead)

    Request​

    Responses

    googleSettingsSchema

    Schema
    • enabled boolean

      Is google OIDC enabled

    • clientId string required

      The google client id, used to authenticate against google

    • clientSecret string required

      The client secret used to authenticate the OAuth session used to log the user in

    • unleashHostname string required

      Name of the host allowed to access the Google authentication flow

    • autoCreate boolean

      Should Unleash create users based on the emails coming back in the authentication reply from Google

    • emailDomains string

      A comma separated list of email domains that Unleash will auto create user accounts for.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-group.html b/reference/api/unleash/get-group.html index 941d327796..4dbedba86c 100644 --- a/reference/api/unleash/get-group.html +++ b/reference/api/unleash/get-group.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Get a single group

    GET /api/admin/groups/:groupId

    Get a single user group by group id

    Request​

    Path Parameters

    • groupId string required
    Responses

    groupSchema

    Schema
    • id integer

      The group id

    • name string required

      The name of the group

    • description string nullable

      A custom description of the group

    • mappingsSSO string[]

      A list of SSO groups that should map to this Unleash group

    • rootRole number nullable

      A role id that is used as the root role for all users in this group. This can be either the id of the Viewer, Editor or Admin role.

    • createdBy string nullable

      A user who created this group

    • createdAt date-time nullable

      When was this group created

    • users object[]

      A list of users belonging to this group

    • Array [
    • joinedAt date-time

      The date when the user joined the group

    • createdBy string nullable

      The username of the user who added this user to this group

    • user objectrequired

      An Unleash user

    • id integer required

      The user id

    • isAPI boolean deprecated

      (Deprecated): Used internally to know which operations the user should be allowed to perform

    • name string nullable

      Name of the user

    • email string

      Email of the user

    • username string nullable

      A unique username for the user

    • imageUrl string

      URL used for the userprofile image

    • inviteLink string

      If the user is actively inviting other users, this is the link that can be shared with other users

    • loginAttempts integer

      How many unsuccessful attempts at logging in has the user made

    • emailSent boolean

      Is the welcome email sent to the user or not

    • rootRole integer

      Which root role this user is assigned

    • seenAt date-time nullable

      The last time this user logged in

    • createdAt date-time

      The user was created at this time

    • accountType string

      A user is either an actual User or a Service Account

    • permissions string[]

      Deprecated

    • ]
    • projects string[]

      A list of projects where this group is used

    • userCount integer

      The number of users that belong to this group

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-groups.html b/reference/api/unleash/get-groups.html index d22633d8f5..1e4aae601a 100644 --- a/reference/api/unleash/get-groups.html +++ b/reference/api/unleash/get-groups.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Get a list of groups

    GET /api/admin/groups

    Get a list of user groups for Role-Based Access Control

    Request​

    Responses

    groupsSchema

    Schema
    • groups object[]

      A list of groups

    • Array [
    • id integer

      The group id

    • name string required

      The name of the group

    • description string nullable

      A custom description of the group

    • mappingsSSO string[]

      A list of SSO groups that should map to this Unleash group

    • rootRole number nullable

      A role id that is used as the root role for all users in this group. This can be either the id of the Viewer, Editor or Admin role.

    • createdBy string nullable

      A user who created this group

    • createdAt date-time nullable

      When was this group created

    • users object[]

      A list of users belonging to this group

    • Array [
    • joinedAt date-time

      The date when the user joined the group

    • createdBy string nullable

      The username of the user who added this user to this group

    • user objectrequired

      An Unleash user

    • id integer required

      The user id

    • isAPI boolean deprecated

      (Deprecated): Used internally to know which operations the user should be allowed to perform

    • name string nullable

      Name of the user

    • email string

      Email of the user

    • username string nullable

      A unique username for the user

    • imageUrl string

      URL used for the userprofile image

    • inviteLink string

      If the user is actively inviting other users, this is the link that can be shared with other users

    • loginAttempts integer

      How many unsuccessful attempts at logging in has the user made

    • emailSent boolean

      Is the welcome email sent to the user or not

    • rootRole integer

      Which root role this user is assigned

    • seenAt date-time nullable

      The last time this user logged in

    • createdAt date-time

      The user was created at this time

    • accountType string

      A user is either an actual User or a Service Account

    • permissions string[]

      Deprecated

    • ]
    • projects string[]

      A list of projects where this group is used

    • userCount integer

      The number of users that belong to this group

    • ]
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-health.html b/reference/api/unleash/get-health.html index 3145f80ff8..0c20708d55 100644 --- a/reference/api/unleash/get-health.html +++ b/reference/api/unleash/get-health.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Get instance operational status

    GET /health

    This operation returns information about whether this Unleash instance is healthy and ready to serve requests or not. Typically used by your deployment orchestrator (e.g. Kubernetes, Docker Swarm, Mesos, et al.).

    Request​

    Responses

    healthCheckSchema

    Schema
    • health string required

      Possible values: [GOOD, BAD]

      The state this Unleash instance is in. GOOD if everything is ok, BAD if the instance should be restarted

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-instance-admin-stats-csv.html b/reference/api/unleash/get-instance-admin-stats-csv.html index b8f1e44ea8..e8a95db3e3 100644 --- a/reference/api/unleash/get-instance-admin-stats-csv.html +++ b/reference/api/unleash/get-instance-admin-stats-csv.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Instance usage statistics

    GET /api/admin/instance-admin/statistics/csv

    Provides statistics about various features of Unleash to allow for reporting of usage for self-hosted customers. The response contains data such as the number of users, groups, features, strategies, versions, etc.

    Request​

    Responses

    instanceAdminStatsSchemaCsv

    Schema
    • string
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-instance-admin-stats.html b/reference/api/unleash/get-instance-admin-stats.html index 7bfafd409b..b498f1a58f 100644 --- a/reference/api/unleash/get-instance-admin-stats.html +++ b/reference/api/unleash/get-instance-admin-stats.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Instance usage statistics

    GET /api/admin/instance-admin/statistics
    deprecated

    This endpoint has been deprecated and may be removed in future versions of the API.

    Provides statistics about various features of Unleash to allow for reporting of usage for self-hosted customers. The response contains data such as the number of users, groups, features, strategies, versions, etc.

    Request​

    Responses

    instanceAdminStatsSchema

    Schema
    • instanceId string required

      A unique identifier for this instance. Generated by the database migration scripts at first run. Typically a UUID.

    • timestamp date-time nullable

      When these statistics were produced

    • versionOSS string

      The version of Unleash OSS that is bundled in this instance

    • versionEnterprise string

      The version of Unleash Enterprise that is bundled in this instance

    • users number

      The number of users this instance has

    • activeUsers object

      The number of active users in the last 7, 30 and 90 days

    • last7 number

      The number of active users in the last 7 days

    • last30 number

      The number of active users in the last 30 days

    • last60 number

      The number of active users in the last 60 days

    • last90 number

      The number of active users in the last 90 days

    • productionChanges object

      The number of changes to the production environment in the last 30, 60 and 90 days

    • last30 number

      The number of changes in production in the last 30 days

    • last60 number

      The number of changes in production in the last 60 days

    • last90 number

      The number of changes in production in the last 90 days

    • featureToggles number

      The number of feature-toggles this instance has

    • projects number

      The number of projects defined in this instance.

    • contextFields number

      The number of context fields defined in this instance.

    • roles number

      The number of roles defined in this instance

    • groups number

      The number of groups defined in this instance

    • environments number

      The number of environments defined in this instance

    • segments number

      The number of segments defined in this instance

    • strategies number

      The number of strategies defined in this instance

    • SAMLenabled boolean

      Whether or not SAML authentication is enabled for this instance

    • OIDCenabled boolean

      Whether or not OIDC authentication is enabled for this instance

    • clientApps object[]

      A count of connected applications in the last week, last month and all time since last restart

    • Array [
    • range string

      Possible values: [allTime, 30d, 7d]

      A description of a time range

    • count number

      The number of client applications that have been observed in this period

    • ]
    • featureExports number

      The number of export operations on this instance

    • featureImports number

      The number of import operations on this instance

    • sum string

      A SHA-256 checksum of the instance statistics to be used to verify that the data in this object has not been tampered with

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-login-history.html b/reference/api/unleash/get-login-history.html index 3d9bd65e6d..702ea9c2cd 100644 --- a/reference/api/unleash/get-login-history.html +++ b/reference/api/unleash/get-login-history.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Get all login events.

    GET /api/admin/logins

    Returns all login events in the Unleash system. You can optionally get them in CSV format by specifying the Accept header as text/csv.

    Request​

    Responses

    loginHistorySchema

    Schema
    • events object[]required

      A list of login events

    • Array [
    • id integer required

      Possible values: >= 1

      The event's ID. Event IDs are incrementing integers. In other words, a more recent event will always have a higher ID than an older event.

    • username string

      The username of the user that attempted to log in. Will return "Incorrectly configured provider" when attempting to log in using a misconfigured provider.

    • auth_type string

      The authentication type used to log in.

    • created_at date-time

      The date and time of when the login was attempted.

    • successful boolean

      Whether the login was successful or not.

    • ip string nullable

      The IP address of the client that attempted to log in.

    • failure_reason string nullable

      The reason for the login failure. This property is only present if the login was unsuccessful.

    • ]
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-maintenance.html b/reference/api/unleash/get-maintenance.html index 76f48a3926..cee1ae3460 100644 --- a/reference/api/unleash/get-maintenance.html +++ b/reference/api/unleash/get-maintenance.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Get maintenance mode status

    GET /api/admin/maintenance

    Tells you whether maintenance mode is enabled or disabled

    Request​

    Responses

    maintenanceSchema

    Schema
    • enabled boolean required

      Whether maintenance mode is enabled or not.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-me.html b/reference/api/unleash/get-me.html index 819aa5cf5e..2c37339d22 100644 --- a/reference/api/unleash/get-me.html +++ b/reference/api/unleash/get-me.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Get your own user details

    GET /api/admin/user

    Detailed information about the current user, user permissions and user feedback

    Request​

    Responses

    meSchema

    Schema
    • user objectrequired

      An Unleash user

    • id integer required

      The user id

    • isAPI boolean deprecated

      (Deprecated): Used internally to know which operations the user should be allowed to perform

    • name string nullable

      Name of the user

    • email string

      Email of the user

    • username string nullable

      A unique username for the user

    • imageUrl string

      URL used for the userprofile image

    • inviteLink string

      If the user is actively inviting other users, this is the link that can be shared with other users

    • loginAttempts integer

      How many unsuccessful attempts at logging in has the user made

    • emailSent boolean

      Is the welcome email sent to the user or not

    • rootRole integer

      Which root role this user is assigned

    • seenAt date-time nullable

      The last time this user logged in

    • createdAt date-time

      The user was created at this time

    • accountType string

      A user is either an actual User or a Service Account

    • permissions string[]

      Deprecated

    • permissions object[]required

      User permissions for projects and environments

    • Array [
    • permission string required

      Project or environment permission name

    • project string

      The project this permission applies to

    • environment string

      The environment this permission applies to

    • ]
    • feedback object[]required

      User feedback information

    • Array [
    • userId integer

      The ID of the user that gave the feedback.

    • neverShow boolean

      true if the user has asked never to see this feedback questionnaire again.

    • given date-time nullable

      When this feedback was given

    • feedbackId string

      The name of the feedback session

    • ]
    • splash objectrequired

      Splash screen configuration

    • property name* boolean
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-notifications.html b/reference/api/unleash/get-notifications.html index d2dabfc31a..12517bc26a 100644 --- a/reference/api/unleash/get-notifications.html +++ b/reference/api/unleash/get-notifications.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Retrieves a list of notifications

    GET /api/admin/notifications

    A user may get relevant notifications from the projects they are a member of

    Request​

    Responses

    notificationsSchema

    Schema
    • Array [
    • id number required

      The id of this notification

    • message string required

      The actual notification message

    • link string required

      The link to change request or feature toggle the notification refers to

    • notificationType required

      Possible values: [change-request, toggle]

      The type of the notification used e.g. for the graphical hints

    • createdBy objectrequired
    • username string nullable

      The name of the user who triggered the notification

    • imageUrl string nullable

      The avatar url of the user who triggered the notification

    • createdAt date-time required

      The date and time when the notification was created

    • readAt date-time nullable required

      The date and time when the notification was read or marked as read, otherwise null

    • ]
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-oidc-settings.html b/reference/api/unleash/get-oidc-settings.html index 413d6881e8..c4fd23ddeb 100644 --- a/reference/api/unleash/get-oidc-settings.html +++ b/reference/api/unleash/get-oidc-settings.html @@ -20,7 +20,7 @@ - + @@ -29,7 +29,7 @@
    Skip to main content

    Get OIDC auth settings

    GET /api/admin/auth/oidc/settings

    Returns the current settings for OIDC Authentication

    Request​

    Responses

    oidcSettingsSchema

    Schema
    • enabled boolean

      true if OpenID connect is turned on for this instance, otherwise false

    • discoverUrl string
    • clientId string required

      The OIDC client ID of this application.

    • secret string required

      Shared secret from OpenID server. Used to authenticate login requests

    • autoCreate boolean

      Auto create users based on email addresses from login tokens

    • enableSingleSignOut boolean

      Support Single sign out when user clicks logout in Unleash. If true user is signed out of all OpenID Connect sessions against the clientId they may have active

    • defaultRootRole string

      Possible values: [Viewer, Editor, Admin]

      Default role granted to users auto-created from email. Only relevant if autoCreate is true

    • emailDomains string

      Comma separated list of email domains that are automatically approved for an account in the server. Only relevant if autoCreate is true

    • acrValues string

      Authentication Context Class Reference, used to request extra values in the acr claim returned from the server. If multiple values are required, they should be space separated. Consult the OIDC reference for more information

    • idTokenSigningAlgorithm string

      Possible values: [RS256, RS384, RS512]

      The signing algorithm used to sign our token. Refer to the JWT signatures documentation for more information.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-open-change-requests-for-user.html b/reference/api/unleash/get-open-change-requests-for-user.html index 4a2b0d593c..6cd92a65ff 100644 --- a/reference/api/unleash/get-open-change-requests-for-user.html +++ b/reference/api/unleash/get-open-change-requests-for-user.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Retrieves pending change requests in configured environments

    GET /api/admin/projects/:projectId/change-requests/open

    This endpoint will retrieve the pending change requests in the configured environments for the project, for the current user performing the request.

    Request​

    Path Parameters

    • projectId string required
    Responses

    changeRequestsSchema

    Schema
    • Array [
      • oneOf
    • id number required

      This change requests's ID.

    • title string

      A title describing the change request's content.

    • environment string required

      The environment in which the changes should be applied.

    • minApprovals number required

      The minimum number of approvals required before this change request can be applied.

    • project string required

      The project this change request belongs to.

    • features object[]required

      The list of features and their changes that relate to this change request.

    • Array [
    • name string required

      The name of the feature

    • conflict string

      A string describing the conflicts related to this change. Only present if there are any concflicts on the feature level.

    • changes object[]required

      List of changes inside change request. This list may be empty when listing all change requests for a project.

    • Array [
    • id number required

      The ID of this change.

    • action string required

      The kind of action that the change contains information about.

    • conflict string

      A description of the conflict caused by this change. Only present if there are any conflicts.

    • payload objectrequired

      The data required to perform this action.

      oneOf
    • string
    • createdBy object

      The user who created this change.

    • username string nullable

      The user's username.

    • imageUrl uri nullable

      The URL where the user's image can be found.

    • createdAt date-time

      When this change was suggested

    • ]
    • defaultChange object

      A description of a default change that will be applied with the change request to prevent invalid states.

      Default changes are changes that are applied in addition to explicit user-specified changes when a change request is applied. Any default changes are applied in the background and are not a real part of the change request.

    • action string required

      The kind of action this is.

    • payload object required

      The necessary data to perform this change.

    • ]
    • segments object[]required

      The list of segments and their changes that relate to this change request.

    • Array [
    • id number required

      The ID of this change.

    • action string required

      The kind of action that the change contains information about.

    • conflict string

      A description of the conflict caused by this change. Only present if there are any conflicts.

    • payload objectrequired

      The data required to perform this action.

      oneOf
    • string
    • createdBy object

      The user who created this change.

    • username string nullable

      The user's username.

    • imageUrl uri nullable

      The URL where the user's image can be found.

    • createdAt date-time

      When this change was suggested

    • name string required

      The current name of the segment

    • ]
    • approvals object[]

      A list of approvals that this change request has received.

    • Array [
    • createdBy objectrequired

      Information about the user who gave this approval.

    • id number

      The ID of the user who gave this approval.

    • username string

      The approving user's username.

    • imageUrl uri

      The URL where the user's image can be found.

    • createdAt date-time required

      When the approval was given.

    • ]
    • rejections object[]

      A list of rejections that this change request has received.

    • Array [
    • createdBy objectrequired

      Information about the user who gave this approval.

    • id number

      The ID of the user who gave this approval.

    • username string

      The approving user's username.

    • imageUrl uri

      The URL where the user's image can be found.

    • createdAt date-time required

      When the approval was given.

    • ]
    • comments object[]

      All comments that have been made on this change request.

    • Array [
    • id number

      The comment's ID. Unique per change request.

    • text string required

      The content of the comment.

    • createdBy objectrequired

      Information about the user who posted the comment

    • username string nullable

      The user's username.

    • imageUrl uri nullable

      The URL where the user's image can be found.

    • createdAt date-time required

      When the comment was made.

    • ]
    • createdBy objectrequired

      The user who created this change request.

    • username string nullable
    • imageUrl uri nullable

      The URL of the user's profile image.

    • createdAt date-time required

      When this change request was created.

    • state string required

      Possible values: [Draft, In review, Approved, Applied, Cancelled, Rejected]

      The current state of the change request.

    • ]
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-pats.html b/reference/api/unleash/get-pats.html index 993afc0ad0..a187eb6272 100644 --- a/reference/api/unleash/get-pats.html +++ b/reference/api/unleash/get-pats.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Get all Personal Access Tokens for the current user.

    GET /api/admin/user/tokens

    Returns all of the Personal Access Tokens belonging to the current user.

    Request​

    Responses

    patsSchema

    Schema
    • pats object[]

      A collection of Personal Access Tokens

    • Array [
    • id integer

      Possible values: >= 1

      The unique identification number for this Personal Access Token. (This property is set by Unleash when the token is created and cannot be set manually: if you provide a value when creating a PAT, Unleash will ignore it.)

    • secret string

      The token used for authentication. (This property is set by Unleash when the token is created and cannot be set manually: if you provide a value when creating a PAT, Unleash will ignore it.)

    • expiresAt date-time

      The token's expiration date.

    • createdAt date-time

      When the token was created. (This property is set by Unleash when the token is created and cannot be set manually: if you provide a value when creating a PAT, Unleash will ignore it.)

    • seenAt date-time nullable

      When the token was last seen/used to authenticate with. null if it has not been used yet. (This property is set by Unleash when the token is created and cannot be set manually: if you provide a value when creating a PAT, Unleash will ignore it.)

    • ]
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-pending-change-requests-for-feature.html b/reference/api/unleash/get-pending-change-requests-for-feature.html index 8de52271ae..338a6248b7 100644 --- a/reference/api/unleash/get-pending-change-requests-for-feature.html +++ b/reference/api/unleash/get-pending-change-requests-for-feature.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Retrieves all pending change requests referencing a feature in the project

    GET /api/admin/projects/:projectId/change-requests/pending/:featureName

    This endpoint will retrieve all pending change requests (change requests with a status of Draft | In review | Approved) referencing the given feature toggle name.

    Request​

    Path Parameters

    • projectId string required
    • featureName string required
    Responses

    changeRequestsSchema

    Schema
    • Array [
      • oneOf
    • id number required

      This change requests's ID.

    • title string

      A title describing the change request's content.

    • environment string required

      The environment in which the changes should be applied.

    • minApprovals number required

      The minimum number of approvals required before this change request can be applied.

    • project string required

      The project this change request belongs to.

    • features object[]required

      The list of features and their changes that relate to this change request.

    • Array [
    • name string required

      The name of the feature

    • conflict string

      A string describing the conflicts related to this change. Only present if there are any concflicts on the feature level.

    • changes object[]required

      List of changes inside change request. This list may be empty when listing all change requests for a project.

    • Array [
    • id number required

      The ID of this change.

    • action string required

      The kind of action that the change contains information about.

    • conflict string

      A description of the conflict caused by this change. Only present if there are any conflicts.

    • payload objectrequired

      The data required to perform this action.

      oneOf
    • string
    • createdBy object

      The user who created this change.

    • username string nullable

      The user's username.

    • imageUrl uri nullable

      The URL where the user's image can be found.

    • createdAt date-time

      When this change was suggested

    • ]
    • defaultChange object

      A description of a default change that will be applied with the change request to prevent invalid states.

      Default changes are changes that are applied in addition to explicit user-specified changes when a change request is applied. Any default changes are applied in the background and are not a real part of the change request.

    • action string required

      The kind of action this is.

    • payload object required

      The necessary data to perform this change.

    • ]
    • segments object[]required

      The list of segments and their changes that relate to this change request.

    • Array [
    • id number required

      The ID of this change.

    • action string required

      The kind of action that the change contains information about.

    • conflict string

      A description of the conflict caused by this change. Only present if there are any conflicts.

    • payload objectrequired

      The data required to perform this action.

      oneOf
    • string
    • createdBy object

      The user who created this change.

    • username string nullable

      The user's username.

    • imageUrl uri nullable

      The URL where the user's image can be found.

    • createdAt date-time

      When this change was suggested

    • name string required

      The current name of the segment

    • ]
    • approvals object[]

      A list of approvals that this change request has received.

    • Array [
    • createdBy objectrequired

      Information about the user who gave this approval.

    • id number

      The ID of the user who gave this approval.

    • username string

      The approving user's username.

    • imageUrl uri

      The URL where the user's image can be found.

    • createdAt date-time required

      When the approval was given.

    • ]
    • rejections object[]

      A list of rejections that this change request has received.

    • Array [
    • createdBy objectrequired

      Information about the user who gave this approval.

    • id number

      The ID of the user who gave this approval.

    • username string

      The approving user's username.

    • imageUrl uri

      The URL where the user's image can be found.

    • createdAt date-time required

      When the approval was given.

    • ]
    • comments object[]

      All comments that have been made on this change request.

    • Array [
    • id number

      The comment's ID. Unique per change request.

    • text string required

      The content of the comment.

    • createdBy objectrequired

      Information about the user who posted the comment

    • username string nullable

      The user's username.

    • imageUrl uri nullable

      The URL where the user's image can be found.

    • createdAt date-time required

      When the comment was made.

    • ]
    • createdBy objectrequired

      The user who created this change request.

    • username string nullable
    • imageUrl uri nullable

      The URL of the user's profile image.

    • createdAt date-time required

      When this change request was created.

    • state string required

      Possible values: [Draft, In review, Approved, Applied, Cancelled, Rejected]

      The current state of the change request.

    • ]
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-pending-change-requests-for-user.html b/reference/api/unleash/get-pending-change-requests-for-user.html index 68f373fded..e0815c18d4 100644 --- a/reference/api/unleash/get-pending-change-requests-for-user.html +++ b/reference/api/unleash/get-pending-change-requests-for-user.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Retrieves pending change requests in configured environments

    GET /api/admin/projects/:projectId/change-requests/pending

    This endpoint will retrieve the pending change requests in the configured environments for the project, for the current user performing the request.

    Request​

    Path Parameters

    • projectId string required
    Responses

    changeRequestsSchema

    Schema
    • Array [
      • oneOf
    • id number required

      This change requests's ID.

    • title string

      A title describing the change request's content.

    • environment string required

      The environment in which the changes should be applied.

    • minApprovals number required

      The minimum number of approvals required before this change request can be applied.

    • project string required

      The project this change request belongs to.

    • features object[]required

      The list of features and their changes that relate to this change request.

    • Array [
    • name string required

      The name of the feature

    • conflict string

      A string describing the conflicts related to this change. Only present if there are any concflicts on the feature level.

    • changes object[]required

      List of changes inside change request. This list may be empty when listing all change requests for a project.

    • Array [
    • id number required

      The ID of this change.

    • action string required

      The kind of action that the change contains information about.

    • conflict string

      A description of the conflict caused by this change. Only present if there are any conflicts.

    • payload objectrequired

      The data required to perform this action.

      oneOf
    • string
    • createdBy object

      The user who created this change.

    • username string nullable

      The user's username.

    • imageUrl uri nullable

      The URL where the user's image can be found.

    • createdAt date-time

      When this change was suggested

    • ]
    • defaultChange object

      A description of a default change that will be applied with the change request to prevent invalid states.

      Default changes are changes that are applied in addition to explicit user-specified changes when a change request is applied. Any default changes are applied in the background and are not a real part of the change request.

    • action string required

      The kind of action this is.

    • payload object required

      The necessary data to perform this change.

    • ]
    • segments object[]required

      The list of segments and their changes that relate to this change request.

    • Array [
    • id number required

      The ID of this change.

    • action string required

      The kind of action that the change contains information about.

    • conflict string

      A description of the conflict caused by this change. Only present if there are any conflicts.

    • payload objectrequired

      The data required to perform this action.

      oneOf
    • string
    • createdBy object

      The user who created this change.

    • username string nullable

      The user's username.

    • imageUrl uri nullable

      The URL where the user's image can be found.

    • createdAt date-time

      When this change was suggested

    • name string required

      The current name of the segment

    • ]
    • approvals object[]

      A list of approvals that this change request has received.

    • Array [
    • createdBy objectrequired

      Information about the user who gave this approval.

    • id number

      The ID of the user who gave this approval.

    • username string

      The approving user's username.

    • imageUrl uri

      The URL where the user's image can be found.

    • createdAt date-time required

      When the approval was given.

    • ]
    • rejections object[]

      A list of rejections that this change request has received.

    • Array [
    • createdBy objectrequired

      Information about the user who gave this approval.

    • id number

      The ID of the user who gave this approval.

    • username string

      The approving user's username.

    • imageUrl uri

      The URL where the user's image can be found.

    • createdAt date-time required

      When the approval was given.

    • ]
    • comments object[]

      All comments that have been made on this change request.

    • Array [
    • id number

      The comment's ID. Unique per change request.

    • text string required

      The content of the comment.

    • createdBy objectrequired

      Information about the user who posted the comment

    • username string nullable

      The user's username.

    • imageUrl uri nullable

      The URL where the user's image can be found.

    • createdAt date-time required

      When the comment was made.

    • ]
    • createdBy objectrequired

      The user who created this change request.

    • username string nullable
    • imageUrl uri nullable

      The URL of the user's profile image.

    • createdAt date-time required

      When this change request was created.

    • state string required

      Possible values: [Draft, In review, Approved, Applied, Cancelled, Rejected]

      The current state of the change request.

    • ]
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-permissions.html b/reference/api/unleash/get-permissions.html index 2001dab600..8e99e4bf60 100644 --- a/reference/api/unleash/get-permissions.html +++ b/reference/api/unleash/get-permissions.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Gets available permissions

    GET /api/admin/permissions

    Returns a list of available permissions

    Request​

    Responses

    adminPermissionsSchema

    Schema
    • permissions objectrequired

      Returns permissions available at all three levels (root|project|environment)

    • root object[]

      Permissions available at the root level, i.e. not connected to any specific project or environment

    • Array [
    • id integer required

      The identifier for this permission

    • name string required

      The name of this permission

    • displayName string required

      The name to display in listings of permissions

    • type string required

      What level this permission applies to. Either root, project or the name of the environment it applies to

    • environment string

      Which environment this permission applies to

    • ]
    • project object[]required

      Permissions available at the project level

    • Array [
    • id integer required

      The identifier for this permission

    • name string required

      The name of this permission

    • displayName string required

      The name to display in listings of permissions

    • type string required

      What level this permission applies to. Either root, project or the name of the environment it applies to

    • environment string

      Which environment this permission applies to

    • ]
    • environments object[]required

      A list of environments with available permissions per environment

    • Array [
    • name string required

      The name of the environment

    • permissions object[]required

      Permissions available for this environment

    • Array [
    • id integer required

      The identifier for this permission

    • name string required

      The name of this permission

    • displayName string required

      The name to display in listings of permissions

    • type string required

      What level this permission applies to. Either root, project or the name of the environment it applies to

    • environment string

      Which environment this permission applies to

    • ]
    • ]
    • version integer required

      Possible values: >= 1, [1, 2]

      The api version of this response. A natural increasing number. Only increases if format changes

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-playground.html b/reference/api/unleash/get-playground.html index d334286c79..d2d0fbc0f5 100644 --- a/reference/api/unleash/get-playground.html +++ b/reference/api/unleash/get-playground.html @@ -20,7 +20,7 @@ - + @@ -40,7 +40,7 @@ variant. If a feature is disabled or doesn't have any variants, you would get the disabled variant. Otherwise, you'll get one of thefeature's defined variants.

  • name string required

    The variant's name. If there is no variant or if the toggle is disabled, this will be disabled

  • enabled boolean required

    Whether the variant is enabled or not. If the feature is disabled or if it doesn't have variants, this property will be false

  • payload object

    An optional payload attached to the variant.

  • type string required

    The format of the payload.

  • value string required

    The payload value stringified.

  • variants object[]required

    The feature variants.

  • Array [
  • name string required

    The variants name. Is unique for this feature toggle

  • weight number required

    Possible values: <= 1000

    The weight is the likelihood of any one user getting this variant. It is a number between 0 and 1000. See the section on variant weights for more information

  • weightType string

    Possible values: [variable, fix]

    Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000

  • stickiness string

    Stickiness is how Unleash guarantees that the same user gets the same variant every time

  • payload object

    Extra data configured for this variant

  • type string required

    Possible values: [json, csv, string, number]

    The type of the value. Commonly used types are string, number, json and csv.

  • value string required

    The actual value of payload

  • overrides object[]

    Overrides assigning specific variants to specific users. The weighting system automatically assigns users to specific groups for you, but any overrides in this list will take precedence.

  • Array [
  • contextName string required

    The name of the context field used to determine overrides

  • values string[] required

    Which values that should be overriden

  • ]
  • ]
  • ]
    • Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-profile.html b/reference/api/unleash/get-profile.html index bda4013ab4..46593c281a 100644 --- a/reference/api/unleash/get-profile.html +++ b/reference/api/unleash/get-profile.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Get your own user profile

    GET /api/admin/user/profile

    Detailed information about the current user root role and project membership

    Request​

    Responses

    profileSchema

    Schema
    • rootRole objectrequired

      A role holds permissions to allow Unleash to decide what actions a role holder is allowed to perform

    • id integer required

      The role id

    • type string required

      A role can either be a global root role (applies to all projects) or a project role

    • name string required

      The name of the role

    • description string

      A more detailed description of the role and what use it's intended for

    • projects string[] required

      Which projects this user is a member of

    • features object[]required

      Deprecated, always returns empty array

    • Array [
    • name string required

      Unique feature name

    • type string

      Type of the toggle e.g. experiment, kill-switch, release, operational, permission

    • description string nullable

      Detailed description of the feature

    • archived boolean

      true if the feature is archived

    • project string

      Name of the project the feature belongs to

    • enabled boolean

      true if the feature is enabled, otherwise false.

    • stale boolean

      true if the feature is stale based on the age and feature type, otherwise false.

    • favorite boolean

      true if the feature was favorited, otherwise false.

    • impressionData boolean

      true if the impression data collection is enabled for the feature, otherwise false.

    • createdAt date-time nullable

      The date the feature was created

    • archivedAt date-time nullable

      The date the feature was archived

    • lastSeenAt date-time nullable deprecated

      The date when metrics where last collected for the feature. This field is deprecated, use the one in featureEnvironmentSchema

    • environments object[]

      The list of environments where the feature can be used

    • Array [
    • name string required

      The name of the environment

    • featureName string

      The name of the feature

    • environment string

      The name of the environment

    • type string

      The type of the environment

    • enabled boolean required

      true if the feature is enabled for the environment, otherwise false.

    • sortOrder number

      The sort order of the feature environment in the feature environments list

    • variantCount number

      The number of defined variants

    • strategies object[]

      A list of activation strategies for the feature environment

    • Array [
    • id string

      A uuid for the feature strategy

    • name string required

      The name or type of strategy

    • title string nullable

      A descriptive title for the strategy

    • disabled boolean nullable

      A toggle to disable the strategy. defaults to false. Disabled strategies are not evaluated or returned to the SDKs

    • featureName string

      The name or feature the strategy is attached to

    • sortOrder number

      The order of the strategy in the list

    • segments number[]

      A list of segment ids attached to the strategy

    • constraints object[]

      A list of the constraints attached to the strategy. See https://docs.getunleash.io/reference/strategy-constraints

    • Array [
    • contextName string required

      The name of the context field that this constraint should apply to.

    • operator string required

      Possible values: [NOT_IN, IN, STR_ENDS_WITH, STR_STARTS_WITH, STR_CONTAINS, NUM_EQ, NUM_GT, NUM_GTE, NUM_LT, NUM_LTE, DATE_AFTER, DATE_BEFORE, SEMVER_EQ, SEMVER_GT, SEMVER_LT]

      The operator to use when evaluating this constraint. For more information about the various operators, refer to the strategy constraint operator documentation.

    • caseInsensitive boolean

      Default value: false

      Whether the operator should be case sensitive or not. Defaults to false (being case sensitive).

    • inverted boolean

      Default value: false

      Whether the result should be negated or not. If true, will turn a true result into a false result and vice versa.

    • values string[]

      The context values that should be used for constraint evaluation. Use this property instead of value for properties that accept multiple values.

    • value string

      The context value that should be used for constraint evaluation. Use this property instead of values for properties that only accept single values.

    • ]
    • variants object[]

      Strategy level variants

    • Array [
    • name string required

      The variant name. Must be unique for this feature toggle

    • weight integer required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is an integer between 0 and 1000. See the section on variant weights for more information

    • weightType string required

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000. Refer to the variant weight documentation.

    • stickiness string required

      The stickiness to use for distribution of this variant. Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • ]
    • parameters object

      A list of parameters for a strategy

    • property name* string
    • ]
    • variants object[]

      A list of variants for the feature environment

    • Array [
    • name string required

      The variants name. Is unique for this feature toggle

    • weight number required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is a number between 0 and 1000. See the section on variant weights for more information

    • weightType string

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000

    • stickiness string

      Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • overrides object[]

      Overrides assigning specific variants to specific users. The weighting system automatically assigns users to specific groups for you, but any overrides in this list will take precedence.

    • Array [
    • contextName string required

      The name of the context field used to determine overrides

    • values string[] required

      Which values that should be overriden

    • ]
    • ]
    • lastSeenAt date-time nullable

      The date when metrics where last collected for the feature environment

    • hasStrategies boolean

      Whether the feature has any strategies defined.

    • hasEnabledStrategies boolean

      Whether the feature has any enabled strategies defined.

    • ]
    • variants object[]deprecated

      The list of feature variants

    • Array [
    • name string required

      The variants name. Is unique for this feature toggle

    • weight number required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is a number between 0 and 1000. See the section on variant weights for more information

    • weightType string

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000

    • stickiness string

      Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • overrides object[]

      Overrides assigning specific variants to specific users. The weighting system automatically assigns users to specific groups for you, but any overrides in this list will take precedence.

    • Array [
    • contextName string required

      The name of the context field used to determine overrides

    • values string[] required

      Which values that should be overriden

    • ]
    • ]
    • strategies object[] deprecated

      This is a legacy field that will be deprecated

    • tags object[]nullable

      The list of feature tags

    • Array [
    • value string required

      Possible values: >= 2 characters and <= 50 characters

      The value of the tag

    • type string required

      Possible values: >= 2 characters and <= 50 characters

      Default value: simple

      The type of the tag

    • ]
    • children string[]

      The list of child feature names. This is an experimental field and may change.

    • dependencies object[]

      The list of parent dependencies. This is an experimental field and may change.

    • Array [
    • feature string required

      The name of the parent feature

    • enabled boolean

      Whether the parent feature is enabled or not

    • variants string[]

      The list of variants the parent feature should resolve to. Only valid when feature is enabled.

    • ]
    • ]
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-project-access.html b/reference/api/unleash/get-project-access.html index 30bc6b5f5e..88029f4fef 100644 --- a/reference/api/unleash/get-project-access.html +++ b/reference/api/unleash/get-project-access.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Get users and groups in project

    GET /api/admin/projects/:projectId/access

    Get all groups, users and their roles, and available roles for the given project.

    Request​

    Path Parameters

    • projectId string required
    Responses

    projectAccessSchema

    Schema
    • groups object[]required

      A list of groups that have access to this project

    • Array [
    • name string

      The name of the group

    • id integer required

      The group's ID in the Unleash system

    • addedAt date-time

      When this group was added to the project

    • roleId integer

      The ID of the role this group has in the given project

    • roles integer[]

      A list of roles this user has in the given project

    • description string nullable

      A custom description of the group

    • mappingsSSO string[]

      A list of SSO groups that should map to this Unleash group

    • rootRole number nullable

      A role id that is used as the root role for all users in this group. This can be either the id of the Viewer, Editor or Admin role.

    • createdBy string nullable

      A user who created this group

    • createdAt date-time nullable

      When was this group created

    • users object[]

      A list of users belonging to this group

    • Array [
    • joinedAt date-time

      The date when the user joined the group

    • createdBy string nullable

      The username of the user who added this user to this group

    • user objectrequired

      An Unleash user

    • id integer required

      The user id

    • isAPI boolean deprecated

      (Deprecated): Used internally to know which operations the user should be allowed to perform

    • name string nullable

      Name of the user

    • email string

      Email of the user

    • username string nullable

      A unique username for the user

    • imageUrl string

      URL used for the userprofile image

    • inviteLink string

      If the user is actively inviting other users, this is the link that can be shared with other users

    • loginAttempts integer

      How many unsuccessful attempts at logging in has the user made

    • emailSent boolean

      Is the welcome email sent to the user or not

    • rootRole integer

      Which root role this user is assigned

    • seenAt date-time nullable

      The last time this user logged in

    • createdAt date-time

      The user was created at this time

    • accountType string

      A user is either an actual User or a Service Account

    • permissions string[]

      Deprecated

    • ]
    • ]
    • users object[]required

      A list of users and their roles within this project

    • Array [
    • isAPI boolean deprecated

      Whether this user is authenticated through Unleash tokens or logged in with a session

    • name string

      The name of the user

    • email string nullable

      The user's email address

    • id integer required

      The user's ID in the Unleash system

    • imageUrl uri nullable

      A URL pointing to the user's image.

    • addedAt date-time

      When this user was added to the project

    • roleId integer

      The ID of the role this user has in the given project

    • roles integer[]

      A list of roles this user has in the given project

    • ]
    • roles object[]required

      A list of roles that are available within this project.

    • Array [
    • id integer required

      The role id

    • type string required

      A role can either be a global root role (applies to all projects) or a project role

    • name string required

      The name of the role

    • description string

      A more detailed description of the role and what use it's intended for

    • ]
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-project-api-tokens.html b/reference/api/unleash/get-project-api-tokens.html index daf54b8d5f..b6069d0c3c 100644 --- a/reference/api/unleash/get-project-api-tokens.html +++ b/reference/api/unleash/get-project-api-tokens.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Get api tokens for project.

    GET /api/admin/projects/:projectId/api-tokens

    Returns the project API tokens that have been created for this project.

    Request​

    Path Parameters

    • projectId string required
    Responses

    apiTokensSchema

    Schema
    • tokens object[]required

      A list of Unleash API tokens.

    • Array [
    • secret string required

      The token used for authentication.

    • username string deprecated

      This property was deprecated in Unleash v5. Prefer the tokenName property instead.

    • tokenName string required

      A unique name for this particular token

    • type string required

      Possible values: [client, admin, frontend]

      The type of API token

    • environment string

      The environment the token has access to. * if it has access to all environments.

    • project string required

      The project this token belongs to.

    • projects string[] required

      The list of projects this token has access to. If the token has access to specific projects they will be listed here. If the token has access to all projects it will be represented as [*]

    • expiresAt date-time nullable

      The token's expiration date. NULL if the token doesn't have an expiration set.

    • createdAt date-time required

      When the token was created.

    • seenAt date-time nullable

      When the token was last seen/used to authenticate with. NULL if the token has not yet been used for authentication.

    • alias string nullable

      Alias is no longer in active use and will often be NULL. It's kept around as a way of allowing old proxy tokens created with the old metadata format to keep working.

    • ]
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-project-change-request-config.html b/reference/api/unleash/get-project-change-request-config.html index 0ba2d2451e..821c413c3b 100644 --- a/reference/api/unleash/get-project-change-request-config.html +++ b/reference/api/unleash/get-project-change-request-config.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Retrieves change request configuration for a project

    GET /api/admin/projects/:projectId/change-requests/config

    Given a projectId, this endpoint will retrieve change request configuration for the project

    Request​

    Path Parameters

    • projectId string required
    Responses

    changeRequestConfigSchema

    Schema
    • Array [
    • environment string required

      The environment that this configuration applies to.

    • type string required

      The type of the environment listed in environment.

    • changeRequestEnabled boolean required

      true if this environment has change requests enabled, otherwise false.

    • requiredApprovals number nullable required

      The number of approvals that are required for a change request to be fully approved and ready to be applied in this environment.

    • ]
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-project-dora.html b/reference/api/unleash/get-project-dora.html index c0747ac694..e842f6d627 100644 --- a/reference/api/unleash/get-project-dora.html +++ b/reference/api/unleash/get-project-dora.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Get an overview project dora metrics.

    GET /api/admin/projects/:projectId/dora

    This endpoint returns an overview of the specified dora metrics

    Request​

    Path Parameters

    • projectId string required
    Responses

    projectDoraMetricsSchema

    Schema
    • projectAverage number

      The average time it takes a feature toggle to be enabled in production. The measurement unit is days.

    • features object[]required

      An array of objects containing feature toggle name and timeToProduction values. The measurement unit of timeToProduction is days.

    • Array [
    • name string required

      The name of a feature toggle

    • timeToProduction number required

      The average number of days it takes a feature toggle to get into production

    • ]
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-project-environments.html b/reference/api/unleash/get-project-environments.html index 5415a1e44f..8460d89a52 100644 --- a/reference/api/unleash/get-project-environments.html +++ b/reference/api/unleash/get-project-environments.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Get the environments available to a project

    GET /api/admin/environments/project/:projectId

    Gets the environments that are available for this project. An environment is available for a project if enabled in the project configuration

    Request​

    Path Parameters

    • projectId string required
    Responses

    environmentsProjectSchema

    Schema
    • version integer required

      Version of the environments schema

    • environments object[]required

      List of environments

    • Array [
    • name string required

      The name of the environment

    • type string required
    • enabled boolean required

      true if the environment is enabled for the project, otherwise false

    • protected boolean required

      true if the environment is protected, otherwise false. A protected environment can not be deleted.

    • sortOrder integer required

      Priority of the environment in a list of environments, the lower the value, the higher up in the list the environment will appear

    • projectApiTokenCount integer

      The number of client and front-end API tokens that have access to this project

    • projectEnabledToggleCount integer

      The number of features enabled in this environment for this project

    • defaultStrategy object

      The strategy configuration to add when enabling a feature environment by default

    • name string required

      The name of the strategy type

    • title string nullable

      A descriptive title for the strategy

    • disabled boolean nullable

      A toggle to disable the strategy. defaults to false. Disabled strategies are not evaluated or returned to the SDKs

    • sortOrder number

      The order of the strategy in the list

    • constraints object[]

      A list of the constraints attached to the strategy. See https://docs.getunleash.io/reference/strategy-constraints

    • Array [
    • contextName string required

      The name of the context field that this constraint should apply to.

    • operator string required

      Possible values: [NOT_IN, IN, STR_ENDS_WITH, STR_STARTS_WITH, STR_CONTAINS, NUM_EQ, NUM_GT, NUM_GTE, NUM_LT, NUM_LTE, DATE_AFTER, DATE_BEFORE, SEMVER_EQ, SEMVER_GT, SEMVER_LT]

      The operator to use when evaluating this constraint. For more information about the various operators, refer to the strategy constraint operator documentation.

    • caseInsensitive boolean

      Default value: false

      Whether the operator should be case sensitive or not. Defaults to false (being case sensitive).

    • inverted boolean

      Default value: false

      Whether the result should be negated or not. If true, will turn a true result into a false result and vice versa.

    • values string[]

      The context values that should be used for constraint evaluation. Use this property instead of value for properties that accept multiple values.

    • value string

      The context value that should be used for constraint evaluation. Use this property instead of values for properties that only accept single values.

    • ]
    • variants object[]

      Strategy level variants

    • Array [
    • name string required

      The variant name. Must be unique for this feature toggle

    • weight integer required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is an integer between 0 and 1000. See the section on variant weights for more information

    • weightType string required

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000. Refer to the variant weight documentation.

    • stickiness string required

      The stickiness to use for distribution of this variant. Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • ]
    • parameters object

      A list of parameters for a strategy

    • property name* string
    • segments number[]

      Ids of segments to use for this strategy

    • ]
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-project-health-report.html b/reference/api/unleash/get-project-health-report.html index 324923c4f3..0adacd88a6 100644 --- a/reference/api/unleash/get-project-health-report.html +++ b/reference/api/unleash/get-project-health-report.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Get a health report for a project.

    GET /api/admin/projects/:projectId/health-report

    This endpoint returns a health report for the specified project. This data is used for the technical debt dashboard

    Request​

    Path Parameters

    • projectId string required
    Responses

    healthReportSchema

    Schema
    • version integer required

      The project overview version.

    • name string required

      The project's name

    • description string nullable

      The project's description

    • defaultStickiness string required

      A default stickiness for the project affecting the default stickiness value for variants and Gradual Rollout strategy

    • mode string required

      Possible values: [open, protected, private]

      The project's collaboration mode. Determines whether non-project members can submit change requests or not.

    • featureLimit number nullable

      A limit on the number of features allowed in the project. Null if no limit.

    • members integer required

      The number of users/members in the project.

    • health integer required

      The overall health rating of the project.

    • environments object[]required

      An array containing the names of all the environments configured for the project.

    • Array [
    • environment string required

      The environment to add to the project

    • changeRequestsEnabled boolean

      Whether change requests should be enabled or for this environment on the project or not

    • defaultStrategy object

      A default strategy to create for this environment on the project.

    • name string required

      The name of the strategy type

    • title string nullable

      A descriptive title for the strategy

    • disabled boolean nullable

      A toggle to disable the strategy. defaults to false. Disabled strategies are not evaluated or returned to the SDKs

    • sortOrder number

      The order of the strategy in the list

    • constraints object[]

      A list of the constraints attached to the strategy. See https://docs.getunleash.io/reference/strategy-constraints

    • Array [
    • contextName string required

      The name of the context field that this constraint should apply to.

    • operator string required

      Possible values: [NOT_IN, IN, STR_ENDS_WITH, STR_STARTS_WITH, STR_CONTAINS, NUM_EQ, NUM_GT, NUM_GTE, NUM_LT, NUM_LTE, DATE_AFTER, DATE_BEFORE, SEMVER_EQ, SEMVER_GT, SEMVER_LT]

      The operator to use when evaluating this constraint. For more information about the various operators, refer to the strategy constraint operator documentation.

    • caseInsensitive boolean

      Default value: false

      Whether the operator should be case sensitive or not. Defaults to false (being case sensitive).

    • inverted boolean

      Default value: false

      Whether the result should be negated or not. If true, will turn a true result into a false result and vice versa.

    • values string[]

      The context values that should be used for constraint evaluation. Use this property instead of value for properties that accept multiple values.

    • value string

      The context value that should be used for constraint evaluation. Use this property instead of values for properties that only accept single values.

    • ]
    • variants object[]

      Strategy level variants

    • Array [
    • name string required

      The variant name. Must be unique for this feature toggle

    • weight integer required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is an integer between 0 and 1000. See the section on variant weights for more information

    • weightType string required

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000. Refer to the variant weight documentation.

    • stickiness string required

      The stickiness to use for distribution of this variant. Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • ]
    • parameters object

      A list of parameters for a strategy

    • property name* string
    • segments number[]

      Ids of segments to use for this strategy

    • ]
    • features object[]required

      An array containing an overview of all the features of the project and their individual status

    • Array [
    • name string required

      Unique feature name

    • type string

      Type of the toggle e.g. experiment, kill-switch, release, operational, permission

    • description string nullable

      Detailed description of the feature

    • archived boolean

      true if the feature is archived

    • project string

      Name of the project the feature belongs to

    • enabled boolean

      true if the feature is enabled, otherwise false.

    • stale boolean

      true if the feature is stale based on the age and feature type, otherwise false.

    • favorite boolean

      true if the feature was favorited, otherwise false.

    • impressionData boolean

      true if the impression data collection is enabled for the feature, otherwise false.

    • createdAt date-time nullable

      The date the feature was created

    • archivedAt date-time nullable

      The date the feature was archived

    • lastSeenAt date-time nullable deprecated

      The date when metrics where last collected for the feature. This field is deprecated, use the one in featureEnvironmentSchema

    • environments object[]

      The list of environments where the feature can be used

    • Array [
    • name string required

      The name of the environment

    • featureName string

      The name of the feature

    • environment string

      The name of the environment

    • type string

      The type of the environment

    • enabled boolean required

      true if the feature is enabled for the environment, otherwise false.

    • sortOrder number

      The sort order of the feature environment in the feature environments list

    • variantCount number

      The number of defined variants

    • strategies object[]

      A list of activation strategies for the feature environment

    • Array [
    • id string

      A uuid for the feature strategy

    • name string required

      The name or type of strategy

    • title string nullable

      A descriptive title for the strategy

    • disabled boolean nullable

      A toggle to disable the strategy. defaults to false. Disabled strategies are not evaluated or returned to the SDKs

    • featureName string

      The name or feature the strategy is attached to

    • sortOrder number

      The order of the strategy in the list

    • segments number[]

      A list of segment ids attached to the strategy

    • constraints object[]

      A list of the constraints attached to the strategy. See https://docs.getunleash.io/reference/strategy-constraints

    • Array [
    • contextName string required

      The name of the context field that this constraint should apply to.

    • operator string required

      Possible values: [NOT_IN, IN, STR_ENDS_WITH, STR_STARTS_WITH, STR_CONTAINS, NUM_EQ, NUM_GT, NUM_GTE, NUM_LT, NUM_LTE, DATE_AFTER, DATE_BEFORE, SEMVER_EQ, SEMVER_GT, SEMVER_LT]

      The operator to use when evaluating this constraint. For more information about the various operators, refer to the strategy constraint operator documentation.

    • caseInsensitive boolean

      Default value: false

      Whether the operator should be case sensitive or not. Defaults to false (being case sensitive).

    • inverted boolean

      Default value: false

      Whether the result should be negated or not. If true, will turn a true result into a false result and vice versa.

    • values string[]

      The context values that should be used for constraint evaluation. Use this property instead of value for properties that accept multiple values.

    • value string

      The context value that should be used for constraint evaluation. Use this property instead of values for properties that only accept single values.

    • ]
    • variants object[]

      Strategy level variants

    • Array [
    • name string required

      The variant name. Must be unique for this feature toggle

    • weight integer required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is an integer between 0 and 1000. See the section on variant weights for more information

    • weightType string required

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000. Refer to the variant weight documentation.

    • stickiness string required

      The stickiness to use for distribution of this variant. Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • ]
    • parameters object

      A list of parameters for a strategy

    • property name* string
    • ]
    • variants object[]

      A list of variants for the feature environment

    • Array [
    • name string required

      The variants name. Is unique for this feature toggle

    • weight number required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is a number between 0 and 1000. See the section on variant weights for more information

    • weightType string

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000

    • stickiness string

      Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • overrides object[]

      Overrides assigning specific variants to specific users. The weighting system automatically assigns users to specific groups for you, but any overrides in this list will take precedence.

    • Array [
    • contextName string required

      The name of the context field used to determine overrides

    • values string[] required

      Which values that should be overriden

    • ]
    • ]
    • lastSeenAt date-time nullable

      The date when metrics where last collected for the feature environment

    • hasStrategies boolean

      Whether the feature has any strategies defined.

    • hasEnabledStrategies boolean

      Whether the feature has any enabled strategies defined.

    • ]
    • variants object[]deprecated

      The list of feature variants

    • Array [
    • name string required

      The variants name. Is unique for this feature toggle

    • weight number required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is a number between 0 and 1000. See the section on variant weights for more information

    • weightType string

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000

    • stickiness string

      Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • overrides object[]

      Overrides assigning specific variants to specific users. The weighting system automatically assigns users to specific groups for you, but any overrides in this list will take precedence.

    • Array [
    • contextName string required

      The name of the context field used to determine overrides

    • values string[] required

      Which values that should be overriden

    • ]
    • ]
    • strategies object[] deprecated

      This is a legacy field that will be deprecated

    • tags object[]nullable

      The list of feature tags

    • Array [
    • value string required

      Possible values: >= 2 characters and <= 50 characters

      The value of the tag

    • type string required

      Possible values: >= 2 characters and <= 50 characters

      Default value: simple

      The type of the tag

    • ]
    • children string[]

      The list of child feature names. This is an experimental field and may change.

    • dependencies object[]

      The list of parent dependencies. This is an experimental field and may change.

    • Array [
    • feature string required

      The name of the parent feature

    • enabled boolean

      Whether the parent feature is enabled or not

    • variants string[]

      The list of variants the parent feature should resolve to. Only valid when feature is enabled.

    • ]
    • ]
    • updatedAt date-time nullable

      When the project was last updated.

    • createdAt date-time nullable

      When the project was last updated.

    • favorite boolean

      Indicates if the project has been marked as a favorite by the current user requesting the project health overview.

    • stats object

      Project statistics

    • avgTimeToProdCurrentWindow number required

      The average time from when a feature was created to when it was enabled in the "production" environment during the current window

    • createdCurrentWindow number required

      The number of feature toggles created during the current window

    • createdPastWindow number required

      The number of feature toggles created during the previous window

    • archivedCurrentWindow number required

      The number of feature toggles that were archived during the current window

    • archivedPastWindow number required

      The number of feature toggles that were archived during the previous window

    • projectActivityCurrentWindow number required

      The number of project events that occurred during the current window

    • projectActivityPastWindow number required

      The number of project events that occurred during the previous window

    • projectMembersAddedCurrentWindow number required

      The number of members that were added to the project during the current window

    • featureNaming object

      Create a feature naming pattern

    • pattern string nullable required

      A JavaScript regular expression pattern, without the start and end delimiters. Optional flags are not allowed.

    • example string nullable

      An example of a feature name that matches the pattern. Must itself match the pattern supplied.

    • description string nullable

      A description of the pattern in a human-readable format. Will be shown to users when they create a new feature flag.

    • potentiallyStaleCount number required

      The number of potentially stale feature toggles.

    • activeCount number required

      The number of active feature toggles.

    • staleCount number required

      The number of stale feature toggles.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-project-overview.html b/reference/api/unleash/get-project-overview.html index 7c53af2049..fb510c10a7 100644 --- a/reference/api/unleash/get-project-overview.html +++ b/reference/api/unleash/get-project-overview.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Get an overview of a project.

    GET /api/admin/projects/:projectId/overview

    This endpoint returns an overview of the specified projects stats, project health, number of members, which environments are configured, and the features types in the project.

    Request​

    Path Parameters

    • projectId string required
    Responses

    projectOverviewSchema

    Schema
    • stats object

      Project statistics

    • avgTimeToProdCurrentWindow number required

      The average time from when a feature was created to when it was enabled in the "production" environment during the current window

    • createdCurrentWindow number required

      The number of feature toggles created during the current window

    • createdPastWindow number required

      The number of feature toggles created during the previous window

    • archivedCurrentWindow number required

      The number of feature toggles that were archived during the current window

    • archivedPastWindow number required

      The number of feature toggles that were archived during the previous window

    • projectActivityCurrentWindow number required

      The number of project events that occurred during the current window

    • projectActivityPastWindow number required

      The number of project events that occurred during the previous window

    • projectMembersAddedCurrentWindow number required

      The number of members that were added to the project during the current window

    • version integer required

      The schema version used to describe the project overview

    • name string required

      The name of this project

    • description string nullable

      Additional information about the project

    • defaultStickiness string

      A default stickiness for the project affecting the default stickiness value for variants and Gradual Rollout strategy

    • mode string

      Possible values: [open, protected, private]

      The project's collaboration mode. Determines whether non-project members can submit change requests or not.

    • featureLimit number nullable

      A limit on the number of features allowed in the project. Null if no limit.

    • featureNaming object

      Create a feature naming pattern

    • pattern string nullable required

      A JavaScript regular expression pattern, without the start and end delimiters. Optional flags are not allowed.

    • example string nullable

      An example of a feature name that matches the pattern. Must itself match the pattern supplied.

    • description string nullable

      A description of the pattern in a human-readable format. Will be shown to users when they create a new feature flag.

    • members number

      The number of members this project has

    • health number

      An indicator of the project's health on a scale from 0 to 100

    • environments object[]

      The environments that are enabled for this project

    • Array [
    • environment string required

      The environment to add to the project

    • changeRequestsEnabled boolean

      Whether change requests should be enabled or for this environment on the project or not

    • defaultStrategy object

      A default strategy to create for this environment on the project.

    • name string required

      The name of the strategy type

    • title string nullable

      A descriptive title for the strategy

    • disabled boolean nullable

      A toggle to disable the strategy. defaults to false. Disabled strategies are not evaluated or returned to the SDKs

    • sortOrder number

      The order of the strategy in the list

    • constraints object[]

      A list of the constraints attached to the strategy. See https://docs.getunleash.io/reference/strategy-constraints

    • Array [
    • contextName string required

      The name of the context field that this constraint should apply to.

    • operator string required

      Possible values: [NOT_IN, IN, STR_ENDS_WITH, STR_STARTS_WITH, STR_CONTAINS, NUM_EQ, NUM_GT, NUM_GTE, NUM_LT, NUM_LTE, DATE_AFTER, DATE_BEFORE, SEMVER_EQ, SEMVER_GT, SEMVER_LT]

      The operator to use when evaluating this constraint. For more information about the various operators, refer to the strategy constraint operator documentation.

    • caseInsensitive boolean

      Default value: false

      Whether the operator should be case sensitive or not. Defaults to false (being case sensitive).

    • inverted boolean

      Default value: false

      Whether the result should be negated or not. If true, will turn a true result into a false result and vice versa.

    • values string[]

      The context values that should be used for constraint evaluation. Use this property instead of value for properties that accept multiple values.

    • value string

      The context value that should be used for constraint evaluation. Use this property instead of values for properties that only accept single values.

    • ]
    • variants object[]

      Strategy level variants

    • Array [
    • name string required

      The variant name. Must be unique for this feature toggle

    • weight integer required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is an integer between 0 and 1000. See the section on variant weights for more information

    • weightType string required

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000. Refer to the variant weight documentation.

    • stickiness string required

      The stickiness to use for distribution of this variant. Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • ]
    • parameters object

      A list of parameters for a strategy

    • property name* string
    • segments number[]

      Ids of segments to use for this strategy

    • ]
    • featureTypeCounts object[]

      The number of features of each type that are in this project

    • Array [
    • type string required

      Type of the flag e.g. experiment, kill-switch, release, operational, permission

    • count number required

      Number of feature flags of this type

    • ]
    • updatedAt date-time nullable

      When the project was last updated.

    • createdAt date-time nullable

      When the project was created.

    • favorite boolean

      true if the project was favorited, otherwise false.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-project-users.html b/reference/api/unleash/get-project-users.html index 883d6a7951..bd5427b471 100644 --- a/reference/api/unleash/get-project-users.html +++ b/reference/api/unleash/get-project-users.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Get users in project

    GET /api/admin/projects/:projectId/users
    deprecated

    This endpoint has been deprecated and may be removed in future versions of the API.

    Get users belonging to a project together with their roles as well as a list of roles available to the project. This endpoint is deprecated. Use /:projectId/access instead.

    Request​

    Path Parameters

    • projectId string required
    Responses

    projectUsersSchema

    Schema
    • users object[]required

      A list of users with access to this project and their role within it.

    • Array [
    • isAPI boolean deprecated

      Whether this user is authenticated through Unleash tokens or logged in with a session

    • name string

      The name of the user

    • email string nullable

      The user's email address

    • id integer required

      The user's ID in the Unleash system

    • imageUrl uri nullable

      A URL pointing to the user's image.

    • addedAt date-time

      When this user was added to the project

    • roleId integer

      The ID of the role this user has in the given project

    • roles integer[]

      A list of roles this user has in the given project

    • ]
    • roles object[]required

      A list of roles that are available for this project

    • Array [
    • id integer required

      The role id

    • type string required

      A role can either be a global root role (applies to all projects) or a project role

    • name string required

      The name of the role

    • description string

      A more detailed description of the role and what use it's intended for

    • ]
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-projects.html b/reference/api/unleash/get-projects.html index 6030ceeb12..3c97a71a85 100644 --- a/reference/api/unleash/get-projects.html +++ b/reference/api/unleash/get-projects.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Get a list of all projects.

    GET /api/admin/projects

    This endpoint returns an list of all the projects in the Unleash instance.

    Request​

    Responses

    projectsSchema

    Schema
    • version integer required

      The schema version used to represent the project data.

    • projects object[]required

      A list of projects in the Unleash instance

    • Array [
    • id string required

      The id of this project

    • name string required

      The name of this project

    • description string nullable

      Additional information about the project

    • health number

      An indicator of the project's health on a scale from 0 to 100

    • featureCount number

      The number of features this project has

    • memberCount number

      The number of members this project has

    • createdAt date-time

      When this project was created.

    • updatedAt date-time nullable

      When this project was last updated.

    • favorite boolean

      true if the project was favorited, otherwise false.

    • mode string

      Possible values: [open, protected, private]

      The project's collaboration mode. Determines whether non-project members can submit change requests or not.

    • defaultStickiness string

      A default stickiness for the project affecting the default stickiness value for variants and Gradual Rollout strategy

    • ]
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-public-signup-token.html b/reference/api/unleash/get-public-signup-token.html index 64c2ee327d..05cd384dc7 100644 --- a/reference/api/unleash/get-public-signup-token.html +++ b/reference/api/unleash/get-public-signup-token.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Retrieve a token

    GET /api/admin/invite-link/tokens/:token

    Get information about a specific token. The :token part of the URL should be the token's secret.

    Request​

    Path Parameters

    • token string required
    Responses

    publicSignupTokenSchema

    Schema
    • secret string required

      The actual value of the token. This is the part that is used by Unleash to create an invite link

    • url string nullable required

      The public signup link for the token. Users who follow this link will be taken to a signup page where they can create an Unleash user.

    • name string required

      The token's name. Only for displaying in the UI

    • enabled boolean required

      Whether the token is active. This property will always be false for a token that has expired.

    • expiresAt date-time required

      The time when the token will expire.

    • createdAt date-time required

      When the token was created.

    • createdBy string nullable required

      The creator's email or username

    • users object[]nullable

      Array of users that have signed up using the token.

    • Array [
    • id integer required

      The user id

    • isAPI boolean deprecated

      (Deprecated): Used internally to know which operations the user should be allowed to perform

    • name string nullable

      Name of the user

    • email string

      Email of the user

    • username string nullable

      A unique username for the user

    • imageUrl string

      URL used for the userprofile image

    • inviteLink string

      If the user is actively inviting other users, this is the link that can be shared with other users

    • loginAttempts integer

      How many unsuccessful attempts at logging in has the user made

    • emailSent boolean

      Is the welcome email sent to the user or not

    • rootRole integer

      Which root role this user is assigned

    • seenAt date-time nullable

      The last time this user logged in

    • createdAt date-time

      The user was created at this time

    • accountType string

      A user is either an actual User or a Service Account

    • permissions string[]

      Deprecated

    • ]
    • role objectrequired

      A role holds permissions to allow Unleash to decide what actions a role holder is allowed to perform

    • id integer required

      The role id

    • type string required

      A role can either be a global root role (applies to all projects) or a project role

    • name string required

      The name of the role

    • description string

      A more detailed description of the role and what use it's intended for

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-raw-feature-metrics.html b/reference/api/unleash/get-raw-feature-metrics.html index 6d2a053005..fb088fe6c8 100644 --- a/reference/api/unleash/get-raw-feature-metrics.html +++ b/reference/api/unleash/get-raw-feature-metrics.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Get feature metrics

    GET /api/admin/client-metrics/features/:name/raw

    Get usage metrics for a specific feature for the last 48 hours, grouped by hour

    Request​

    Path Parameters

    • name string required
    Responses

    featureMetricsSchema

    Schema
    • version integer required

      Possible values: >= 1

      The version of this schema

    • maturity string required

      The maturity level of this API (alpha, beta, stable, deprecated)

    • data object[]required

      Metrics gathered per environment

    • Array [
    • featureName string

      The name of the feature

    • appName string

      The name of the application the SDK is being used in

    • environment string required

      Which environment the SDK is being used in

    • timestamp objectrequired

      The start of the time window these metrics are valid for. The window is usually 1 hour wide

      oneOf
    • string date-time

      An RFC-3339-compliant timestamp.

    • yes integer required

      How many times the toggle evaluated to true

    • no integer required

      How many times the toggle evaluated to false

    • variants object

      How many times each variant was returned

    • property name* integer
    • ]
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-requests-per-second.html b/reference/api/unleash/get-requests-per-second.html index c645279e41..9e887ff7dc 100644 --- a/reference/api/unleash/get-requests-per-second.html +++ b/reference/api/unleash/get-requests-per-second.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Gets usage data

    GET /api/admin/metrics/rps

    Gets usage data per app/endpoint from a prometheus compatible metrics endpoint

    Request​

    Responses

    requestsPerSecondSegmentedSchema

    Schema
    • clientMetrics object

      Statistics for usage of Unleash, formatted so it can easily be used in a graph

    • status string

      Possible values: [success, failure]

      Whether the query against prometheus succeeded or failed

    • data object

      The query result from prometheus

    • resultType string

      Possible values: [matrix, vector, scalar, string]

      Prometheus compatible result type.

    • result object[]

      An array of values per metric. Each one represents a line in the graph labeled by its metric name

    • Array [
    • metric object

      A key value set representing the metric

    • appName string

      Name of the application this metric relates to

    • endpoint string

      Which endpoint has been accessed

    • values array[]

      An array of arrays. Each element of the array is an array of size 2 consisting of the 2 axis for the graph: in position zero the x axis represented as a number and position one the y axis represented as string

    • ]
    • adminMetrics object

      Statistics for usage of Unleash, formatted so it can easily be used in a graph

    • status string

      Possible values: [success, failure]

      Whether the query against prometheus succeeded or failed

    • data object

      The query result from prometheus

    • resultType string

      Possible values: [matrix, vector, scalar, string]

      Prometheus compatible result type.

    • result object[]

      An array of values per metric. Each one represents a line in the graph labeled by its metric name

    • Array [
    • metric object

      A key value set representing the metric

    • appName string

      Name of the application this metric relates to

    • endpoint string

      Which endpoint has been accessed

    • values array[]

      An array of arrays. Each element of the array is an array of size 2 consisting of the 2 axis for the graph: in position zero the x axis represented as a number and position one the y axis represented as string

    • ]
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-role-by-id.html b/reference/api/unleash/get-role-by-id.html index f69a77aaa1..85145d63db 100644 --- a/reference/api/unleash/get-role-by-id.html +++ b/reference/api/unleash/get-role-by-id.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Get a single role

    GET /api/admin/roles/:roleId

    Get a single role by role id

    Request​

    Path Parameters

    • roleId string required
    Responses

    roleWithPermissionsSchema

    Schema
    • id number required

      The role id

    • type string required

      A role can either be a global root role, or a project role or a custom project role or a custom global root-custom role

    • name string required

      The name of the role

    • description string

      A more detailed description of the role and what use it's intended for

    • permissions object[]required

      A list of permissions assigned to this role

    • Array [
    • id integer required

      The identifier for this permission

    • name string required

      The name of this permission

    • displayName string required

      The name to display in listings of permissions

    • type string required

      What level this permission applies to. Either root, project or the name of the environment it applies to

    • environment string

      Which environment this permission applies to

    • ]
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-role-project-access.html b/reference/api/unleash/get-role-project-access.html index fc33fdc7d2..c710d7369b 100644 --- a/reference/api/unleash/get-role-project-access.html +++ b/reference/api/unleash/get-role-project-access.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Get project-role mappings

    GET /api/admin/projects/roles/:roleId/access

    For the provided role, retrieves a list of projects that use this role. For each project it also contains information about how the role used in that project, such as how many users, groups, or service accounts that use the role.

    Request​

    Path Parameters

    • roleId string required
    Responses

    projectRoleUsageSchema

    Schema
    • projects object[]

      A collection of projects with counts of users and groups mapped to them with specified roles.

    • Array [
    • project string required

      The id of the project user and group count are counted for.

    • role integer

      Id of the role the user and group count are counted for.

    • userCount integer

      Number of users mapped to this project.

    • serviceAccountCount integer

      Number of service accounts mapped to this project.

    • groupCount integer

      Number of groups mapped to this project.

    • ]
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-roles.html b/reference/api/unleash/get-roles.html index 8c62a0b81f..2215642023 100644 --- a/reference/api/unleash/get-roles.html +++ b/reference/api/unleash/get-roles.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Get a list of roles

    GET /api/admin/roles

    Get a list of project, root and custom roles for Role-Based Access Control

    Request​

    Responses

    rolesWithVersionSchema

    Schema
    • version integer required

      Possible values: >= 1

      The version of this schema

    • roles object[]required

      A list of roles

    • Array [
    • id integer required

      The role id

    • type string required

      A role can either be a global root role (applies to all projects) or a project role

    • name string required

      The name of the role

    • description string

      A more detailed description of the role and what use it's intended for

    • ]
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-saml-settings.html b/reference/api/unleash/get-saml-settings.html index cd57bf0bb8..ad3386a91c 100644 --- a/reference/api/unleash/get-saml-settings.html +++ b/reference/api/unleash/get-saml-settings.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Get SAML auth settings

    GET /api/admin/auth/saml/settings

    Returns the current settings for SAML authentication

    Request​

    Responses

    samlSettingsSchema

    Schema
    • enabled boolean

      Is SAML authentication enabled

    • entityId string required

      The SAML 2.0 entity ID

    • signOnUrl string required

      Which URL to use for Single Sign On

    • certificate string required

      The X509 certificate used to validate requests

    • signOutUrl string

      Which URL to use for Single Sign Out

    • spCertificate string

      Signing certificate for sign out requests

    • autoCreate boolean

      Should Unleash create users based on the emails coming back in the authentication reply from the SAML server

    • emailDomains string

      A comma separated list of email domains that Unleash will auto create user accounts for.

    • defaultRootRole string

      Possible values: [Viewer, Editor, Admin]

      Assign this root role to auto created users

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-scheduled-change-requests.html b/reference/api/unleash/get-scheduled-change-requests.html index 723a63dfa8..7b893f0f67 100644 --- a/reference/api/unleash/get-scheduled-change-requests.html +++ b/reference/api/unleash/get-scheduled-change-requests.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Get scheduled change requests matching a query.

    GET /api/admin/projects/:projectId/change-requests/scheduled

    This endpoint retrieves basic information about all scheduled change requests that match the search criteria provided in the query parameters. The endpoint will return any change request that matches one or more of the provided parameters. If you use no query parameters, you'll get an empty list.

    For instance, to find all the scheduled change requests that either touch feature MyFeature or strategy 0D198067-7D55-460C-9EC7-DB86E3AE261A, you would use the query string feature=MyFeature&strategyId=0D198067-7D55-460C-9EC7-DB86E3AE261A.

    Request​

    Path Parameters

    • projectId string required
    Responses

    changeRequestScheduledResultSchema

    Schema
    • Array [
    • id number required

      The change request id

    • environment string required

      The environment of the change request

    • title string

      The change request title

    • ]
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-segment.html b/reference/api/unleash/get-segment.html index b80477491e..c8aeee1f00 100644 --- a/reference/api/unleash/get-segment.html +++ b/reference/api/unleash/get-segment.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Get a segment

    GET /api/admin/segments/:id

    Retrieves a segment based on its ID.

    Request​

    Path Parameters

    • id string required
    Responses

    adminSegmentSchema

    Schema
    • id integer required

      The ID of this segment

    • name string required

      The name of this segment

    • description string nullable

      The description for this segment

    • constraints object[]required

      The list of constraints that are used in this segment

    • Array [
    • contextName string required

      The name of the context field that this constraint should apply to.

    • operator string required

      Possible values: [NOT_IN, IN, STR_ENDS_WITH, STR_STARTS_WITH, STR_CONTAINS, NUM_EQ, NUM_GT, NUM_GTE, NUM_LT, NUM_LTE, DATE_AFTER, DATE_BEFORE, SEMVER_EQ, SEMVER_GT, SEMVER_LT]

      The operator to use when evaluating this constraint. For more information about the various operators, refer to the strategy constraint operator documentation.

    • caseInsensitive boolean

      Default value: false

      Whether the operator should be case sensitive or not. Defaults to false (being case sensitive).

    • inverted boolean

      Default value: false

      Whether the result should be negated or not. If true, will turn a true result into a false result and vice versa.

    • values string[]

      The context values that should be used for constraint evaluation. Use this property instead of value for properties that accept multiple values.

    • value string

      The context value that should be used for constraint evaluation. Use this property instead of values for properties that only accept single values.

    • ]
    • usedInFeatures integer nullable

      The number of feature flags that use this segment. The number also includes the any flags with pending change requests that would add this segment.

    • usedInProjects integer nullable

      The number of projects that use this segment. The number includes any projects with pending change requests that would add this segment.

    • project string nullable

      The project the segment belongs to. Only present if the segment is a project-specific segment.

    • createdBy string nullable

      The creator's email or username

    • createdAt date-time required

      When the segment was created

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-segments-by-strategy-id.html b/reference/api/unleash/get-segments-by-strategy-id.html index 80da035242..c2f7a9aec3 100644 --- a/reference/api/unleash/get-segments-by-strategy-id.html +++ b/reference/api/unleash/get-segments-by-strategy-id.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Get strategy segments

    GET /api/admin/segments/strategies/:strategyId

    Retrieve all segments that are referenced by the specified strategy. Returns an empty list of segments if the strategy ID doesn't exist.

    Request​

    Path Parameters

    • strategyId string required
    Responses

    segmentsSchema

    Schema
    • segments object[]

      A list of segments

    • Array [
    • id integer required

      The ID of this segment

    • name string required

      The name of this segment

    • description string nullable

      The description for this segment

    • constraints object[]required

      The list of constraints that are used in this segment

    • Array [
    • contextName string required

      The name of the context field that this constraint should apply to.

    • operator string required

      Possible values: [NOT_IN, IN, STR_ENDS_WITH, STR_STARTS_WITH, STR_CONTAINS, NUM_EQ, NUM_GT, NUM_GTE, NUM_LT, NUM_LTE, DATE_AFTER, DATE_BEFORE, SEMVER_EQ, SEMVER_GT, SEMVER_LT]

      The operator to use when evaluating this constraint. For more information about the various operators, refer to the strategy constraint operator documentation.

    • caseInsensitive boolean

      Default value: false

      Whether the operator should be case sensitive or not. Defaults to false (being case sensitive).

    • inverted boolean

      Default value: false

      Whether the result should be negated or not. If true, will turn a true result into a false result and vice versa.

    • values string[]

      The context values that should be used for constraint evaluation. Use this property instead of value for properties that accept multiple values.

    • value string

      The context value that should be used for constraint evaluation. Use this property instead of values for properties that only accept single values.

    • ]
    • usedInFeatures integer nullable

      The number of feature flags that use this segment. The number also includes the any flags with pending change requests that would add this segment.

    • usedInProjects integer nullable

      The number of projects that use this segment. The number includes any projects with pending change requests that would add this segment.

    • project string nullable

      The project the segment belongs to. Only present if the segment is a project-specific segment.

    • createdBy string nullable

      The creator's email or username

    • createdAt date-time required

      When the segment was created

    • ]
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-segments.html b/reference/api/unleash/get-segments.html index 83184d06b2..d40b2b3ee2 100644 --- a/reference/api/unleash/get-segments.html +++ b/reference/api/unleash/get-segments.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Get all segments

    GET /api/admin/segments

    Retrieves all segments that exist in this Unleash instance.

    Request​

    Responses

    segmentsSchema

    Schema
    • segments object[]

      A list of segments

    • Array [
    • id integer required

      The ID of this segment

    • name string required

      The name of this segment

    • description string nullable

      The description for this segment

    • constraints object[]required

      The list of constraints that are used in this segment

    • Array [
    • contextName string required

      The name of the context field that this constraint should apply to.

    • operator string required

      Possible values: [NOT_IN, IN, STR_ENDS_WITH, STR_STARTS_WITH, STR_CONTAINS, NUM_EQ, NUM_GT, NUM_GTE, NUM_LT, NUM_LTE, DATE_AFTER, DATE_BEFORE, SEMVER_EQ, SEMVER_GT, SEMVER_LT]

      The operator to use when evaluating this constraint. For more information about the various operators, refer to the strategy constraint operator documentation.

    • caseInsensitive boolean

      Default value: false

      Whether the operator should be case sensitive or not. Defaults to false (being case sensitive).

    • inverted boolean

      Default value: false

      Whether the result should be negated or not. If true, will turn a true result into a false result and vice versa.

    • values string[]

      The context values that should be used for constraint evaluation. Use this property instead of value for properties that accept multiple values.

    • value string

      The context value that should be used for constraint evaluation. Use this property instead of values for properties that only accept single values.

    • ]
    • usedInFeatures integer nullable

      The number of feature flags that use this segment. The number also includes the any flags with pending change requests that would add this segment.

    • usedInProjects integer nullable

      The number of projects that use this segment. The number includes any projects with pending change requests that would add this segment.

    • project string nullable

      The project the segment belongs to. Only present if the segment is a project-specific segment.

    • createdBy string nullable

      The creator's email or username

    • createdAt date-time required

      When the segment was created

    • ]
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-service-account-tokens.html b/reference/api/unleash/get-service-account-tokens.html index b825938fef..9bca75e638 100644 --- a/reference/api/unleash/get-service-account-tokens.html +++ b/reference/api/unleash/get-service-account-tokens.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    List all tokens for a service account.

    GET /api/admin/service-account/:id/token

    Returns the list of all tokens for a service account identified by the id.

    Request​

    Path Parameters

    • id string required
    Responses

    patsSchema

    Schema
    • pats object[]

      A collection of Personal Access Tokens

    • Array [
    • id integer

      Possible values: >= 1

      The unique identification number for this Personal Access Token. (This property is set by Unleash when the token is created and cannot be set manually: if you provide a value when creating a PAT, Unleash will ignore it.)

    • secret string

      The token used for authentication. (This property is set by Unleash when the token is created and cannot be set manually: if you provide a value when creating a PAT, Unleash will ignore it.)

    • expiresAt date-time

      The token's expiration date.

    • createdAt date-time

      When the token was created. (This property is set by Unleash when the token is created and cannot be set manually: if you provide a value when creating a PAT, Unleash will ignore it.)

    • seenAt date-time nullable

      When the token was last seen/used to authenticate with. null if it has not been used yet. (This property is set by Unleash when the token is created and cannot be set manually: if you provide a value when creating a PAT, Unleash will ignore it.)

    • ]
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-service-accounts.html b/reference/api/unleash/get-service-accounts.html index f23b3a3b62..a0f35c0555 100644 --- a/reference/api/unleash/get-service-accounts.html +++ b/reference/api/unleash/get-service-accounts.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    List service accounts.

    GET /api/admin/service-account

    Returns the list of all service accounts.

    Request​

    Responses

    serviceAccountsSchema

    Schema
    • serviceAccounts object[]required

      A list of service accounts

    • Array [
    • id number required

      The service account id

    • isAPI boolean deprecated

      Deprecated: for internal use only, should not be exposed through the API

    • name string

      The name of the service account

    • email string deprecated

      Deprecated: service accounts don't have emails associated with them

    • username string

      The service account username

    • imageUrl string

      The service account image url

    • inviteLink string deprecated

      Deprecated: service accounts cannot be invited via an invitation link

    • loginAttempts number deprecated

      Deprecated: service accounts cannot log in to Unleash

    • emailSent boolean deprecated

      Deprecated: internal use only

    • rootRole integer

      The root role id associated with the service account

    • seenAt date-time nullable deprecated

      Deprecated. This property is always null. To find out when a service account was last seen, check its tokens list and refer to each token's lastSeen property instead.

    • createdAt date-time

      The service account creation date

    • tokens object[]

      The list of tokens associated with the service account

    • Array [
    • id integer

      Possible values: >= 1

      The unique identification number for this Personal Access Token. (This property is set by Unleash when the token is created and cannot be set manually: if you provide a value when creating a PAT, Unleash will ignore it.)

    • secret string

      The token used for authentication. (This property is set by Unleash when the token is created and cannot be set manually: if you provide a value when creating a PAT, Unleash will ignore it.)

    • expiresAt date-time

      The token's expiration date.

    • createdAt date-time

      When the token was created. (This property is set by Unleash when the token is created and cannot be set manually: if you provide a value when creating a PAT, Unleash will ignore it.)

    • seenAt date-time nullable

      When the token was last seen/used to authenticate with. null if it has not been used yet. (This property is set by Unleash when the token is created and cannot be set manually: if you provide a value when creating a PAT, Unleash will ignore it.)

    • ]
    • ]
    • rootRoles object[]

      A list of root roles that are referenced from service account objects in the serviceAccounts list

    • Array [
    • id integer required

      The role id

    • type string required

      A role can either be a global root role (applies to all projects) or a project role

    • name string required

      The name of the role

    • description string

      A more detailed description of the role and what use it's intended for

    • ]
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-simple-settings.html b/reference/api/unleash/get-simple-settings.html index db64a3dcad..7e858d57c0 100644 --- a/reference/api/unleash/get-simple-settings.html +++ b/reference/api/unleash/get-simple-settings.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Get Simple auth settings

    GET /api/admin/auth/simple/settings

    Is simple authentication (username/password) enabled for this server

    Request​

    Responses

    passwordAuthSchema

    Schema
    • enabled boolean

      Is username/password authentication enabled

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-strategies-by-context-field.html b/reference/api/unleash/get-strategies-by-context-field.html index 8cd426bca6..9943e3f99c 100644 --- a/reference/api/unleash/get-strategies-by-context-field.html +++ b/reference/api/unleash/get-strategies-by-context-field.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Get strategies that use a context field

    GET /api/admin/context/:contextField/strategies

    Retrieves a list of all strategies that use the specified context field. If the context field doesn't exist, returns an empty list of strategies

    Request​

    Path Parameters

    • contextField string required
    Responses

    contextFieldStrategiesSchema

    Schema
    • strategies object[]required

      List of strategies using the context field

    • Array [
    • id string required

      The ID of the strategy.

    • featureName string required

      The name of the feature that contains this strategy.

    • projectId string required

      The ID of the project that contains this feature.

    • environment string required

      The ID of the environment where this strategy is in.

    • strategyName string required

      The name of the strategy.

    • ]
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-strategies-by-segment-id.html b/reference/api/unleash/get-strategies-by-segment-id.html index 997ec3577f..9ab7714104 100644 --- a/reference/api/unleash/get-strategies-by-segment-id.html +++ b/reference/api/unleash/get-strategies-by-segment-id.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Get strategies that reference segment

    GET /api/admin/segments/:id/strategies

    Retrieve all strategies that reference the specified segment.

    Request​

    Path Parameters

    • id string required
    Responses

    segmentStrategiesSchema

    Schema
    • strategies object[]required

      The list of strategies

    • Array [
    • id string required

      The ID of the strategy

    • featureName string required

      The name of the feature flag that this strategy belongs to.

    • projectId string required

      The ID of the project that the strategy belongs to.

    • environment string required

      The ID of the environment that the strategy belongs to.

    • strategyName string required

      The name of the strategy's type.

    • ]
    • changeRequestStrategies object[]

      A list of strategies that use this segment in active change requests.

    • Array [
    • id string

      The ID of the strategy. Not present on new strategies that haven't been added to the feature flag yet.

    • featureName string required

      The name of the feature flag that this strategy belongs to.

    • projectId string required

      The ID of the project that the strategy belongs to.

    • environment string required

      The ID of the environment that the strategy belongs to.

    • strategyName string required

      The name of the strategy's type.

    • ]
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-strategy.html b/reference/api/unleash/get-strategy.html index 1cce10f114..a7aa8054f1 100644 --- a/reference/api/unleash/get-strategy.html +++ b/reference/api/unleash/get-strategy.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Get a strategy definition

    GET /api/admin/strategies/:name

    Retrieves the definition of the strategy specified in the URL

    Request​

    Path Parameters

    • name string required
    Responses

    strategySchema

    Schema
    • title string nullable

      An optional title for the strategy

    • name string required

      The name (type) of the strategy

    • displayName string nullable required

      A human friendly name for the strategy

    • description string nullable required

      A short description of the strategy

    • editable boolean required

      Whether the strategy can be edited or not. Strategies bundled with Unleash cannot be edited.

    • deprecated boolean required
    • parameters object[]required

      A list of relevant parameters for each strategy

    • Array [
    • name string
    • type string
    • description string
    • required boolean
    • ]
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-tag-type.html b/reference/api/unleash/get-tag-type.html index e5c6f56998..aa49a485d0 100644 --- a/reference/api/unleash/get-tag-type.html +++ b/reference/api/unleash/get-tag-type.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Get a tag type

    GET /api/admin/tag-types/:name

    Get a tag type by name.

    Request​

    Path Parameters

    • name string required
    Responses

    tagTypeSchema

    Schema
    • name string required

      The name of the tag type.

    • description string

      The description of the tag type.

    • icon string nullable

      The icon of the tag type.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-tag-types.html b/reference/api/unleash/get-tag-types.html index 83dce88715..f4c84502e2 100644 --- a/reference/api/unleash/get-tag-types.html +++ b/reference/api/unleash/get-tag-types.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Get all tag types

    GET /api/admin/tag-types

    Get a list of all available tag types.

    Request​

    Responses

    tagTypesSchema

    Schema
    • version integer required

      The version of the schema used to model the tag types.

    • tagTypes object[]required

      The list of tag types.

    • Array [
    • name string required

      The name of the tag type.

    • description string

      The description of the tag type.

    • icon string nullable

      The icon of the tag type.

    • ]
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-tag.html b/reference/api/unleash/get-tag.html index 7d88321636..f6202389f2 100644 --- a/reference/api/unleash/get-tag.html +++ b/reference/api/unleash/get-tag.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Get a tag by type and value.

    GET /api/admin/tags/:type/:value

    Get a tag by type and value. Can be used to check whether a given tag already exists in Unleash or not.

    Request​

    Path Parameters

    • type string required
    • value string required
    Responses

    tagWithVersionSchema

    Schema
    • version integer required

      The version of the schema used to model the tag.

    • tag objectrequired

      Representation of a tag

    • value string required

      Possible values: >= 2 characters and <= 50 characters

      The value of the tag

    • type string required

      Possible values: >= 2 characters and <= 50 characters

      Default value: simple

      The type of the tag

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-tags-by-type.html b/reference/api/unleash/get-tags-by-type.html index f1433c90f1..1bb3ee8320 100644 --- a/reference/api/unleash/get-tags-by-type.html +++ b/reference/api/unleash/get-tags-by-type.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    List all tags of a given type.

    GET /api/admin/tags/:type

    List all tags of a given type. If the tag type does not exist it returns an empty list.

    Request​

    Path Parameters

    • type string required
    Responses

    tagsSchema

    Schema
    • version integer required

      The version of the schema used to model the tags.

    • tags object[]required

      A list of tags.

    • Array [
    • value string required

      Possible values: >= 2 characters and <= 50 characters

      The value of the tag

    • type string required

      Possible values: >= 2 characters and <= 50 characters

      Default value: simple

      The type of the tag

    • ]
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-tags.html b/reference/api/unleash/get-tags.html index 61620f98fb..117066a0e8 100644 --- a/reference/api/unleash/get-tags.html +++ b/reference/api/unleash/get-tags.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    List all tags.

    GET /api/admin/tags

    List all tags available in Unleash.

    Request​

    Responses

    tagsSchema

    Schema
    • version integer required

      The version of the schema used to model the tags.

    • tags object[]required

      A list of tags.

    • Array [
    • value string required

      Possible values: >= 2 characters and <= 50 characters

      The value of the tag

    • type string required

      Possible values: >= 2 characters and <= 50 characters

      Default value: simple

      The type of the tag

    • ]
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-telemetry-settings.html b/reference/api/unleash/get-telemetry-settings.html index dda4c9f96c..a390d73f97 100644 --- a/reference/api/unleash/get-telemetry-settings.html +++ b/reference/api/unleash/get-telemetry-settings.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Get telemetry settings

    GET /api/admin/telemetry/settings

    Provides the configured settings for telemetry information collection

    Request​

    Responses

    telemetrySettingsSchema

    Schema
    • versionInfoCollectionEnabled boolean required

      Whether collection of version info is enabled/active.

    • featureInfoCollectionEnabled boolean required

      Whether collection of feature usage metrics is enabled/active.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-ui-config.html b/reference/api/unleash/get-ui-config.html index f374546302..b38df94a4f 100644 --- a/reference/api/unleash/get-ui-config.html +++ b/reference/api/unleash/get-ui-config.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Get UI configuration

    GET /api/admin/ui-config

    Retrieves the full configuration used to set up the Unleash Admin UI.

    Request​

    Responses

    uiConfigSchema

    Schema
    • slogan string

      The slogan to display in the UI footer.

    • name string

      The name of this Unleash instance. Used to build the text in the footer.

    • version string required

      The current version of Unleash

    • environment string

      What kind of Unleash instance it is: Enterprise, Pro, or Open source

    • unleashUrl string required

      The URL of the Unleash instance.

    • baseUriPath string required

      The base URI path at which this Unleash instance is listening.

    • feedbackUriPath string

      The URI path at which the feedback endpoint is listening.

    • disablePasswordAuth boolean

      Whether password authentication should be disabled or not.

    • emailEnabled boolean

      Whether this instance can send out emails or not.

    • maintenanceMode boolean

      Whether maintenance mode is currently active or not.

    • segmentValuesLimit number

      The maximum number of values that can be used in a single segment.

    • strategySegmentsLimit number

      The maximum number of segments that can be applied to a single strategy.

    • networkViewEnabled boolean

      Whether to enable the Unleash network view or not.

    • frontendApiOrigins string[]

      The list of origins that the front-end API should accept requests from.

    • flags object

      Additional (largely experimental) features that are enabled in this Unleash instance.

    • anyOf
    • links object[]

      Relevant links to use in the UI.

    • authenticationType string

      Possible values: [open-source, demo, enterprise, hosted, custom, none]

      The type of authentication enabled for this Unleash instance

    • versionInfo objectrequired

      Detailed information about an Unleash version

    • current objectrequired

      The current version of Unleash.

    • oss string

      The OSS version used when building this Unleash instance, represented as a git revision belonging to the main Unleash git repo

    • enterprise string

      The Enterpris version of Unleash used to build this instance, represented as a git revision belonging to the Unleash Enterprise repository. Will be an empty string if no enterprise version was used,

    • latest objectrequired

      Information about the latest available Unleash releases. Will be an empty object if no data is available.

    • oss string

      The latest available OSS version of Unleash

    • enterprise string

      The latest available Enterprise version of Unleash

    • isLatest boolean required

      Whether the Unleash server is running the latest release (true) or if there are updates available (false)

    • instanceId string

      The instance identifier of the Unleash instance

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-user.html b/reference/api/unleash/get-user.html index b0d5731e57..95f0e8a58e 100644 --- a/reference/api/unleash/get-user.html +++ b/reference/api/unleash/get-user.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Get user

    GET /api/admin/user-admin/:id

    Will return a single user by id

    Request​

    Path Parameters

    • id string required
    Responses

    userSchema

    Schema
    • id integer required

      The user id

    • isAPI boolean deprecated

      (Deprecated): Used internally to know which operations the user should be allowed to perform

    • name string nullable

      Name of the user

    • email string

      Email of the user

    • username string nullable

      A unique username for the user

    • imageUrl string

      URL used for the userprofile image

    • inviteLink string

      If the user is actively inviting other users, this is the link that can be shared with other users

    • loginAttempts integer

      How many unsuccessful attempts at logging in has the user made

    • emailSent boolean

      Is the welcome email sent to the user or not

    • rootRole integer

      Which root role this user is assigned

    • seenAt date-time nullable

      The last time this user logged in

    • createdAt date-time

      The user was created at this time

    • accountType string

      A user is either an actual User or a Service Account

    • permissions string[]

      Deprecated

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-users.html b/reference/api/unleash/get-users.html index cd99e63c8b..e8d1bd9b1d 100644 --- a/reference/api/unleash/get-users.html +++ b/reference/api/unleash/get-users.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Get all users and [root roles](https://docs.getunleash.io/reference/rbac#predefined-roles)

    GET /api/admin/user-admin

    Will return all users and all available root roles for the Unleash instance.

    Request​

    Responses

    usersSchema

    Schema
    • users object[]required

      A list of users in the Unleash instance.

    • Array [
    • id integer required

      The user id

    • isAPI boolean deprecated

      (Deprecated): Used internally to know which operations the user should be allowed to perform

    • name string nullable

      Name of the user

    • email string

      Email of the user

    • username string nullable

      A unique username for the user

    • imageUrl string

      URL used for the userprofile image

    • inviteLink string

      If the user is actively inviting other users, this is the link that can be shared with other users

    • loginAttempts integer

      How many unsuccessful attempts at logging in has the user made

    • emailSent boolean

      Is the welcome email sent to the user or not

    • rootRole integer

      Which root role this user is assigned

    • seenAt date-time nullable

      The last time this user logged in

    • createdAt date-time

      The user was created at this time

    • accountType string

      A user is either an actual User or a Service Account

    • permissions string[]

      Deprecated

    • ]
    • rootRoles object[]

      A list of root roles in the Unleash instance.

    • Array [
    • id integer required

      The role id

    • type string required

      A role can either be a global root role (applies to all projects) or a project role

    • name string required

      The name of the role

    • description string

      A more detailed description of the role and what use it's intended for

    • ]
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/get-valid-tokens.html b/reference/api/unleash/get-valid-tokens.html index d8c169b5ac..c790edbe8e 100644 --- a/reference/api/unleash/get-valid-tokens.html +++ b/reference/api/unleash/get-valid-tokens.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Check which tokens are valid

    POST /edge/validate

    This operation accepts a list of tokens to validate. Unleash will validate each token you provide. For each valid token you provide, Unleash will return the token along with its type and which projects it has access to.

    Request​

    Body

    required

    tokenStringListSchema

    • tokens string[] required

      Tokens that we want to get access information about

    Responses

    validatedEdgeTokensSchema

    Schema
    • tokens object[]required

      The list of Unleash token objects. Each object contains the token itself and some additional metadata.

    • Array [
    • projects string[] required

      The list of projects this token has access to. If the token has access to specific projects they will be listed here. If the token has access to all projects it will be represented as [*]

    • type string required

      Possible values: [client, admin, frontend]

      The API token's type. Unleash supports three different types of API tokens (ADMIN, CLIENT, FRONTEND). They all have varying access, so when validating a token it's important to know what kind you're dealing with

    • token string required

      The actual token value. Unleash API tokens are comprised of three parts. <project(s)>:.randomcharacters

    • ]
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/import-export.html b/reference/api/unleash/import-export.html index 2ec02423e0..a6e70caa39 100644 --- a/reference/api/unleash/import-export.html +++ b/reference/api/unleash/import-export.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Import/Export

    Import and export the state of your Unleash instance.

    - + \ No newline at end of file diff --git a/reference/api/unleash/import-toggles.html b/reference/api/unleash/import-toggles.html index a416dfe212..fc6070ca15 100644 --- a/reference/api/unleash/import-toggles.html +++ b/reference/api/unleash/import-toggles.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Import feature toggles

    POST /api/admin/features-batch/import

    Import feature toggles into a specific project and environment.

    Request​

    Body

    required

    importTogglesSchema

    • project string required

      The exported project

    • environment string required

      The exported environment

    • data objectrequired

      The result of the export operation, providing you with the feature toggle definitions, strategy definitions and the rest of the elements relevant to the features (tags, environments etc.)

    • features object[]required

      All the exported features.

    • Array [
    • name string required

      Unique feature name

    • type string

      Type of the toggle e.g. experiment, kill-switch, release, operational, permission

    • description string nullable

      Detailed description of the feature

    • archived boolean

      true if the feature is archived

    • project string

      Name of the project the feature belongs to

    • enabled boolean

      true if the feature is enabled, otherwise false.

    • stale boolean

      true if the feature is stale based on the age and feature type, otherwise false.

    • favorite boolean

      true if the feature was favorited, otherwise false.

    • impressionData boolean

      true if the impression data collection is enabled for the feature, otherwise false.

    • createdAt date-time nullable

      The date the feature was created

    • archivedAt date-time nullable

      The date the feature was archived

    • lastSeenAt date-time nullable deprecated

      The date when metrics where last collected for the feature. This field is deprecated, use the one in featureEnvironmentSchema

    • environments object[]

      The list of environments where the feature can be used

    • Array [
    • name string required

      The name of the environment

    • featureName string

      The name of the feature

    • environment string

      The name of the environment

    • type string

      The type of the environment

    • enabled boolean required

      true if the feature is enabled for the environment, otherwise false.

    • sortOrder number

      The sort order of the feature environment in the feature environments list

    • variantCount number

      The number of defined variants

    • strategies object[]

      A list of activation strategies for the feature environment

    • Array [
    • id string

      A uuid for the feature strategy

    • name string required

      The name or type of strategy

    • title string nullable

      A descriptive title for the strategy

    • disabled boolean nullable

      A toggle to disable the strategy. defaults to false. Disabled strategies are not evaluated or returned to the SDKs

    • featureName string

      The name or feature the strategy is attached to

    • sortOrder number

      The order of the strategy in the list

    • segments number[]

      A list of segment ids attached to the strategy

    • constraints object[]

      A list of the constraints attached to the strategy. See https://docs.getunleash.io/reference/strategy-constraints

    • Array [
    • contextName string required

      The name of the context field that this constraint should apply to.

    • operator string required

      Possible values: [NOT_IN, IN, STR_ENDS_WITH, STR_STARTS_WITH, STR_CONTAINS, NUM_EQ, NUM_GT, NUM_GTE, NUM_LT, NUM_LTE, DATE_AFTER, DATE_BEFORE, SEMVER_EQ, SEMVER_GT, SEMVER_LT]

      The operator to use when evaluating this constraint. For more information about the various operators, refer to the strategy constraint operator documentation.

    • caseInsensitive boolean

      Default value: false

      Whether the operator should be case sensitive or not. Defaults to false (being case sensitive).

    • inverted boolean

      Default value: false

      Whether the result should be negated or not. If true, will turn a true result into a false result and vice versa.

    • values string[]

      The context values that should be used for constraint evaluation. Use this property instead of value for properties that accept multiple values.

    • value string

      The context value that should be used for constraint evaluation. Use this property instead of values for properties that only accept single values.

    • ]
    • variants object[]

      Strategy level variants

    • Array [
    • name string required

      The variant name. Must be unique for this feature toggle

    • weight integer required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is an integer between 0 and 1000. See the section on variant weights for more information

    • weightType string required

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000. Refer to the variant weight documentation.

    • stickiness string required

      The stickiness to use for distribution of this variant. Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • ]
    • parameters object

      A list of parameters for a strategy

    • property name* string
    • ]
    • variants object[]

      A list of variants for the feature environment

    • Array [
    • name string required

      The variants name. Is unique for this feature toggle

    • weight number required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is a number between 0 and 1000. See the section on variant weights for more information

    • weightType string

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000

    • stickiness string

      Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • overrides object[]

      Overrides assigning specific variants to specific users. The weighting system automatically assigns users to specific groups for you, but any overrides in this list will take precedence.

    • Array [
    • contextName string required

      The name of the context field used to determine overrides

    • values string[] required

      Which values that should be overriden

    • ]
    • ]
    • lastSeenAt date-time nullable

      The date when metrics where last collected for the feature environment

    • hasStrategies boolean

      Whether the feature has any strategies defined.

    • hasEnabledStrategies boolean

      Whether the feature has any enabled strategies defined.

    • ]
    • variants object[]deprecated

      The list of feature variants

    • Array [
    • name string required

      The variants name. Is unique for this feature toggle

    • weight number required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is a number between 0 and 1000. See the section on variant weights for more information

    • weightType string

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000

    • stickiness string

      Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • overrides object[]

      Overrides assigning specific variants to specific users. The weighting system automatically assigns users to specific groups for you, but any overrides in this list will take precedence.

    • Array [
    • contextName string required

      The name of the context field used to determine overrides

    • values string[] required

      Which values that should be overriden

    • ]
    • ]
    • strategies object[] deprecated

      This is a legacy field that will be deprecated

    • tags object[]nullable

      The list of feature tags

    • Array [
    • value string required

      Possible values: >= 2 characters and <= 50 characters

      The value of the tag

    • type string required

      Possible values: >= 2 characters and <= 50 characters

      Default value: simple

      The type of the tag

    • ]
    • children string[]

      The list of child feature names. This is an experimental field and may change.

    • dependencies object[]

      The list of parent dependencies. This is an experimental field and may change.

    • Array [
    • feature string required

      The name of the parent feature

    • enabled boolean

      Whether the parent feature is enabled or not

    • variants string[]

      The list of variants the parent feature should resolve to. Only valid when feature is enabled.

    • ]
    • ]
    • featureStrategies object[]required

      All strategy instances that are used by the exported features in the features list.

    • Array [
    • id string

      A uuid for the feature strategy

    • name string required

      The name or type of strategy

    • title string nullable

      A descriptive title for the strategy

    • disabled boolean nullable

      A toggle to disable the strategy. defaults to false. Disabled strategies are not evaluated or returned to the SDKs

    • featureName string

      The name or feature the strategy is attached to

    • sortOrder number

      The order of the strategy in the list

    • segments number[]

      A list of segment ids attached to the strategy

    • constraints object[]

      A list of the constraints attached to the strategy. See https://docs.getunleash.io/reference/strategy-constraints

    • Array [
    • contextName string required

      The name of the context field that this constraint should apply to.

    • operator string required

      Possible values: [NOT_IN, IN, STR_ENDS_WITH, STR_STARTS_WITH, STR_CONTAINS, NUM_EQ, NUM_GT, NUM_GTE, NUM_LT, NUM_LTE, DATE_AFTER, DATE_BEFORE, SEMVER_EQ, SEMVER_GT, SEMVER_LT]

      The operator to use when evaluating this constraint. For more information about the various operators, refer to the strategy constraint operator documentation.

    • caseInsensitive boolean

      Default value: false

      Whether the operator should be case sensitive or not. Defaults to false (being case sensitive).

    • inverted boolean

      Default value: false

      Whether the result should be negated or not. If true, will turn a true result into a false result and vice versa.

    • values string[]

      The context values that should be used for constraint evaluation. Use this property instead of value for properties that accept multiple values.

    • value string

      The context value that should be used for constraint evaluation. Use this property instead of values for properties that only accept single values.

    • ]
    • variants object[]

      Strategy level variants

    • Array [
    • name string required

      The variant name. Must be unique for this feature toggle

    • weight integer required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is an integer between 0 and 1000. See the section on variant weights for more information

    • weightType string required

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000. Refer to the variant weight documentation.

    • stickiness string required

      The stickiness to use for distribution of this variant. Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • ]
    • parameters object

      A list of parameters for a strategy

    • property name* string
    • ]
    • featureEnvironments object[]

      Environment-specific configuration for all the features in the features list. Includes data such as whether the feature is enabled in the selected export environment, whether there are any variants assigned, etc.

    • Array [
    • name string required

      The name of the environment

    • featureName string

      The name of the feature

    • environment string

      The name of the environment

    • type string

      The type of the environment

    • enabled boolean required

      true if the feature is enabled for the environment, otherwise false.

    • sortOrder number

      The sort order of the feature environment in the feature environments list

    • variantCount number

      The number of defined variants

    • strategies object[]

      A list of activation strategies for the feature environment

    • Array [
    • id string

      A uuid for the feature strategy

    • name string required

      The name or type of strategy

    • title string nullable

      A descriptive title for the strategy

    • disabled boolean nullable

      A toggle to disable the strategy. defaults to false. Disabled strategies are not evaluated or returned to the SDKs

    • featureName string

      The name or feature the strategy is attached to

    • sortOrder number

      The order of the strategy in the list

    • segments number[]

      A list of segment ids attached to the strategy

    • constraints object[]

      A list of the constraints attached to the strategy. See https://docs.getunleash.io/reference/strategy-constraints

    • Array [
    • contextName string required

      The name of the context field that this constraint should apply to.

    • operator string required

      Possible values: [NOT_IN, IN, STR_ENDS_WITH, STR_STARTS_WITH, STR_CONTAINS, NUM_EQ, NUM_GT, NUM_GTE, NUM_LT, NUM_LTE, DATE_AFTER, DATE_BEFORE, SEMVER_EQ, SEMVER_GT, SEMVER_LT]

      The operator to use when evaluating this constraint. For more information about the various operators, refer to the strategy constraint operator documentation.

    • caseInsensitive boolean

      Default value: false

      Whether the operator should be case sensitive or not. Defaults to false (being case sensitive).

    • inverted boolean

      Default value: false

      Whether the result should be negated or not. If true, will turn a true result into a false result and vice versa.

    • values string[]

      The context values that should be used for constraint evaluation. Use this property instead of value for properties that accept multiple values.

    • value string

      The context value that should be used for constraint evaluation. Use this property instead of values for properties that only accept single values.

    • ]
    • variants object[]

      Strategy level variants

    • Array [
    • name string required

      The variant name. Must be unique for this feature toggle

    • weight integer required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is an integer between 0 and 1000. See the section on variant weights for more information

    • weightType string required

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000. Refer to the variant weight documentation.

    • stickiness string required

      The stickiness to use for distribution of this variant. Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • ]
    • parameters object

      A list of parameters for a strategy

    • property name* string
    • ]
    • variants object[]

      A list of variants for the feature environment

    • Array [
    • name string required

      The variants name. Is unique for this feature toggle

    • weight number required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is a number between 0 and 1000. See the section on variant weights for more information

    • weightType string

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000

    • stickiness string

      Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • overrides object[]

      Overrides assigning specific variants to specific users. The weighting system automatically assigns users to specific groups for you, but any overrides in this list will take precedence.

    • Array [
    • contextName string required

      The name of the context field used to determine overrides

    • values string[] required

      Which values that should be overriden

    • ]
    • ]
    • lastSeenAt date-time nullable

      The date when metrics where last collected for the feature environment

    • hasStrategies boolean

      Whether the feature has any strategies defined.

    • hasEnabledStrategies boolean

      Whether the feature has any enabled strategies defined.

    • ]
    • contextFields object[]

      A list of all the context fields that are in use by any of the strategies in the featureStrategies list.

    • Array [
    • name string required

      The name of the context field

    • description string nullable

      The description of the context field.

    • stickiness boolean

      Does this context field support being used for stickiness calculations

    • sortOrder integer

      Used when sorting a list of context fields. Is also used as a tiebreaker if a list of context fields is sorted alphabetically.

    • createdAt date-time nullable

      When this context field was created

    • usedInFeatures integer nullable

      Number of projects where this context field is used in

    • usedInProjects integer nullable

      Number of projects where this context field is used in

    • legalValues object[]

      Allowed values for this context field schema. Can be used to narrow down accepted input

    • Array [
    • value string required

      The valid value

    • description string

      Describes this specific legal value

    • ]
    • ]
    • featureTags object[]

      A list of all the tags that have been applied to any of the features in the features list.

    • Array [
    • featureName string required

      The name of the feature this tag is applied to

    • tagType string

      The [type](https://docs.getunleash.io/reference/tags#tag-types tag types) of the tag

    • tagValue string required

      The value of the tag

    • type string deprecated

      The [type](https://docs.getunleash.io/reference/tags#tag-types tag types) of the tag. This property is deprecated and will be removed in a future version of Unleash. Superseded by the tagType property.

    • value string deprecated

      The value of the tag. This property is deprecated and will be removed in a future version of Unleash. Superseded by the tagValue property.

    • createdByUserId number nullable

      The id of the user who created this tag

    • ]
    • segments object[]

      A list of all the segments that are used by the strategies in the featureStrategies list.

    • Array [
    • id number required
    • name string required
    • ]
    • tagTypes object[]required

      A list of all of the tag types that are used in the featureTags list.

    • Array [
    • name string required

      The name of the tag type.

    • description string

      The description of the tag type.

    • icon string nullable

      The icon of the tag type.

    • ]
    • dependencies object[]

      A list of all the dependencies for features in features list.

    • Array [
    • feature string required

      The name of the child feature.

    • dependencies object[]required

      List of parent features for the child feature

    • Array [
    • feature string required

      The name of the feature we depend on.

    • enabled boolean

      Whether the parent feature should be enabled. When false variants are ignored. true by default.

    • variants string[]

      The list of variants the parent feature should resolve to. Leave empty when you only want to check the enabled status.

    • ]
    • ]
    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/import.html b/reference/api/unleash/import.html index 8d7f0a2561..c6e00987d2 100644 --- a/reference/api/unleash/import.html +++ b/reference/api/unleash/import.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Import state (deprecated)

    POST /api/admin/state/import
    deprecated

    This endpoint has been deprecated and may be removed in future versions of the API.

    Imports state into the system. Deprecated in favor of /api/admin/features-batch/import

    Request​

    Body

    required

    stateSchema

    • version integer required

      The version of the schema used to describe the state

    • features object[]

      A list of features

    • Array [
    • name string required

      Unique feature name

    • type string

      Type of the toggle e.g. experiment, kill-switch, release, operational, permission

    • description string nullable

      Detailed description of the feature

    • archived boolean

      true if the feature is archived

    • project string

      Name of the project the feature belongs to

    • enabled boolean

      true if the feature is enabled, otherwise false.

    • stale boolean

      true if the feature is stale based on the age and feature type, otherwise false.

    • favorite boolean

      true if the feature was favorited, otherwise false.

    • impressionData boolean

      true if the impression data collection is enabled for the feature, otherwise false.

    • createdAt date-time nullable

      The date the feature was created

    • archivedAt date-time nullable

      The date the feature was archived

    • lastSeenAt date-time nullable deprecated

      The date when metrics where last collected for the feature. This field is deprecated, use the one in featureEnvironmentSchema

    • environments object[]

      The list of environments where the feature can be used

    • Array [
    • name string required

      The name of the environment

    • featureName string

      The name of the feature

    • environment string

      The name of the environment

    • type string

      The type of the environment

    • enabled boolean required

      true if the feature is enabled for the environment, otherwise false.

    • sortOrder number

      The sort order of the feature environment in the feature environments list

    • variantCount number

      The number of defined variants

    • strategies object[]

      A list of activation strategies for the feature environment

    • Array [
    • id string

      A uuid for the feature strategy

    • name string required

      The name or type of strategy

    • title string nullable

      A descriptive title for the strategy

    • disabled boolean nullable

      A toggle to disable the strategy. defaults to false. Disabled strategies are not evaluated or returned to the SDKs

    • featureName string

      The name or feature the strategy is attached to

    • sortOrder number

      The order of the strategy in the list

    • segments number[]

      A list of segment ids attached to the strategy

    • constraints object[]

      A list of the constraints attached to the strategy. See https://docs.getunleash.io/reference/strategy-constraints

    • Array [
    • contextName string required

      The name of the context field that this constraint should apply to.

    • operator string required

      Possible values: [NOT_IN, IN, STR_ENDS_WITH, STR_STARTS_WITH, STR_CONTAINS, NUM_EQ, NUM_GT, NUM_GTE, NUM_LT, NUM_LTE, DATE_AFTER, DATE_BEFORE, SEMVER_EQ, SEMVER_GT, SEMVER_LT]

      The operator to use when evaluating this constraint. For more information about the various operators, refer to the strategy constraint operator documentation.

    • caseInsensitive boolean

      Default value: false

      Whether the operator should be case sensitive or not. Defaults to false (being case sensitive).

    • inverted boolean

      Default value: false

      Whether the result should be negated or not. If true, will turn a true result into a false result and vice versa.

    • values string[]

      The context values that should be used for constraint evaluation. Use this property instead of value for properties that accept multiple values.

    • value string

      The context value that should be used for constraint evaluation. Use this property instead of values for properties that only accept single values.

    • ]
    • variants object[]

      Strategy level variants

    • Array [
    • name string required

      The variant name. Must be unique for this feature toggle

    • weight integer required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is an integer between 0 and 1000. See the section on variant weights for more information

    • weightType string required

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000. Refer to the variant weight documentation.

    • stickiness string required

      The stickiness to use for distribution of this variant. Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • ]
    • parameters object

      A list of parameters for a strategy

    • property name* string
    • ]
    • variants object[]

      A list of variants for the feature environment

    • Array [
    • name string required

      The variants name. Is unique for this feature toggle

    • weight number required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is a number between 0 and 1000. See the section on variant weights for more information

    • weightType string

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000

    • stickiness string

      Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • overrides object[]

      Overrides assigning specific variants to specific users. The weighting system automatically assigns users to specific groups for you, but any overrides in this list will take precedence.

    • Array [
    • contextName string required

      The name of the context field used to determine overrides

    • values string[] required

      Which values that should be overriden

    • ]
    • ]
    • lastSeenAt date-time nullable

      The date when metrics where last collected for the feature environment

    • hasStrategies boolean

      Whether the feature has any strategies defined.

    • hasEnabledStrategies boolean

      Whether the feature has any enabled strategies defined.

    • ]
    • variants object[]deprecated

      The list of feature variants

    • Array [
    • name string required

      The variants name. Is unique for this feature toggle

    • weight number required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is a number between 0 and 1000. See the section on variant weights for more information

    • weightType string

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000

    • stickiness string

      Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • overrides object[]

      Overrides assigning specific variants to specific users. The weighting system automatically assigns users to specific groups for you, but any overrides in this list will take precedence.

    • Array [
    • contextName string required

      The name of the context field used to determine overrides

    • values string[] required

      Which values that should be overriden

    • ]
    • ]
    • strategies object[] deprecated

      This is a legacy field that will be deprecated

    • tags object[]nullable

      The list of feature tags

    • Array [
    • value string required

      Possible values: >= 2 characters and <= 50 characters

      The value of the tag

    • type string required

      Possible values: >= 2 characters and <= 50 characters

      Default value: simple

      The type of the tag

    • ]
    • children string[]

      The list of child feature names. This is an experimental field and may change.

    • dependencies object[]

      The list of parent dependencies. This is an experimental field and may change.

    • Array [
    • feature string required

      The name of the parent feature

    • enabled boolean

      Whether the parent feature is enabled or not

    • variants string[]

      The list of variants the parent feature should resolve to. Only valid when feature is enabled.

    • ]
    • ]
    • strategies object[]

      A list of strategies

    • Array [
    • title string nullable

      An optional title for the strategy

    • name string required

      The name (type) of the strategy

    • displayName string nullable required

      A human friendly name for the strategy

    • description string nullable required

      A short description of the strategy

    • editable boolean required

      Whether the strategy can be edited or not. Strategies bundled with Unleash cannot be edited.

    • deprecated boolean required
    • parameters object[]required

      A list of relevant parameters for each strategy

    • Array [
    • name string
    • type string
    • description string
    • required boolean
    • ]
    • ]
    • tags object[]

      A list of tags

    • Array [
    • value string required

      Possible values: >= 2 characters and <= 50 characters

      The value of the tag

    • type string required

      Possible values: >= 2 characters and <= 50 characters

      Default value: simple

      The type of the tag

    • ]
    • tagTypes object[]

      A list of tag types

    • Array [
    • name string required

      The name of the tag type.

    • description string

      The description of the tag type.

    • icon string nullable

      The icon of the tag type.

    • ]
    • featureTags object[]

      A list of tags applied to features

    • Array [
    • featureName string required

      The name of the feature this tag is applied to

    • tagType string

      The [type](https://docs.getunleash.io/reference/tags#tag-types tag types) of the tag

    • tagValue string required

      The value of the tag

    • type string deprecated

      The [type](https://docs.getunleash.io/reference/tags#tag-types tag types) of the tag. This property is deprecated and will be removed in a future version of Unleash. Superseded by the tagType property.

    • value string deprecated

      The value of the tag. This property is deprecated and will be removed in a future version of Unleash. Superseded by the tagValue property.

    • createdByUserId number nullable

      The id of the user who created this tag

    • ]
    • projects object[]

      A list of projects

    • Array [
    • id string required

      The id of this project

    • name string required

      The name of this project

    • description string nullable

      Additional information about the project

    • health number

      An indicator of the project's health on a scale from 0 to 100

    • featureCount number

      The number of features this project has

    • memberCount number

      The number of members this project has

    • createdAt date-time

      When this project was created.

    • updatedAt date-time nullable

      When this project was last updated.

    • favorite boolean

      true if the project was favorited, otherwise false.

    • mode string

      Possible values: [open, protected, private]

      The project's collaboration mode. Determines whether non-project members can submit change requests or not.

    • defaultStickiness string

      A default stickiness for the project affecting the default stickiness value for variants and Gradual Rollout strategy

    • ]
    • featureStrategies object[]

      A list of feature strategies as applied to features

    • Array [
    • id string

      A uuid for the feature strategy

    • name string required

      The name or type of strategy

    • title string nullable

      A descriptive title for the strategy

    • disabled boolean nullable

      A toggle to disable the strategy. defaults to false. Disabled strategies are not evaluated or returned to the SDKs

    • featureName string

      The name or feature the strategy is attached to

    • sortOrder number

      The order of the strategy in the list

    • segments number[]

      A list of segment ids attached to the strategy

    • constraints object[]

      A list of the constraints attached to the strategy. See https://docs.getunleash.io/reference/strategy-constraints

    • Array [
    • contextName string required

      The name of the context field that this constraint should apply to.

    • operator string required

      Possible values: [NOT_IN, IN, STR_ENDS_WITH, STR_STARTS_WITH, STR_CONTAINS, NUM_EQ, NUM_GT, NUM_GTE, NUM_LT, NUM_LTE, DATE_AFTER, DATE_BEFORE, SEMVER_EQ, SEMVER_GT, SEMVER_LT]

      The operator to use when evaluating this constraint. For more information about the various operators, refer to the strategy constraint operator documentation.

    • caseInsensitive boolean

      Default value: false

      Whether the operator should be case sensitive or not. Defaults to false (being case sensitive).

    • inverted boolean

      Default value: false

      Whether the result should be negated or not. If true, will turn a true result into a false result and vice versa.

    • values string[]

      The context values that should be used for constraint evaluation. Use this property instead of value for properties that accept multiple values.

    • value string

      The context value that should be used for constraint evaluation. Use this property instead of values for properties that only accept single values.

    • ]
    • variants object[]

      Strategy level variants

    • Array [
    • name string required

      The variant name. Must be unique for this feature toggle

    • weight integer required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is an integer between 0 and 1000. See the section on variant weights for more information

    • weightType string required

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000. Refer to the variant weight documentation.

    • stickiness string required

      The stickiness to use for distribution of this variant. Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • ]
    • parameters object

      A list of parameters for a strategy

    • property name* string
    • ]
    • featureEnvironments object[]

      A list of feature environment configurations

    • Array [
    • name string required

      The name of the environment

    • featureName string

      The name of the feature

    • environment string

      The name of the environment

    • type string

      The type of the environment

    • enabled boolean required

      true if the feature is enabled for the environment, otherwise false.

    • sortOrder number

      The sort order of the feature environment in the feature environments list

    • variantCount number

      The number of defined variants

    • strategies object[]

      A list of activation strategies for the feature environment

    • Array [
    • id string

      A uuid for the feature strategy

    • name string required

      The name or type of strategy

    • title string nullable

      A descriptive title for the strategy

    • disabled boolean nullable

      A toggle to disable the strategy. defaults to false. Disabled strategies are not evaluated or returned to the SDKs

    • featureName string

      The name or feature the strategy is attached to

    • sortOrder number

      The order of the strategy in the list

    • segments number[]

      A list of segment ids attached to the strategy

    • constraints object[]

      A list of the constraints attached to the strategy. See https://docs.getunleash.io/reference/strategy-constraints

    • Array [
    • contextName string required

      The name of the context field that this constraint should apply to.

    • operator string required

      Possible values: [NOT_IN, IN, STR_ENDS_WITH, STR_STARTS_WITH, STR_CONTAINS, NUM_EQ, NUM_GT, NUM_GTE, NUM_LT, NUM_LTE, DATE_AFTER, DATE_BEFORE, SEMVER_EQ, SEMVER_GT, SEMVER_LT]

      The operator to use when evaluating this constraint. For more information about the various operators, refer to the strategy constraint operator documentation.

    • caseInsensitive boolean

      Default value: false

      Whether the operator should be case sensitive or not. Defaults to false (being case sensitive).

    • inverted boolean

      Default value: false

      Whether the result should be negated or not. If true, will turn a true result into a false result and vice versa.

    • values string[]

      The context values that should be used for constraint evaluation. Use this property instead of value for properties that accept multiple values.

    • value string

      The context value that should be used for constraint evaluation. Use this property instead of values for properties that only accept single values.

    • ]
    • variants object[]

      Strategy level variants

    • Array [
    • name string required

      The variant name. Must be unique for this feature toggle

    • weight integer required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is an integer between 0 and 1000. See the section on variant weights for more information

    • weightType string required

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000. Refer to the variant weight documentation.

    • stickiness string required

      The stickiness to use for distribution of this variant. Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • ]
    • parameters object

      A list of parameters for a strategy

    • property name* string
    • ]
    • variants object[]

      A list of variants for the feature environment

    • Array [
    • name string required

      The variants name. Is unique for this feature toggle

    • weight number required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is a number between 0 and 1000. See the section on variant weights for more information

    • weightType string

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000

    • stickiness string

      Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • overrides object[]

      Overrides assigning specific variants to specific users. The weighting system automatically assigns users to specific groups for you, but any overrides in this list will take precedence.

    • Array [
    • contextName string required

      The name of the context field used to determine overrides

    • values string[] required

      Which values that should be overriden

    • ]
    • ]
    • lastSeenAt date-time nullable

      The date when metrics where last collected for the feature environment

    • hasStrategies boolean

      Whether the feature has any strategies defined.

    • hasEnabledStrategies boolean

      Whether the feature has any enabled strategies defined.

    • ]
    • environments object[]

      A list of environments

    • Array [
    • name string required

      The name of the environment

    • type string required
    • enabled boolean required

      true if the environment is enabled for the project, otherwise false.

    • protected boolean required

      true if the environment is protected, otherwise false. A protected environment can not be deleted.

    • sortOrder integer required

      Priority of the environment in a list of environments, the lower the value, the higher up in the list the environment will appear. Needs to be an integer

    • projectCount integer nullable

      The number of projects with this environment

    • apiTokenCount integer nullable

      The number of API tokens for the project environment

    • enabledToggleCount integer nullable

      The number of enabled toggles for the project environment

    • ]
    • segments object[]

      A list of segments

    • Array [
    • id number required

      The segment's id.

    • name string

      The name of the segment.

    • constraints object[]required

      List of constraints that determine which users are part of the segment

    • Array [
    • contextName string required

      The name of the context field that this constraint should apply to.

    • operator string required

      Possible values: [NOT_IN, IN, STR_ENDS_WITH, STR_STARTS_WITH, STR_CONTAINS, NUM_EQ, NUM_GT, NUM_GTE, NUM_LT, NUM_LTE, DATE_AFTER, DATE_BEFORE, SEMVER_EQ, SEMVER_GT, SEMVER_LT]

      The operator to use when evaluating this constraint. For more information about the various operators, refer to the strategy constraint operator documentation.

    • caseInsensitive boolean

      Default value: false

      Whether the operator should be case sensitive or not. Defaults to false (being case sensitive).

    • inverted boolean

      Default value: false

      Whether the result should be negated or not. If true, will turn a true result into a false result and vice versa.

    • values string[]

      The context values that should be used for constraint evaluation. Use this property instead of value for properties that accept multiple values.

    • value string

      The context value that should be used for constraint evaluation. Use this property instead of values for properties that only accept single values.

    • ]
    • description string nullable

      The description of the segment.

    • createdAt date-time

      The time the segment was created as a RFC 3339-conformant timestamp.

    • createdBy string

      Which user created this segment

    • project string nullable

      The project the segment relates to, if applicable.

    • ]
    • featureStrategySegments object[]

      A list of segment/strategy pairings

    • Array [
    • segmentId integer required

      The ID of the segment

    • featureStrategyId string required

      The ID of the strategy

    • ]
    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/instance-admin.html b/reference/api/unleash/instance-admin.html index 5ebb79c42f..6767ce89d4 100644 --- a/reference/api/unleash/instance-admin.html +++ b/reference/api/unleash/instance-admin.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Instance Admin

    Instance admin endpoints used to manage the Unleash instance itself.

    - + \ No newline at end of file diff --git a/reference/api/unleash/list-parent-options.html b/reference/api/unleash/list-parent-options.html index 9d15e892ce..ec7f753e14 100644 --- a/reference/api/unleash/list-parent-options.html +++ b/reference/api/unleash/list-parent-options.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    List parent options.

    GET /api/admin/projects/:projectId/features/:child/parents

    List available parents who have no transitive dependencies.

    Request​

    Path Parameters

    • projectId string required
    • child string required
    Responses

    parentFeatureOptionsSchema

    Schema
    • Array [
    • string
    • ]
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/list-tags.html b/reference/api/unleash/list-tags.html index d1dfb3b989..4c50fb02b9 100644 --- a/reference/api/unleash/list-tags.html +++ b/reference/api/unleash/list-tags.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Get all tags for a feature.

    GET /api/admin/features/:featureName/tags

    Retrieves all the tags for a feature name. If the feature does not exist it returns an empty list.

    Request​

    Path Parameters

    • featureName string required
    Responses

    tagsSchema

    Schema
    • version integer required

      The version of the schema used to model the tags.

    • tags object[]required

      A list of tags.

    • Array [
    • value string required

      Possible values: >= 2 characters and <= 50 characters

      The value of the tag

    • type string required

      Possible values: >= 2 characters and <= 50 characters

      Default value: simple

      The type of the tag

    • ]
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/login.html b/reference/api/unleash/login.html index 5c885a0c0e..3ff2df6861 100644 --- a/reference/api/unleash/login.html +++ b/reference/api/unleash/login.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Log in

    POST /auth/simple/login

    Logs in the user and creates an active session

    Request​

    Body

    required

    loginSchema

    • username string required

      The username trying to log in

    • password string required

      The password of the user trying to log in

    Responses

    userSchema

    Schema
    • id integer required

      The user id

    • isAPI boolean deprecated

      (Deprecated): Used internally to know which operations the user should be allowed to perform

    • name string nullable

      Name of the user

    • email string

      Email of the user

    • username string nullable

      A unique username for the user

    • imageUrl string

      URL used for the userprofile image

    • inviteLink string

      If the user is actively inviting other users, this is the link that can be shared with other users

    • loginAttempts integer

      How many unsuccessful attempts at logging in has the user made

    • emailSent boolean

      Is the welcome email sent to the user or not

    • rootRole integer

      Which root role this user is assigned

    • seenAt date-time nullable

      The last time this user logged in

    • createdAt date-time

      The user was created at this time

    • accountType string

      A user is either an actual User or a Service Account

    • permissions string[]

      Deprecated

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/maintenance.html b/reference/api/unleash/maintenance.html index d640beb59b..7af851583c 100644 --- a/reference/api/unleash/maintenance.html +++ b/reference/api/unleash/maintenance.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content
    - + \ No newline at end of file diff --git a/reference/api/unleash/mark-notifications-as-read.html b/reference/api/unleash/mark-notifications-as-read.html index 555f5f752f..c135648161 100644 --- a/reference/api/unleash/mark-notifications-as-read.html +++ b/reference/api/unleash/mark-notifications-as-read.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Mark notifications as read

    POST /api/admin/notifications/read

    Allow to select which notifications were read and saving a read date

    Request​

    Body

    required

    markNotificationsAsReadSchema

    • notifications integer[] required

      A list of IDs belonging to the notifications you want to mark as read.

    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/metrics.html b/reference/api/unleash/metrics.html index 79e63c1a96..d2f4df691e 100644 --- a/reference/api/unleash/metrics.html +++ b/reference/api/unleash/metrics.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Metrics

    Register, read, or delete metrics recorded by Unleash.

    - + \ No newline at end of file diff --git a/reference/api/unleash/notifications.html b/reference/api/unleash/notifications.html index faed69eca2..cf4626db9c 100644 --- a/reference/api/unleash/notifications.html +++ b/reference/api/unleash/notifications.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content
    - + \ No newline at end of file diff --git a/reference/api/unleash/operational.html b/reference/api/unleash/operational.html index 624e4dcd6a..07abc13b9f 100644 --- a/reference/api/unleash/operational.html +++ b/reference/api/unleash/operational.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content
    - + \ No newline at end of file diff --git a/reference/api/unleash/overwrite-environment-feature-variants.html b/reference/api/unleash/overwrite-environment-feature-variants.html index dc8b709917..6972b72922 100644 --- a/reference/api/unleash/overwrite-environment-feature-variants.html +++ b/reference/api/unleash/overwrite-environment-feature-variants.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Create (overwrite) variants for a feature in an environment

    PUT /api/admin/projects/:projectId/features/:featureName/environments/:environment/variants

    This overwrites the current variants for the feature toggle in the :featureName parameter for the :environment parameter.

    The backend will validate the input for the following invariants:

    • If there are variants, there needs to be at least one variant with weightType: variable
    • The sum of the weights of variants with weightType: fix must be strictly less than 1000 (< 1000)

    The backend will also distribute remaining weight up to 1000 after adding the variants with weightType: fix together amongst the variants of weightType: variable

    Request​

    Path Parameters

    • projectId string required
    • featureName string required
    • environment string required

    Body

    arrayrequired

    variantsSchema

    • Array [
    • name string required

      The variants name. Is unique for this feature toggle

    • weight number required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is a number between 0 and 1000. See the section on variant weights for more information

    • weightType string

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000

    • stickiness string

      Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • overrides object[]

      Overrides assigning specific variants to specific users. The weighting system automatically assigns users to specific groups for you, but any overrides in this list will take precedence.

    • Array [
    • contextName string required

      The name of the context field used to determine overrides

    • values string[] required

      Which values that should be overriden

    • ]
    • ]
    Responses

    featureVariantsSchema

    Schema
    • version integer required

      The version of the feature variants schema.

    • variants object[]required

      All variants defined for a specific feature toggle.

    • Array [
    • name string required

      The variants name. Is unique for this feature toggle

    • weight number required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is a number between 0 and 1000. See the section on variant weights for more information

    • weightType string

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000

    • stickiness string

      Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • overrides object[]

      Overrides assigning specific variants to specific users. The weighting system automatically assigns users to specific groups for you, but any overrides in this list will take precedence.

    • Array [
    • contextName string required

      The name of the context field used to determine overrides

    • values string[] required

      Which values that should be overriden

    • ]
    • ]
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/overwrite-feature-variants-on-environments.html b/reference/api/unleash/overwrite-feature-variants-on-environments.html index 54a94711c3..d686af9735 100644 --- a/reference/api/unleash/overwrite-feature-variants-on-environments.html +++ b/reference/api/unleash/overwrite-feature-variants-on-environments.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Create (overwrite) variants for a feature toggle in multiple environments

    PUT /api/admin/projects/:projectId/features/:featureName/variants-batch

    This overwrites the current variants for the feature toggle in the :featureName parameter for the :environment parameter.

    Request​

    Path Parameters

    • projectId string required
    • featureName string required

    Body

    required

    pushVariantsSchema

    • variants object[]

      The variants to write to the provided environments

    • Array [
    • name string required

      The variants name. Is unique for this feature toggle

    • weight number required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is a number between 0 and 1000. See the section on variant weights for more information

    • weightType string

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000

    • stickiness string

      Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • overrides object[]

      Overrides assigning specific variants to specific users. The weighting system automatically assigns users to specific groups for you, but any overrides in this list will take precedence.

    • Array [
    • contextName string required

      The name of the context field used to determine overrides

    • values string[] required

      Which values that should be overriden

    • ]
    • ]
    • environments string[]

      The enviromnents to write the provided variants to

    Responses

    featureVariantsSchema

    Schema
    • version integer required

      The version of the feature variants schema.

    • variants object[]required

      All variants defined for a specific feature toggle.

    • Array [
    • name string required

      The variants name. Is unique for this feature toggle

    • weight number required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is a number between 0 and 1000. See the section on variant weights for more information

    • weightType string

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000

    • stickiness string

      Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • overrides object[]

      Overrides assigning specific variants to specific users. The weighting system automatically assigns users to specific groups for you, but any overrides in this list will take precedence.

    • Array [
    • contextName string required

      The name of the context field used to determine overrides

    • values string[] required

      Which values that should be overriden

    • ]
    • ]
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/overwrite-feature-variants.html b/reference/api/unleash/overwrite-feature-variants.html index de53b3c6ae..c76fed3ace 100644 --- a/reference/api/unleash/overwrite-feature-variants.html +++ b/reference/api/unleash/overwrite-feature-variants.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Create (overwrite) variants for a feature toggle in all environments

    PUT /api/admin/projects/:projectId/features/:featureName/variants

    This overwrites the current variants for the feature specified in the :featureName parameter in all environments.

    The backend will validate the input for the following invariants

    • If there are variants, there needs to be at least one variant with weightType: variable
    • The sum of the weights of variants with weightType: fix must be strictly less than 1000 (< 1000)

    The backend will also distribute remaining weight up to 1000 after adding the variants with weightType: fix together amongst the variants of weightType: variable

    Request​

    Path Parameters

    • projectId string required
    • featureName string required

    Body

    arrayrequired

    variantsSchema

    • Array [
    • name string required

      The variants name. Is unique for this feature toggle

    • weight number required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is a number between 0 and 1000. See the section on variant weights for more information

    • weightType string

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000

    • stickiness string

      Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • overrides object[]

      Overrides assigning specific variants to specific users. The weighting system automatically assigns users to specific groups for you, but any overrides in this list will take precedence.

    • Array [
    • contextName string required

      The name of the context field used to determine overrides

    • values string[] required

      Which values that should be overriden

    • ]
    • ]
    Responses

    featureVariantsSchema

    Schema
    • version integer required

      The version of the feature variants schema.

    • variants object[]required

      All variants defined for a specific feature toggle.

    • Array [
    • name string required

      The variants name. Is unique for this feature toggle

    • weight number required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is a number between 0 and 1000. See the section on variant weights for more information

    • weightType string

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000

    • stickiness string

      Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • overrides object[]

      Overrides assigning specific variants to specific users. The weighting system automatically assigns users to specific groups for you, but any overrides in this list will take precedence.

    • Array [
    • contextName string required

      The name of the context field used to determine overrides

    • values string[] required

      Which values that should be overriden

    • ]
    • ]
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/patch-environments-feature-variants.html b/reference/api/unleash/patch-environments-feature-variants.html index e0e73df0b9..f2e14368e3 100644 --- a/reference/api/unleash/patch-environments-feature-variants.html +++ b/reference/api/unleash/patch-environments-feature-variants.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Patch a feature's variants in an environment

    PATCH /api/admin/projects/:projectId/features/:featureName/environments/:environment/variants

    Apply a list of patches to the features environments in the specified environment. The patch objects should conform to the JSON-patch format (RFC 6902).

    Request​

    Path Parameters

    • projectId string required
    • featureName string required
    • environment string required

    Body

    arrayrequired

    patchesSchema

    • Array [
    • path string required

      The path to the property to operate on

    • op string required

      Possible values: [add, remove, replace, copy, move]

      The kind of operation to perform

    • from string

      The target to move or copy from, if performing one of those operations

    • value

      The value to add or replace, if performing one of those operations

    • ]
    Responses

    featureVariantsSchema

    Schema
    • version integer required

      The version of the feature variants schema.

    • variants object[]required

      All variants defined for a specific feature toggle.

    • Array [
    • name string required

      The variants name. Is unique for this feature toggle

    • weight number required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is a number between 0 and 1000. See the section on variant weights for more information

    • weightType string

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000

    • stickiness string

      Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • overrides object[]

      Overrides assigning specific variants to specific users. The weighting system automatically assigns users to specific groups for you, but any overrides in this list will take precedence.

    • Array [
    • contextName string required

      The name of the context field used to determine overrides

    • values string[] required

      Which values that should be overriden

    • ]
    • ]
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/patch-feature-strategy.html b/reference/api/unleash/patch-feature-strategy.html index e853b460fd..51356d2d67 100644 --- a/reference/api/unleash/patch-feature-strategy.html +++ b/reference/api/unleash/patch-feature-strategy.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Change specific properties of a strategy

    PATCH /api/admin/projects/:projectId/features/:featureName/environments/:environment/strategies/:strategyId

    Change specific properties of a strategy configuration in a feature toggle.

    Request​

    Path Parameters

    • projectId string required
    • featureName string required
    • environment string required
    • strategyId string required

    Body

    arrayrequired

    patchesSchema

    • Array [
    • path string required

      The path to the property to operate on

    • op string required

      Possible values: [add, remove, replace, copy, move]

      The kind of operation to perform

    • from string

      The target to move or copy from, if performing one of those operations

    • value

      The value to add or replace, if performing one of those operations

    • ]
    Responses

    featureStrategySchema

    Schema
    • id string

      A uuid for the feature strategy

    • name string required

      The name or type of strategy

    • title string nullable

      A descriptive title for the strategy

    • disabled boolean nullable

      A toggle to disable the strategy. defaults to false. Disabled strategies are not evaluated or returned to the SDKs

    • featureName string

      The name or feature the strategy is attached to

    • sortOrder number

      The order of the strategy in the list

    • segments number[]

      A list of segment ids attached to the strategy

    • constraints object[]

      A list of the constraints attached to the strategy. See https://docs.getunleash.io/reference/strategy-constraints

    • Array [
    • contextName string required

      The name of the context field that this constraint should apply to.

    • operator string required

      Possible values: [NOT_IN, IN, STR_ENDS_WITH, STR_STARTS_WITH, STR_CONTAINS, NUM_EQ, NUM_GT, NUM_GTE, NUM_LT, NUM_LTE, DATE_AFTER, DATE_BEFORE, SEMVER_EQ, SEMVER_GT, SEMVER_LT]

      The operator to use when evaluating this constraint. For more information about the various operators, refer to the strategy constraint operator documentation.

    • caseInsensitive boolean

      Default value: false

      Whether the operator should be case sensitive or not. Defaults to false (being case sensitive).

    • inverted boolean

      Default value: false

      Whether the result should be negated or not. If true, will turn a true result into a false result and vice versa.

    • values string[]

      The context values that should be used for constraint evaluation. Use this property instead of value for properties that accept multiple values.

    • value string

      The context value that should be used for constraint evaluation. Use this property instead of values for properties that only accept single values.

    • ]
    • variants object[]

      Strategy level variants

    • Array [
    • name string required

      The variant name. Must be unique for this feature toggle

    • weight integer required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is an integer between 0 and 1000. See the section on variant weights for more information

    • weightType string required

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000. Refer to the variant weight documentation.

    • stickiness string required

      The stickiness to use for distribution of this variant. Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • ]
    • parameters object

      A list of parameters for a strategy

    • property name* string
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/patch-feature-variants.html b/reference/api/unleash/patch-feature-variants.html index be736a597a..8c3a2a2341 100644 --- a/reference/api/unleash/patch-feature-variants.html +++ b/reference/api/unleash/patch-feature-variants.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Apply a patch to a feature's variants (in all environments).

    PATCH /api/admin/projects/:projectId/features/:featureName/variants

    Apply a list of patches patch to the specified feature's variants. The patch objects should conform to the JSON-patch format (RFC 6902).

    ⚠️ Warning: This method is not atomic. If something fails in the middle of applying the patch, you can be left with a half-applied patch. We recommend that you instead patch variants on a per-environment basis, which is an atomic operation.

    Request​

    Path Parameters

    • projectId string required
    • featureName string required

    Body

    arrayrequired

    patchesSchema

    • Array [
    • path string required

      The path to the property to operate on

    • op string required

      Possible values: [add, remove, replace, copy, move]

      The kind of operation to perform

    • from string

      The target to move or copy from, if performing one of those operations

    • value

      The value to add or replace, if performing one of those operations

    • ]
    Responses

    featureVariantsSchema

    Schema
    • version integer required

      The version of the feature variants schema.

    • variants object[]required

      All variants defined for a specific feature toggle.

    • Array [
    • name string required

      The variants name. Is unique for this feature toggle

    • weight number required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is a number between 0 and 1000. See the section on variant weights for more information

    • weightType string

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000

    • stickiness string

      Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • overrides object[]

      Overrides assigning specific variants to specific users. The weighting system automatically assigns users to specific groups for you, but any overrides in this list will take precedence.

    • Array [
    • contextName string required

      The name of the context field used to determine overrides

    • values string[] required

      Which values that should be overriden

    • ]
    • ]
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/patch-feature.html b/reference/api/unleash/patch-feature.html index 0d1c0ebdd8..07cb9e6db6 100644 --- a/reference/api/unleash/patch-feature.html +++ b/reference/api/unleash/patch-feature.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Modify a feature toggle

    PATCH /api/admin/projects/:projectId/features/:featureName

    Change specific properties of a feature toggle.

    Request​

    Path Parameters

    • projectId string required
    • featureName string required

    Body

    arrayrequired

    patchesSchema

    • Array [
    • path string required

      The path to the property to operate on

    • op string required

      Possible values: [add, remove, replace, copy, move]

      The kind of operation to perform

    • from string

      The target to move or copy from, if performing one of those operations

    • value

      The value to add or replace, if performing one of those operations

    • ]
    Responses

    featureSchema

    Schema
    • name string required

      Unique feature name

    • type string

      Type of the toggle e.g. experiment, kill-switch, release, operational, permission

    • description string nullable

      Detailed description of the feature

    • archived boolean

      true if the feature is archived

    • project string

      Name of the project the feature belongs to

    • enabled boolean

      true if the feature is enabled, otherwise false.

    • stale boolean

      true if the feature is stale based on the age and feature type, otherwise false.

    • favorite boolean

      true if the feature was favorited, otherwise false.

    • impressionData boolean

      true if the impression data collection is enabled for the feature, otherwise false.

    • createdAt date-time nullable

      The date the feature was created

    • archivedAt date-time nullable

      The date the feature was archived

    • lastSeenAt date-time nullable deprecated

      The date when metrics where last collected for the feature. This field is deprecated, use the one in featureEnvironmentSchema

    • environments object[]

      The list of environments where the feature can be used

    • Array [
    • name string required

      The name of the environment

    • featureName string

      The name of the feature

    • environment string

      The name of the environment

    • type string

      The type of the environment

    • enabled boolean required

      true if the feature is enabled for the environment, otherwise false.

    • sortOrder number

      The sort order of the feature environment in the feature environments list

    • variantCount number

      The number of defined variants

    • strategies object[]

      A list of activation strategies for the feature environment

    • Array [
    • id string

      A uuid for the feature strategy

    • name string required

      The name or type of strategy

    • title string nullable

      A descriptive title for the strategy

    • disabled boolean nullable

      A toggle to disable the strategy. defaults to false. Disabled strategies are not evaluated or returned to the SDKs

    • featureName string

      The name or feature the strategy is attached to

    • sortOrder number

      The order of the strategy in the list

    • segments number[]

      A list of segment ids attached to the strategy

    • constraints object[]

      A list of the constraints attached to the strategy. See https://docs.getunleash.io/reference/strategy-constraints

    • Array [
    • contextName string required

      The name of the context field that this constraint should apply to.

    • operator string required

      Possible values: [NOT_IN, IN, STR_ENDS_WITH, STR_STARTS_WITH, STR_CONTAINS, NUM_EQ, NUM_GT, NUM_GTE, NUM_LT, NUM_LTE, DATE_AFTER, DATE_BEFORE, SEMVER_EQ, SEMVER_GT, SEMVER_LT]

      The operator to use when evaluating this constraint. For more information about the various operators, refer to the strategy constraint operator documentation.

    • caseInsensitive boolean

      Default value: false

      Whether the operator should be case sensitive or not. Defaults to false (being case sensitive).

    • inverted boolean

      Default value: false

      Whether the result should be negated or not. If true, will turn a true result into a false result and vice versa.

    • values string[]

      The context values that should be used for constraint evaluation. Use this property instead of value for properties that accept multiple values.

    • value string

      The context value that should be used for constraint evaluation. Use this property instead of values for properties that only accept single values.

    • ]
    • variants object[]

      Strategy level variants

    • Array [
    • name string required

      The variant name. Must be unique for this feature toggle

    • weight integer required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is an integer between 0 and 1000. See the section on variant weights for more information

    • weightType string required

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000. Refer to the variant weight documentation.

    • stickiness string required

      The stickiness to use for distribution of this variant. Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • ]
    • parameters object

      A list of parameters for a strategy

    • property name* string
    • ]
    • variants object[]

      A list of variants for the feature environment

    • Array [
    • name string required

      The variants name. Is unique for this feature toggle

    • weight number required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is a number between 0 and 1000. See the section on variant weights for more information

    • weightType string

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000

    • stickiness string

      Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • overrides object[]

      Overrides assigning specific variants to specific users. The weighting system automatically assigns users to specific groups for you, but any overrides in this list will take precedence.

    • Array [
    • contextName string required

      The name of the context field used to determine overrides

    • values string[] required

      Which values that should be overriden

    • ]
    • ]
    • lastSeenAt date-time nullable

      The date when metrics where last collected for the feature environment

    • hasStrategies boolean

      Whether the feature has any strategies defined.

    • hasEnabledStrategies boolean

      Whether the feature has any enabled strategies defined.

    • ]
    • variants object[]deprecated

      The list of feature variants

    • Array [
    • name string required

      The variants name. Is unique for this feature toggle

    • weight number required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is a number between 0 and 1000. See the section on variant weights for more information

    • weightType string

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000

    • stickiness string

      Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • overrides object[]

      Overrides assigning specific variants to specific users. The weighting system automatically assigns users to specific groups for you, but any overrides in this list will take precedence.

    • Array [
    • contextName string required

      The name of the context field used to determine overrides

    • values string[] required

      Which values that should be overriden

    • ]
    • ]
    • strategies object[] deprecated

      This is a legacy field that will be deprecated

    • tags object[]nullable

      The list of feature tags

    • Array [
    • value string required

      Possible values: >= 2 characters and <= 50 characters

      The value of the tag

    • type string required

      Possible values: >= 2 characters and <= 50 characters

      Default value: simple

      The type of the tag

    • ]
    • children string[]

      The list of child feature names. This is an experimental field and may change.

    • dependencies object[]

      The list of parent dependencies. This is an experimental field and may change.

    • Array [
    • feature string required

      The name of the parent feature

    • enabled boolean

      Whether the parent feature is enabled or not

    • variants string[]

      The list of variants the parent feature should resolve to. Only valid when feature is enabled.

    • ]
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/personal-access-tokens.html b/reference/api/unleash/personal-access-tokens.html index d56efe1a0c..456a0af0d1 100644 --- a/reference/api/unleash/personal-access-tokens.html +++ b/reference/api/unleash/personal-access-tokens.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Personal access tokens

    Create, update, and delete Personal access tokens.

    - + \ No newline at end of file diff --git a/reference/api/unleash/playground.html b/reference/api/unleash/playground.html index 1077990160..403ffd38ff 100644 --- a/reference/api/unleash/playground.html +++ b/reference/api/unleash/playground.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Playground

    Evaluate an Unleash context against your feature toggles.

    - + \ No newline at end of file diff --git a/reference/api/unleash/projects.html b/reference/api/unleash/projects.html index d68c136df4..902695210d 100644 --- a/reference/api/unleash/projects.html +++ b/reference/api/unleash/projects.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Projects

    Create, update, and delete Unleash projects.

    - + \ No newline at end of file diff --git a/reference/api/unleash/provide-feedback.html b/reference/api/unleash/provide-feedback.html index 2757396943..e5c852ed1e 100644 --- a/reference/api/unleash/provide-feedback.html +++ b/reference/api/unleash/provide-feedback.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Submit user feedback

    POST /feedback

    Allows users to submit feedback.

    Request​

    Body

    required

    provideFeedbackSchema

    • category string required

      The category of the feedback.

    • userType string nullable

      The type of user providing the feedback.

    • difficultyScore number nullable

      A score indicating the difficulty experienced by the user.

    • positive string nullable

      This field is for users to mention what they liked.

    • areasForImprovement string nullable

      Details aspects of the service or product that could benefit from enhancements or modifications. Aids in pinpointing areas needing attention for improvement.

    Responses

    feedbackSchema

    Schema
    • id number required

      The unique identifier of the feedback.

    • createdAt date-time required

      The date and time when the feedback was provided.

    • category string required

      The category of the feedback.

    • userType string nullable required

      The type of user providing the feedback.

    • difficultyScore number nullable required

      A score indicating the difficulty experienced by the user.

    • positive string nullable required

      This field is for users to mention what they liked.

    • areasForImprovement string nullable required

      Details aspects of the service or product that could benefit from enhancements or modifications. Aids in pinpointing areas needing attention for improvement.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/public-signup-tokens.html b/reference/api/unleash/public-signup-tokens.html index f131384666..b4d22d01d1 100644 --- a/reference/api/unleash/public-signup-tokens.html +++ b/reference/api/unleash/public-signup-tokens.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Public signup tokens

    Create, update, and delete Unleash Public Signup tokens.

    - + \ No newline at end of file diff --git a/reference/api/unleash/reactivate-strategy.html b/reference/api/unleash/reactivate-strategy.html index 032957bbbf..a980e476bf 100644 --- a/reference/api/unleash/reactivate-strategy.html +++ b/reference/api/unleash/reactivate-strategy.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Reactivate a strategy

    POST /api/admin/strategies/:strategyName/reactivate

    Marks the specified strategy as not deprecated. If the strategy wasn't already deprecated, nothing changes.

    Request​

    Path Parameters

    • strategyName string required
    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/read-license.html b/reference/api/unleash/read-license.html index 4d7a353541..6b27b79eee 100644 --- a/reference/api/unleash/read-license.html +++ b/reference/api/unleash/read-license.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Reads the Unleash license.

    GET /api/admin/license

    Reads the Unleash license. Only available for self-hosted Enterprise customers.

    Request​

    Responses

    licenseReadSchema

    Schema
    • token string required

      The actual license token.

    • customer string

      Name of the customer that owns the license. This is the name of the company that purchased the license.

    • plan string

      Name of plan that the license is for.

    • seats number

      Number of seats in the license.

    • expireAt date-time

      Date when the license expires.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/register-client-application.html b/reference/api/unleash/register-client-application.html index a559a29ab1..60c29021e0 100644 --- a/reference/api/unleash/register-client-application.html +++ b/reference/api/unleash/register-client-application.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Register a client SDK

    POST /api/client/register

    Register a client SDK with Unleash. SDKs call this endpoint on startup to tell Unleash about their existence. Used to track custom strategies in use as well as SDK versions.

    Request​

    Body

    required

    clientApplicationSchema

    • appName string required

      An identifier for the app that uses the sdk, should be static across SDK restarts

    • instanceId string

      A unique identifier identifying the instance of the application running the SDK. Often changes based on execution environment. For instance: two pods in Kubernetes will have two different instanceIds

    • sdkVersion string

      An SDK version identifier. Usually formatted as "unleash-client-:"

    • environment string deprecated

      The SDK's configured 'environment' property. Deprecated. This property does not control which Unleash environment the SDK gets toggles for. To control Unleash environments, use the SDKs API key.

    • interval number required

      How often (in seconds) does the client refresh its toggles

    • started objectrequired

      Either an RFC-3339 timestamp or a unix timestamp in seconds

      oneOf
    • string date-time
    • strategies string[] required

      Which strategies the SDKs runtime knows about

    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/register-client-metrics.html b/reference/api/unleash/register-client-metrics.html index 0c61f812d8..bd7e4bb761 100644 --- a/reference/api/unleash/register-client-metrics.html +++ b/reference/api/unleash/register-client-metrics.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Register client usage metrics

    POST /api/client/metrics

    Registers usage metrics. Stores information about how many times each toggle was evaluated to enabled and disabled within a time frame. If provided, this operation will also store data on how many times each feature toggle's variants were displayed to the end user.

    Request​

    Body

    required

    clientMetricsSchema

    • appName string required

      The name of the application that is evaluating toggles

    • instanceId string

      A (somewhat) unique identifier for the application

    • environment string

      Which environment the application is running in

    • bucket objectrequired

      Holds all metrics gathered over a window of time. Typically 1 hour wide

    • start objectrequired

      The start of the time window these metrics are valid for. The window is usually 1 hour wide

      oneOf
    • string date-time

      An RFC-3339-compliant timestamp.

    • stop objectrequired

      The end of the time window these metrics are valid for. The window is 1 hour wide

      oneOf
    • string date-time

      An RFC-3339-compliant timestamp.

    • toggles objectrequired

      an object containing feature names with yes/no plus variant usage

    • property name* object
    • yes number

      How many times the toggle evaluated to true

    • no integer

      How many times the toggle evaluated to false

    • variants object

      An object describing how many times each variant was returned. Variant names are used as properties, and the number of times they were exposed is the corresponding value (i.e. { [variantName]: number }).

    • property name* integer
    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/register-frontend-client.html b/reference/api/unleash/register-frontend-client.html index a4c2aceaa6..b2e18341e6 100644 --- a/reference/api/unleash/register-frontend-client.html +++ b/reference/api/unleash/register-frontend-client.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Register a client SDK

    POST /api/frontend/client/register

    This is for future use. Currently Frontend client registration is not supported. Returning 200 for clients that expect this status code. If the Frontend API is disabled 404 is returned.

    Request​

    Body

    required

    proxyClientSchema

    • appName string required

      Name of the application using Unleash

    • instanceId string

      Instance id for this application (typically hostname, podId or similar)

    • sdkVersion string

      Optional field that describes the sdk version (name:version)

    • environment string deprecated

      deprecated

    • interval number required

      At which interval, in milliseconds, will this client be expected to send metrics

    • started objectrequired

      When this client started. Should be reported as ISO8601 time.

      oneOf
    • string date-time
    • strategies string[] required

      List of strategies implemented by this application

    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/register-frontend-metrics.html b/reference/api/unleash/register-frontend-metrics.html index 694da215e5..f1720e5530 100644 --- a/reference/api/unleash/register-frontend-metrics.html +++ b/reference/api/unleash/register-frontend-metrics.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Register client usage metrics

    POST /api/frontend/client/metrics

    Registers usage metrics. Stores information about how many times each toggle was evaluated to enabled and disabled within a time frame. If provided, this operation will also store data on how many times each feature toggle's variants were displayed to the end user. If the Frontend API is disabled 404 is returned.

    Request​

    Body

    required

    clientMetricsSchema

    • appName string required

      The name of the application that is evaluating toggles

    • instanceId string

      A (somewhat) unique identifier for the application

    • environment string

      Which environment the application is running in

    • bucket objectrequired

      Holds all metrics gathered over a window of time. Typically 1 hour wide

    • start objectrequired

      The start of the time window these metrics are valid for. The window is usually 1 hour wide

      oneOf
    • string date-time

      An RFC-3339-compliant timestamp.

    • stop objectrequired

      The end of the time window these metrics are valid for. The window is 1 hour wide

      oneOf
    • string date-time

      An RFC-3339-compliant timestamp.

    • toggles objectrequired

      an object containing feature names with yes/no plus variant usage

    • property name* object
    • yes number

      How many times the toggle evaluated to true

    • no integer

      How many times the toggle evaluated to false

    • variants object

      An object describing how many times each variant was returned. Variant names are used as properties, and the number of times they were exposed is the corresponding value (i.e. { [variantName]: number }).

    • property name* integer
    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/remove-environment-from-project.html b/reference/api/unleash/remove-environment-from-project.html index 2d706f45df..bf694f4e76 100644 --- a/reference/api/unleash/remove-environment-from-project.html +++ b/reference/api/unleash/remove-environment-from-project.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Remove an environment from a project.

    DELETE /api/admin/projects/:projectId/environments/:environment

    This endpoint removes the specified environment from the project.

    Request​

    Path Parameters

    • projectId string required
    • environment string required
    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/remove-environment.html b/reference/api/unleash/remove-environment.html index 80cf09a189..d6a6215103 100644 --- a/reference/api/unleash/remove-environment.html +++ b/reference/api/unleash/remove-environment.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Deletes an environment by name

    DELETE /api/admin/environments/:name

    Given an existing environment by name, this endpoint will attempt to delete it

    Request​

    Path Parameters

    • name string required
    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/remove-favorite-feature.html b/reference/api/unleash/remove-favorite-feature.html index d6d31f8b0b..d5b7379479 100644 --- a/reference/api/unleash/remove-favorite-feature.html +++ b/reference/api/unleash/remove-favorite-feature.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Remove feature from favorites

    DELETE /api/admin/projects/:projectId/features/:featureName/favorites

    This endpoint removes the feature in the url from favorites

    Request​

    Path Parameters

    • projectId string required
    • featureName string required
    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/remove-favorite-project.html b/reference/api/unleash/remove-favorite-project.html index e84394566d..963efdaa77 100644 --- a/reference/api/unleash/remove-favorite-project.html +++ b/reference/api/unleash/remove-favorite-project.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Remove project from favorites

    DELETE /api/admin/projects/:projectId/favorites

    This endpoint removes the project in the url from favorites

    Request​

    Path Parameters

    • projectId string required
    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/remove-group-access.html b/reference/api/unleash/remove-group-access.html index 1b0055b676..81add05d9f 100644 --- a/reference/api/unleash/remove-group-access.html +++ b/reference/api/unleash/remove-group-access.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Remove project access for a group

    DELETE /api/admin/projects/:projectId/groups/:groupId/roles

    Removes project access for a group by removing all of its roles for the project.

    Request​

    Path Parameters

    • projectId string required
    • groupId string required
    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/remove-role-for-user.html b/reference/api/unleash/remove-role-for-user.html index b1529d5f37..1f100b255f 100644 --- a/reference/api/unleash/remove-role-for-user.html +++ b/reference/api/unleash/remove-role-for-user.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Removes role from user

    DELETE /api/admin/projects/:projectId/users/:userId/roles/:roleId
    deprecated

    This endpoint has been deprecated and may be removed in future versions of the API.

    Remove the specified project role from the specified user. This endpoint is deprecated. Use /:projectId/users/:userId/roles instead.

    Request​

    Path Parameters

    • projectId string required
    • userId string required
    • roleId string required
    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/remove-role-from-group.html b/reference/api/unleash/remove-role-from-group.html index 5c4c5eb508..3214740a20 100644 --- a/reference/api/unleash/remove-role-from-group.html +++ b/reference/api/unleash/remove-role-from-group.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Remove project group role

    DELETE /api/admin/projects/:projectId/groups/:groupId/roles/:roleId
    deprecated

    This endpoint has been deprecated and may be removed in future versions of the API.

    Removes a project role from a group. This endpoint is deprecated. Use /:projectId/groups/:groupId/roles instead.

    Request​

    Path Parameters

    • projectId string required
    • groupId string required
    • roleId string required
    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/remove-segment.html b/reference/api/unleash/remove-segment.html index 1cadc25765..9b12df19eb 100644 --- a/reference/api/unleash/remove-segment.html +++ b/reference/api/unleash/remove-segment.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Deletes a segment by id

    DELETE /api/admin/segments/:id

    Deletes a segment by its id, if not found returns a 409 error

    Request​

    Path Parameters

    • id string required
    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/remove-strategy.html b/reference/api/unleash/remove-strategy.html index 62a5a39847..fa7aa1d8e2 100644 --- a/reference/api/unleash/remove-strategy.html +++ b/reference/api/unleash/remove-strategy.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Delete a strategy

    DELETE /api/admin/strategies/:name

    Deletes the specified strategy definition

    Request​

    Path Parameters

    • name string required
    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/remove-tag.html b/reference/api/unleash/remove-tag.html index 7d58a8c928..ab801354ec 100644 --- a/reference/api/unleash/remove-tag.html +++ b/reference/api/unleash/remove-tag.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Removes a tag from a feature.

    DELETE /api/admin/features/:featureName/tags/:type/:value

    Removes a tag from a feature. If the feature exists but the tag does not, it returns a successful response.

    Request​

    Path Parameters

    • featureName string required
    • type string required
    • value string required
    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/remove-user-access.html b/reference/api/unleash/remove-user-access.html index fd7eebd3fd..2205172cf6 100644 --- a/reference/api/unleash/remove-user-access.html +++ b/reference/api/unleash/remove-user-access.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Remove project access for a user

    DELETE /api/admin/projects/:projectId/users/:userId/roles

    Removes project access for a user by removing all of its roles for the project.

    Request​

    Path Parameters

    • projectId string required
    • userId string required
    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/reset-user-password.html b/reference/api/unleash/reset-user-password.html index d08edb1a2e..82207e9f27 100644 --- a/reference/api/unleash/reset-user-password.html +++ b/reference/api/unleash/reset-user-password.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Reset user password

    POST /api/admin/user-admin/reset-password

    Reset user password as an admin

    Request​

    Body

    required

    idSchema

    • id string required

      User email

    Responses

    resetPasswordSchema

    Schema
    • resetPasswordUrl uri required

      A URL pointing to a location where the user can reset their password

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/revive-feature.html b/reference/api/unleash/revive-feature.html index f927683d8a..a553c7abec 100644 --- a/reference/api/unleash/revive-feature.html +++ b/reference/api/unleash/revive-feature.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Revives a feature

    POST /api/admin/archive/revive/:featureName

    This endpoint revives the specified feature from archive.

    Request​

    Path Parameters

    • featureName string required
    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/revive-features.html b/reference/api/unleash/revive-features.html index aecb532813..d1b8564799 100644 --- a/reference/api/unleash/revive-features.html +++ b/reference/api/unleash/revive-features.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Revives a list of features

    POST /api/admin/projects/:projectId/revive

    This endpoint revives the specified features.

    Request​

    Path Parameters

    • projectId string required

    Body

    required

    batchFeaturesSchema

    • features string[] required

      List of feature toggle names

    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/search-events.html b/reference/api/unleash/search-events.html index 758b0f9478..f1fd06cbd7 100644 --- a/reference/api/unleash/search-events.html +++ b/reference/api/unleash/search-events.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Search for events

    POST /api/admin/events/search

    Allows searching for events matching the search criteria in the request body

    Request​

    Body

    required

    searchEventsSchema

    • type string

      Possible values: [application-created, feature-created, feature-deleted, feature-updated, feature-metadata-updated, feature-variants-updated, feature-environment-variants-updated, feature-project-change, feature-archived, feature-revived, feature-import, feature-tagged, feature-tag-import, feature-strategy-update, feature-strategy-add, feature-strategy-remove, feature-type-updated, strategy-order-changed, drop-feature-tags, feature-untagged, feature-stale-on, feature-stale-off, drop-features, feature-environment-enabled, feature-environment-disabled, strategy-created, strategy-deleted, strategy-deprecated, strategy-reactivated, strategy-updated, strategy-import, drop-strategies, context-field-created, context-field-updated, context-field-deleted, project-access-added, project-access-user-roles-updated, project-access-group-roles-updated, project-access-user-roles-deleted, project-access-group-roles-deleted, project-access-updated, project-created, project-updated, project-deleted, project-import, project-user-added, project-user-removed, project-user-role-changed, project-group-role-changed, project-group-added, project-group-removed, role-created, role-updated, role-deleted, drop-projects, tag-created, tag-deleted, tag-import, drop-tags, tag-type-created, tag-type-deleted, tag-type-updated, tag-type-import, drop-tag-types, addon-config-created, addon-config-updated, addon-config-deleted, db-pool-update, user-created, user-updated, user-deleted, drop-environments, environment-import, environment-created, environment-updated, environment-deleted, segment-created, segment-updated, segment-deleted, group-created, group-updated, group-deleted, group-user-added, group-user-removed, setting-created, setting-updated, setting-deleted, client-metrics, client-register, pat-created, pat-deleted, public-signup-token-created, public-signup-token-user-added, public-signup-token-updated, change-request-created, change-request-discarded, change-added, change-discarded, change-edited, change-request-rejected, change-request-approved, change-request-approval-added, change-request-cancelled, change-request-sent-to-review, scheduled-change-request-executed, change-request-applied, change-request-scheduled, change-request-scheduled-application-success, change-request-scheduled-application-failure, change-request-configuration-updated, api-token-created, api-token-updated, api-token-deleted, feature-favorited, feature-unfavorited, project-favorited, project-unfavorited, features-exported, features-imported, service-account-created, service-account-deleted, service-account-updated, feature-potentially-stale-on, feature-dependency-added, feature-dependency-removed, feature-dependencies-removed, banner-created, banner-updated, banner-deleted, project-environment-added, project-environment-removed, default-strategy-updated, segment-import, incoming-webhook-created, incoming-webhook-updated, incoming-webhook-deleted, incoming-webhook-token-created, incoming-webhook-token-updated, incoming-webhook-token-deleted]

      Find events by event type (case-sensitive).

    • project string

      Find events by project ID (case-sensitive).

    • feature string

      Find events by feature toggle name (case-sensitive).

    • query string

      Find events by a free-text search query. The query will be matched against the event type, the username or email that created the event (if any), and the event data payload (if any).

    • limit integer

      Possible values: >= 1 and <= 100

      Default value: 100

      The maximum amount of events to return in the search result

    • offset integer

      Which event id to start listing from

    Responses

    eventsSchema

    Schema
    • version integer required

      Possible values: >= 1, [1]

      The api version of this response. A natural increasing number. Only increases if format changes

    • events object[]required

      The list of events

    • Array [
    • id integer required

      Possible values: >= 1

      The ID of the event. An increasing natural number.

    • createdAt date-time required

      The time the event happened as a RFC 3339-conformant timestamp.

    • type string required

      Possible values: [application-created, feature-created, feature-deleted, feature-updated, feature-metadata-updated, feature-variants-updated, feature-environment-variants-updated, feature-project-change, feature-archived, feature-revived, feature-import, feature-tagged, feature-tag-import, feature-strategy-update, feature-strategy-add, feature-strategy-remove, feature-type-updated, strategy-order-changed, drop-feature-tags, feature-untagged, feature-stale-on, feature-stale-off, drop-features, feature-environment-enabled, feature-environment-disabled, strategy-created, strategy-deleted, strategy-deprecated, strategy-reactivated, strategy-updated, strategy-import, drop-strategies, context-field-created, context-field-updated, context-field-deleted, project-access-added, project-access-user-roles-updated, project-access-group-roles-updated, project-access-user-roles-deleted, project-access-group-roles-deleted, project-access-updated, project-created, project-updated, project-deleted, project-import, project-user-added, project-user-removed, project-user-role-changed, project-group-role-changed, project-group-added, project-group-removed, role-created, role-updated, role-deleted, drop-projects, tag-created, tag-deleted, tag-import, drop-tags, tag-type-created, tag-type-deleted, tag-type-updated, tag-type-import, drop-tag-types, addon-config-created, addon-config-updated, addon-config-deleted, db-pool-update, user-created, user-updated, user-deleted, drop-environments, environment-import, environment-created, environment-updated, environment-deleted, segment-created, segment-updated, segment-deleted, group-created, group-updated, group-deleted, group-user-added, group-user-removed, setting-created, setting-updated, setting-deleted, client-metrics, client-register, pat-created, pat-deleted, public-signup-token-created, public-signup-token-user-added, public-signup-token-updated, change-request-created, change-request-discarded, change-added, change-discarded, change-edited, change-request-rejected, change-request-approved, change-request-approval-added, change-request-cancelled, change-request-sent-to-review, scheduled-change-request-executed, change-request-applied, change-request-scheduled, change-request-scheduled-application-success, change-request-scheduled-application-failure, change-request-configuration-updated, api-token-created, api-token-updated, api-token-deleted, feature-favorited, feature-unfavorited, project-favorited, project-unfavorited, features-exported, features-imported, service-account-created, service-account-deleted, service-account-updated, feature-potentially-stale-on, feature-dependency-added, feature-dependency-removed, feature-dependencies-removed, banner-created, banner-updated, banner-deleted, project-environment-added, project-environment-removed, default-strategy-updated, segment-import, incoming-webhook-created, incoming-webhook-updated, incoming-webhook-deleted, incoming-webhook-token-created, incoming-webhook-token-updated, incoming-webhook-token-deleted]

      What type of event this is

    • createdBy string required

      Which user created this event

    • createdByUserId number nullable

      The is of the user that created this event

    • environment string nullable

      The feature toggle environment the event relates to, if applicable.

    • project string nullable

      The project the event relates to, if applicable.

    • featureName string nullable

      The name of the feature toggle the event relates to, if applicable.

    • data object nullable

      Extra associated data related to the event, such as feature toggle state, segment configuration, etc., if applicable.

    • preData object nullable

      Data relating to the previous state of the event's subject.

    • tags object[]nullable

      Any tags related to the event, if applicable.

    • Array [
    • value string required

      Possible values: >= 2 characters and <= 50 characters

      The value of the tag

    • type string required

      Possible values: >= 2 characters and <= 50 characters

      Default value: simple

      The type of the tag

    • ]
    • ]
    • totalEvents integer

      The total count of events

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/search-features.html b/reference/api/unleash/search-features.html index dd95cace96..9a5be7cd2f 100644 --- a/reference/api/unleash/search-features.html +++ b/reference/api/unleash/search-features.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Search and filter features

    GET /api/admin/search/features

    Search and filter by selected fields.

    Request​

    Query Parameters

    • query string

      The search query for the feature name or tag

    • project string

      Possible values: Value must match regular expression ^(IS|IS_NOT|IS_ANY_OF|IS_NONE_OF):(.*?)(,([a-zA-Z0-9_]+))*$

      Id of the project where search and filter is performed. The project id can be specified with an operator. The supported operators are IS, IS_NOT, IS_ANY_OF, IS_NONE_OF.

    • state string

      Possible values: Value must match regular expression ^(IS|IS_NOT|IS_ANY_OF|IS_NONE_OF):(.*?)(,([a-zA-Z0-9_]+))*$

      The state of the feature active/stale. The state can be specified with an operator. The supported operators are IS, IS_NOT, IS_ANY_OF, IS_NONE_OF.

    • type string[]

      The list of feature types to filter by

    • tag string

      Possible values: Value must match regular expression ^(INCLUDE|DO_NOT_INCLUDE|INCLUDE_ALL_OF|INCLUDE_ANY_OF|EXCLUDE_IF_ANY_OF|EXCLUDE_ALL):(?:\s*[^,:]+:[^,:]+\s*)(?:,\s*[^,:]+:[^,:]+\s*)*$

      The list of feature tags to filter by. Feature tag has to specify a type and a value joined with a colon.

    • segment string

      Possible values: Value must match regular expression ^(INCLUDE|DO_NOT_INCLUDE|INCLUDE_ALL_OF|INCLUDE_ANY_OF|EXCLUDE_IF_ANY_OF|EXCLUDE_ALL):(.*?)(,([a-zA-Z0-9_]+))*$

      The list of segments with operators to filter by. The segment valid operators are INCLUDE, DO_NOT_INCLUDE, INCLUDE_ALL_OF, INCLUDE_ANY_OF, EXCLUDE_IF_ANY_OF, EXCLUDE_ALL.

    • status string[]

      The list of feature environment status to filter by. Feature environment has to specify a name and a status joined with a colon.

    • offset string

      The number of features to skip when returning a page. By default it is set to 0.

    • limit string

      The number of feature environments to return in a page. By default it is set to 50.

    • sortBy string

      The field to sort the results by. By default it is set to "createdAt".

    • sortOrder string

      The sort order for the sortBy. By default it is det to "asc".

    • favoritesFirst string

      The flag to indicate if the favorite features should be returned first. By default it is set to false.

    • createdAt string

      Possible values: Value must match regular expression ^(IS_BEFORE|IS_ON_OR_AFTER):\d{4}-\d{2}-\d{2}$

      The date the feature was created. The date can be specified with an operator. The supported operators are IS_BEFORE, IS_ON_OR_AFTER.

    Responses

    searchFeaturesSchema

    Schema
    • features object[]required

      The full list of features in this project matching search and filter criteria.

    • Array [
    • name string required

      Unique feature name

    • type string

      Type of the toggle e.g. experiment, kill-switch, release, operational, permission

    • description string nullable

      Detailed description of the feature

    • archived boolean

      true if the feature is archived

    • project string

      Name of the project the feature belongs to

    • enabled boolean

      true if the feature is enabled, otherwise false.

    • stale boolean

      true if the feature is stale based on the age and feature type, otherwise false.

    • favorite boolean

      true if the feature was favorited, otherwise false.

    • impressionData boolean

      true if the impression data collection is enabled for the feature, otherwise false.

    • createdAt date-time nullable

      The date the feature was created

    • archivedAt date-time nullable

      The date the feature was archived

    • lastSeenAt date-time nullable deprecated

      The date when metrics where last collected for the feature. This field is deprecated, use the one in featureEnvironmentSchema

    • environments object[]

      The list of environments where the feature can be used

    • Array [
    • name string required

      The name of the environment

    • featureName string

      The name of the feature

    • environment string

      The name of the environment

    • type string

      The type of the environment

    • enabled boolean required

      true if the feature is enabled for the environment, otherwise false.

    • sortOrder number

      The sort order of the feature environment in the feature environments list

    • variantCount number

      The number of defined variants

    • strategies object[]

      A list of activation strategies for the feature environment

    • Array [
    • id string

      A uuid for the feature strategy

    • name string required

      The name or type of strategy

    • title string nullable

      A descriptive title for the strategy

    • disabled boolean nullable

      A toggle to disable the strategy. defaults to false. Disabled strategies are not evaluated or returned to the SDKs

    • featureName string

      The name or feature the strategy is attached to

    • sortOrder number

      The order of the strategy in the list

    • segments number[]

      A list of segment ids attached to the strategy

    • constraints object[]

      A list of the constraints attached to the strategy. See https://docs.getunleash.io/reference/strategy-constraints

    • Array [
    • contextName string required

      The name of the context field that this constraint should apply to.

    • operator string required

      Possible values: [NOT_IN, IN, STR_ENDS_WITH, STR_STARTS_WITH, STR_CONTAINS, NUM_EQ, NUM_GT, NUM_GTE, NUM_LT, NUM_LTE, DATE_AFTER, DATE_BEFORE, SEMVER_EQ, SEMVER_GT, SEMVER_LT]

      The operator to use when evaluating this constraint. For more information about the various operators, refer to the strategy constraint operator documentation.

    • caseInsensitive boolean

      Default value: false

      Whether the operator should be case sensitive or not. Defaults to false (being case sensitive).

    • inverted boolean

      Default value: false

      Whether the result should be negated or not. If true, will turn a true result into a false result and vice versa.

    • values string[]

      The context values that should be used for constraint evaluation. Use this property instead of value for properties that accept multiple values.

    • value string

      The context value that should be used for constraint evaluation. Use this property instead of values for properties that only accept single values.

    • ]
    • variants object[]

      Strategy level variants

    • Array [
    • name string required

      The variant name. Must be unique for this feature toggle

    • weight integer required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is an integer between 0 and 1000. See the section on variant weights for more information

    • weightType string required

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000. Refer to the variant weight documentation.

    • stickiness string required

      The stickiness to use for distribution of this variant. Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • ]
    • parameters object

      A list of parameters for a strategy

    • property name* string
    • ]
    • variants object[]

      A list of variants for the feature environment

    • Array [
    • name string required

      The variants name. Is unique for this feature toggle

    • weight number required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is a number between 0 and 1000. See the section on variant weights for more information

    • weightType string

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000

    • stickiness string

      Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • overrides object[]

      Overrides assigning specific variants to specific users. The weighting system automatically assigns users to specific groups for you, but any overrides in this list will take precedence.

    • Array [
    • contextName string required

      The name of the context field used to determine overrides

    • values string[] required

      Which values that should be overriden

    • ]
    • ]
    • lastSeenAt date-time nullable

      The date when metrics where last collected for the feature environment

    • hasStrategies boolean

      Whether the feature has any strategies defined.

    • hasEnabledStrategies boolean

      Whether the feature has any enabled strategies defined.

    • ]
    • segments string[]

      The list of segments the feature is enabled for.

    • variants object[]deprecated

      The list of feature variants

    • Array [
    • name string required

      The variants name. Is unique for this feature toggle

    • weight number required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is a number between 0 and 1000. See the section on variant weights for more information

    • weightType string

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000

    • stickiness string

      Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • overrides object[]

      Overrides assigning specific variants to specific users. The weighting system automatically assigns users to specific groups for you, but any overrides in this list will take precedence.

    • Array [
    • contextName string required

      The name of the context field used to determine overrides

    • values string[] required

      Which values that should be overriden

    • ]
    • ]
    • strategies object[] deprecated

      This is a legacy field that will be deprecated

    • tags object[]nullable

      The list of feature tags

    • Array [
    • value string required

      Possible values: >= 2 characters and <= 50 characters

      The value of the tag

    • type string required

      Possible values: >= 2 characters and <= 50 characters

      Default value: simple

      The type of the tag

    • ]
    • children string[]

      The list of child feature names. This is an experimental field and may change.

    • dependencies object[]

      The list of parent dependencies. This is an experimental field and may change.

    • Array [
    • feature string required

      The name of the parent feature

    • enabled boolean

      Whether the parent feature is enabled or not

    • variants string[]

      The list of variants the parent feature should resolve to. Only valid when feature is enabled.

    • ]
    • ]
    • total number

      Total count of the features matching search and filter criteria

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/search-users.html b/reference/api/unleash/search-users.html index bf33562693..8e9240967c 100644 --- a/reference/api/unleash/search-users.html +++ b/reference/api/unleash/search-users.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Search users

    GET /api/admin/user-admin/search

    It will preform a simple search based on name and email matching the given query. Requires minimum 2 characters

    Request​

    Query Parameters

    • q string

      The pattern to search in the username or email

    Responses

    usersSchema

    Schema
    • users object[]required

      A list of users in the Unleash instance.

    • Array [
    • id integer required

      The user id

    • isAPI boolean deprecated

      (Deprecated): Used internally to know which operations the user should be allowed to perform

    • name string nullable

      Name of the user

    • email string

      Email of the user

    • username string nullable

      A unique username for the user

    • imageUrl string

      URL used for the userprofile image

    • inviteLink string

      If the user is actively inviting other users, this is the link that can be shared with other users

    • loginAttempts integer

      How many unsuccessful attempts at logging in has the user made

    • emailSent boolean

      Is the welcome email sent to the user or not

    • rootRole integer

      Which root role this user is assigned

    • seenAt date-time nullable

      The last time this user logged in

    • createdAt date-time

      The user was created at this time

    • accountType string

      A user is either an actual User or a Service Account

    • permissions string[]

      Deprecated

    • ]
    • rootRoles object[]

      A list of root roles in the Unleash instance.

    • Array [
    • id integer required

      The role id

    • type string required

      A role can either be a global root role (applies to all projects) or a project role

    • name string required

      The name of the role

    • description string

      A more detailed description of the role and what use it's intended for

    • ]
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/search.html b/reference/api/unleash/search.html index 8fbfd1334f..629ca6dcb5 100644 --- a/reference/api/unleash/search.html +++ b/reference/api/unleash/search.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content
    - + \ No newline at end of file diff --git a/reference/api/unleash/segments.html b/reference/api/unleash/segments.html index 458e480067..5ad7889098 100644 --- a/reference/api/unleash/segments.html +++ b/reference/api/unleash/segments.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Segments

    Create, update, delete, and manage segments.

    - + \ No newline at end of file diff --git a/reference/api/unleash/send-reset-password-email.html b/reference/api/unleash/send-reset-password-email.html index 3af0768e5e..c8eebae36a 100644 --- a/reference/api/unleash/send-reset-password-email.html +++ b/reference/api/unleash/send-reset-password-email.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Reset password

    POST /auth/reset/password-email

    Requests a password reset email for the user. This email can be used to reset the password for a user that has forgotten their password

    Request​

    Body

    required

    emailSchema

    • email string required

      The email address

    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/service-accounts.html b/reference/api/unleash/service-accounts.html index e669c1520a..04308d5f22 100644 --- a/reference/api/unleash/service-accounts.html +++ b/reference/api/unleash/service-accounts.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Service Accounts

    Endpoints for managing Service Accounts, which enable programmatic access to the Unleash API.

    - + \ No newline at end of file diff --git a/reference/api/unleash/set-google-settings.html b/reference/api/unleash/set-google-settings.html index e615982190..b4ea233101 100644 --- a/reference/api/unleash/set-google-settings.html +++ b/reference/api/unleash/set-google-settings.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Set Google auth options

    POST /api/admin/auth/google/settings
    deprecated

    This endpoint has been deprecated and may be removed in future versions of the API.

    Updates the settings for Google Authentication (deprecated, please use OpenID instead)

    Request​

    Body

    required

    googleSettingsSchema

    • enabled boolean

      Is google OIDC enabled

    • clientId string required

      The google client id, used to authenticate against google

    • clientSecret string required

      The client secret used to authenticate the OAuth session used to log the user in

    • unleashHostname string required

      Name of the host allowed to access the Google authentication flow

    • autoCreate boolean

      Should Unleash create users based on the emails coming back in the authentication reply from Google

    • emailDomains string

      A comma separated list of email domains that Unleash will auto create user accounts for.

    Responses

    googleSettingsSchema

    Schema
    • enabled boolean

      Is google OIDC enabled

    • clientId string required

      The google client id, used to authenticate against google

    • clientSecret string required

      The client secret used to authenticate the OAuth session used to log the user in

    • unleashHostname string required

      Name of the host allowed to access the Google authentication flow

    • autoCreate boolean

      Should Unleash create users based on the emails coming back in the authentication reply from Google

    • emailDomains string

      A comma separated list of email domains that Unleash will auto create user accounts for.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/set-oidc-settings.html b/reference/api/unleash/set-oidc-settings.html index 9f209f58a0..b8c1091023 100644 --- a/reference/api/unleash/set-oidc-settings.html +++ b/reference/api/unleash/set-oidc-settings.html @@ -20,7 +20,7 @@ - + @@ -30,7 +30,7 @@
    Skip to main content

    Set OIDC settings

    POST /api/admin/auth/oidc/settings

    Configure OpenID Connect as a login provider for Unleash.

    Request​

    Body

    required

    oidcSettingsSchema

    • enabled boolean

      true if OpenID connect is turned on for this instance, otherwise false

    • discoverUrl string
    • clientId string required

      The OIDC client ID of this application.

    • secret string required

      Shared secret from OpenID server. Used to authenticate login requests

    • autoCreate boolean

      Auto create users based on email addresses from login tokens

    • enableSingleSignOut boolean

      Support Single sign out when user clicks logout in Unleash. If true user is signed out of all OpenID Connect sessions against the clientId they may have active

    • defaultRootRole string

      Possible values: [Viewer, Editor, Admin]

      Default role granted to users auto-created from email. Only relevant if autoCreate is true

    • emailDomains string

      Comma separated list of email domains that are automatically approved for an account in the server. Only relevant if autoCreate is true

    • acrValues string

      Authentication Context Class Reference, used to request extra values in the acr claim returned from the server. If multiple values are required, they should be space separated. Consult the OIDC reference for more information

    • idTokenSigningAlgorithm string

      Possible values: [RS256, RS384, RS512]

      The signing algorithm used to sign our token. Refer to the JWT signatures documentation for more information.

    Responses

    oidcSettingsSchema

    Schema
    • enabled boolean

      true if OpenID connect is turned on for this instance, otherwise false

    • discoverUrl string
    • clientId string required

      The OIDC client ID of this application.

    • secret string required

      Shared secret from OpenID server. Used to authenticate login requests

    • autoCreate boolean

      Auto create users based on email addresses from login tokens

    • enableSingleSignOut boolean

      Support Single sign out when user clicks logout in Unleash. If true user is signed out of all OpenID Connect sessions against the clientId they may have active

    • defaultRootRole string

      Possible values: [Viewer, Editor, Admin]

      Default role granted to users auto-created from email. Only relevant if autoCreate is true

    • emailDomains string

      Comma separated list of email domains that are automatically approved for an account in the server. Only relevant if autoCreate is true

    • acrValues string

      Authentication Context Class Reference, used to request extra values in the acr claim returned from the server. If multiple values are required, they should be space separated. Consult the OIDC reference for more information

    • idTokenSigningAlgorithm string

      Possible values: [RS256, RS384, RS512]

      The signing algorithm used to sign our token. Refer to the JWT signatures documentation for more information.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/set-project-access.html b/reference/api/unleash/set-project-access.html index 8ebb9334ee..0167002f2c 100644 --- a/reference/api/unleash/set-project-access.html +++ b/reference/api/unleash/set-project-access.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Set users and groups to roles in the current project

    PUT /api/admin/projects/:projectId/access

    Sets all groups, users and their roles for the given project, overriding any existing configuration.

    Request​

    Path Parameters

    • projectId string required

    Body

    required

    projectAccessConfigurationSchema

    • roles object[]required

      A list of roles that are available within this project.

    • Array [
    • id integer

      Possible values: >= 1

      The id of the role.

    • groups integer[]

      A list of group ids that will be assigned this role

    • users integer[]

      A list of user ids that will be assigned this role

    • ]
    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/set-roles-for-group.html b/reference/api/unleash/set-roles-for-group.html index 03addc86c4..c4d0f43782 100644 --- a/reference/api/unleash/set-roles-for-group.html +++ b/reference/api/unleash/set-roles-for-group.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Sets roles for group

    PUT /api/admin/projects/:projectId/groups/:groupId/roles

    Sets the roles a group has in the project.

    Request​

    Path Parameters

    • projectId string required
    • groupId string required
    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/set-roles-for-user.html b/reference/api/unleash/set-roles-for-user.html index e8d5b871e1..dc5fa0ea0e 100644 --- a/reference/api/unleash/set-roles-for-user.html +++ b/reference/api/unleash/set-roles-for-user.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Sets roles for user

    PUT /api/admin/projects/:projectId/users/:userId/roles

    Sets the roles a user has in the project.

    Request​

    Path Parameters

    • projectId string required
    • userId string required
    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/set-saml-settings.html b/reference/api/unleash/set-saml-settings.html index 70beff909a..d7de10c6d6 100644 --- a/reference/api/unleash/set-saml-settings.html +++ b/reference/api/unleash/set-saml-settings.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Update SAML auth settings

    POST /api/admin/auth/saml/settings

    Updates the settings for SAML Authentication

    Request​

    Body

    required

    samlSettingsSchema

    • enabled boolean

      Is SAML authentication enabled

    • entityId string required

      The SAML 2.0 entity ID

    • signOnUrl string required

      Which URL to use for Single Sign On

    • certificate string required

      The X509 certificate used to validate requests

    • signOutUrl string

      Which URL to use for Single Sign Out

    • spCertificate string

      Signing certificate for sign out requests

    • autoCreate boolean

      Should Unleash create users based on the emails coming back in the authentication reply from the SAML server

    • emailDomains string

      A comma separated list of email domains that Unleash will auto create user accounts for.

    • defaultRootRole string

      Possible values: [Viewer, Editor, Admin]

      Assign this root role to auto created users

    Responses

    samlSettingsSchema

    Schema
    • enabled boolean

      Is SAML authentication enabled

    • entityId string required

      The SAML 2.0 entity ID

    • signOnUrl string required

      Which URL to use for Single Sign On

    • certificate string required

      The X509 certificate used to validate requests

    • signOutUrl string

      Which URL to use for Single Sign Out

    • spCertificate string

      Signing certificate for sign out requests

    • autoCreate boolean

      Should Unleash create users based on the emails coming back in the authentication reply from the SAML server

    • emailDomains string

      A comma separated list of email domains that Unleash will auto create user accounts for.

    • defaultRootRole string

      Possible values: [Viewer, Editor, Admin]

      Assign this root role to auto created users

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/set-simple-settings.html b/reference/api/unleash/set-simple-settings.html index 3e6a8a6eaf..1589fd1fda 100644 --- a/reference/api/unleash/set-simple-settings.html +++ b/reference/api/unleash/set-simple-settings.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Update Simple auth settings

    POST /api/admin/auth/simple/settings

    Enable or disable simple authentication (username/password)

    Request​

    Body

    required

    passwordAuthSchema

    • enabled boolean

      Is username/password authentication enabled

    Responses

    passwordAuthSchema

    Schema
    • enabled boolean

      Is username/password authentication enabled

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/set-strategy-sort-order.html b/reference/api/unleash/set-strategy-sort-order.html index f00f157b70..9284e0d313 100644 --- a/reference/api/unleash/set-strategy-sort-order.html +++ b/reference/api/unleash/set-strategy-sort-order.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Set strategy sort order

    POST /api/admin/projects/:projectId/features/:featureName/environments/:environment/strategies/set-sort-order

    Set the sort order of the provided list of strategies.

    Request​

    Path Parameters

    • projectId string required
    • featureName string required
    • environment string required

    Body

    arrayrequired

    setStrategySortOrderSchema

    • Array [
    • id string required

      The ID of the strategy

    • sortOrder number required

      The new sort order of the strategy

    • ]
    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/set-ui-config.html b/reference/api/unleash/set-ui-config.html index 98df3982aa..b371d5f04c 100644 --- a/reference/api/unleash/set-ui-config.html +++ b/reference/api/unleash/set-ui-config.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Set UI configuration

    POST /api/admin/ui-config

    Sets the UI configuration for this Unleash instance.

    Request​

    Body

    required

    setUiConfigSchema

    • frontendSettings object

      Settings related to the front-end API.

    • frontendApiOrigins string[] required

      The list of origins that the front-end API should accept requests from.

    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/stale-features.html b/reference/api/unleash/stale-features.html index cbd2af61d1..8709097053 100644 --- a/reference/api/unleash/stale-features.html +++ b/reference/api/unleash/stale-features.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Mark features as stale / not stale

    POST /api/admin/projects/:projectId/stale

    This endpoint marks the provided list of features as either stale or not stale depending on the request body you send. Any provided features that don't exist are ignored.

    Request​

    Path Parameters

    • projectId string required

    Body

    required

    batchStaleSchema

    • features string[] required

      A list of features to mark as (not) stale

    • stale boolean required

      Whether the list of features should be marked as stale or not stale. If true, the features will be marked as stale. If false, the features will be marked as not stale.

    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/strategies.html b/reference/api/unleash/strategies.html index 75f36740bd..a4ec45943b 100644 --- a/reference/api/unleash/strategies.html +++ b/reference/api/unleash/strategies.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Strategies

    Create, update, delete, manage custom strategies.

    - + \ No newline at end of file diff --git a/reference/api/unleash/tags.html b/reference/api/unleash/tags.html index a8b911cd83..b80d094866 100644 --- a/reference/api/unleash/tags.html +++ b/reference/api/unleash/tags.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Tags

    Create, update, and delete tags and tag types.

    - + \ No newline at end of file diff --git a/reference/api/unleash/telemetry.html b/reference/api/unleash/telemetry.html index 7df044d32c..14daf68bde 100644 --- a/reference/api/unleash/telemetry.html +++ b/reference/api/unleash/telemetry.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content
    - + \ No newline at end of file diff --git a/reference/api/unleash/toggle-environment-off.html b/reference/api/unleash/toggle-environment-off.html index eabc7f1b51..9f795f80ea 100644 --- a/reference/api/unleash/toggle-environment-off.html +++ b/reference/api/unleash/toggle-environment-off.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Toggle the environment with `name` off

    POST /api/admin/environments/:name/off

    Removes this environment from the list of available environments for projects to use

    Request​

    Path Parameters

    • name string required
    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/toggle-environment-on.html b/reference/api/unleash/toggle-environment-on.html index 90383ac9bc..42f53965ea 100644 --- a/reference/api/unleash/toggle-environment-on.html +++ b/reference/api/unleash/toggle-environment-on.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Toggle the environment with `name` on

    POST /api/admin/environments/:name/on

    Makes it possible to enable this environment for a project. An environment must first be globally enabled using this endpoint before it can be enabled for a project

    Request​

    Path Parameters

    • name string required
    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/toggle-feature-environment-off.html b/reference/api/unleash/toggle-feature-environment-off.html index 07045d9e01..ee5ea41d88 100644 --- a/reference/api/unleash/toggle-feature-environment-off.html +++ b/reference/api/unleash/toggle-feature-environment-off.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Disable a feature toggle

    POST /api/admin/projects/:projectId/features/:featureName/environments/:environment/off

    Disable a feature toggle in the specified environment.

    Request​

    Path Parameters

    • projectId string required
    • featureName string required
    • environment string required
    Responses

    featureSchema

    Schema
    • name string required

      Unique feature name

    • type string

      Type of the toggle e.g. experiment, kill-switch, release, operational, permission

    • description string nullable

      Detailed description of the feature

    • archived boolean

      true if the feature is archived

    • project string

      Name of the project the feature belongs to

    • enabled boolean

      true if the feature is enabled, otherwise false.

    • stale boolean

      true if the feature is stale based on the age and feature type, otherwise false.

    • favorite boolean

      true if the feature was favorited, otherwise false.

    • impressionData boolean

      true if the impression data collection is enabled for the feature, otherwise false.

    • createdAt date-time nullable

      The date the feature was created

    • archivedAt date-time nullable

      The date the feature was archived

    • lastSeenAt date-time nullable deprecated

      The date when metrics where last collected for the feature. This field is deprecated, use the one in featureEnvironmentSchema

    • environments object[]

      The list of environments where the feature can be used

    • Array [
    • name string required

      The name of the environment

    • featureName string

      The name of the feature

    • environment string

      The name of the environment

    • type string

      The type of the environment

    • enabled boolean required

      true if the feature is enabled for the environment, otherwise false.

    • sortOrder number

      The sort order of the feature environment in the feature environments list

    • variantCount number

      The number of defined variants

    • strategies object[]

      A list of activation strategies for the feature environment

    • Array [
    • id string

      A uuid for the feature strategy

    • name string required

      The name or type of strategy

    • title string nullable

      A descriptive title for the strategy

    • disabled boolean nullable

      A toggle to disable the strategy. defaults to false. Disabled strategies are not evaluated or returned to the SDKs

    • featureName string

      The name or feature the strategy is attached to

    • sortOrder number

      The order of the strategy in the list

    • segments number[]

      A list of segment ids attached to the strategy

    • constraints object[]

      A list of the constraints attached to the strategy. See https://docs.getunleash.io/reference/strategy-constraints

    • Array [
    • contextName string required

      The name of the context field that this constraint should apply to.

    • operator string required

      Possible values: [NOT_IN, IN, STR_ENDS_WITH, STR_STARTS_WITH, STR_CONTAINS, NUM_EQ, NUM_GT, NUM_GTE, NUM_LT, NUM_LTE, DATE_AFTER, DATE_BEFORE, SEMVER_EQ, SEMVER_GT, SEMVER_LT]

      The operator to use when evaluating this constraint. For more information about the various operators, refer to the strategy constraint operator documentation.

    • caseInsensitive boolean

      Default value: false

      Whether the operator should be case sensitive or not. Defaults to false (being case sensitive).

    • inverted boolean

      Default value: false

      Whether the result should be negated or not. If true, will turn a true result into a false result and vice versa.

    • values string[]

      The context values that should be used for constraint evaluation. Use this property instead of value for properties that accept multiple values.

    • value string

      The context value that should be used for constraint evaluation. Use this property instead of values for properties that only accept single values.

    • ]
    • variants object[]

      Strategy level variants

    • Array [
    • name string required

      The variant name. Must be unique for this feature toggle

    • weight integer required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is an integer between 0 and 1000. See the section on variant weights for more information

    • weightType string required

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000. Refer to the variant weight documentation.

    • stickiness string required

      The stickiness to use for distribution of this variant. Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • ]
    • parameters object

      A list of parameters for a strategy

    • property name* string
    • ]
    • variants object[]

      A list of variants for the feature environment

    • Array [
    • name string required

      The variants name. Is unique for this feature toggle

    • weight number required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is a number between 0 and 1000. See the section on variant weights for more information

    • weightType string

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000

    • stickiness string

      Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • overrides object[]

      Overrides assigning specific variants to specific users. The weighting system automatically assigns users to specific groups for you, but any overrides in this list will take precedence.

    • Array [
    • contextName string required

      The name of the context field used to determine overrides

    • values string[] required

      Which values that should be overriden

    • ]
    • ]
    • lastSeenAt date-time nullable

      The date when metrics where last collected for the feature environment

    • hasStrategies boolean

      Whether the feature has any strategies defined.

    • hasEnabledStrategies boolean

      Whether the feature has any enabled strategies defined.

    • ]
    • variants object[]deprecated

      The list of feature variants

    • Array [
    • name string required

      The variants name. Is unique for this feature toggle

    • weight number required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is a number between 0 and 1000. See the section on variant weights for more information

    • weightType string

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000

    • stickiness string

      Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • overrides object[]

      Overrides assigning specific variants to specific users. The weighting system automatically assigns users to specific groups for you, but any overrides in this list will take precedence.

    • Array [
    • contextName string required

      The name of the context field used to determine overrides

    • values string[] required

      Which values that should be overriden

    • ]
    • ]
    • strategies object[] deprecated

      This is a legacy field that will be deprecated

    • tags object[]nullable

      The list of feature tags

    • Array [
    • value string required

      Possible values: >= 2 characters and <= 50 characters

      The value of the tag

    • type string required

      Possible values: >= 2 characters and <= 50 characters

      Default value: simple

      The type of the tag

    • ]
    • children string[]

      The list of child feature names. This is an experimental field and may change.

    • dependencies object[]

      The list of parent dependencies. This is an experimental field and may change.

    • Array [
    • feature string required

      The name of the parent feature

    • enabled boolean

      Whether the parent feature is enabled or not

    • variants string[]

      The list of variants the parent feature should resolve to. Only valid when feature is enabled.

    • ]
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/toggle-feature-environment-on.html b/reference/api/unleash/toggle-feature-environment-on.html index ad0d2123da..d3ccb1078e 100644 --- a/reference/api/unleash/toggle-feature-environment-on.html +++ b/reference/api/unleash/toggle-feature-environment-on.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Enable a feature toggle

    POST /api/admin/projects/:projectId/features/:featureName/environments/:environment/on

    Enable a feature toggle in the specified environment.

    Request​

    Path Parameters

    • projectId string required
    • featureName string required
    • environment string required
    Responses

    featureSchema

    Schema
    • name string required

      Unique feature name

    • type string

      Type of the toggle e.g. experiment, kill-switch, release, operational, permission

    • description string nullable

      Detailed description of the feature

    • archived boolean

      true if the feature is archived

    • project string

      Name of the project the feature belongs to

    • enabled boolean

      true if the feature is enabled, otherwise false.

    • stale boolean

      true if the feature is stale based on the age and feature type, otherwise false.

    • favorite boolean

      true if the feature was favorited, otherwise false.

    • impressionData boolean

      true if the impression data collection is enabled for the feature, otherwise false.

    • createdAt date-time nullable

      The date the feature was created

    • archivedAt date-time nullable

      The date the feature was archived

    • lastSeenAt date-time nullable deprecated

      The date when metrics where last collected for the feature. This field is deprecated, use the one in featureEnvironmentSchema

    • environments object[]

      The list of environments where the feature can be used

    • Array [
    • name string required

      The name of the environment

    • featureName string

      The name of the feature

    • environment string

      The name of the environment

    • type string

      The type of the environment

    • enabled boolean required

      true if the feature is enabled for the environment, otherwise false.

    • sortOrder number

      The sort order of the feature environment in the feature environments list

    • variantCount number

      The number of defined variants

    • strategies object[]

      A list of activation strategies for the feature environment

    • Array [
    • id string

      A uuid for the feature strategy

    • name string required

      The name or type of strategy

    • title string nullable

      A descriptive title for the strategy

    • disabled boolean nullable

      A toggle to disable the strategy. defaults to false. Disabled strategies are not evaluated or returned to the SDKs

    • featureName string

      The name or feature the strategy is attached to

    • sortOrder number

      The order of the strategy in the list

    • segments number[]

      A list of segment ids attached to the strategy

    • constraints object[]

      A list of the constraints attached to the strategy. See https://docs.getunleash.io/reference/strategy-constraints

    • Array [
    • contextName string required

      The name of the context field that this constraint should apply to.

    • operator string required

      Possible values: [NOT_IN, IN, STR_ENDS_WITH, STR_STARTS_WITH, STR_CONTAINS, NUM_EQ, NUM_GT, NUM_GTE, NUM_LT, NUM_LTE, DATE_AFTER, DATE_BEFORE, SEMVER_EQ, SEMVER_GT, SEMVER_LT]

      The operator to use when evaluating this constraint. For more information about the various operators, refer to the strategy constraint operator documentation.

    • caseInsensitive boolean

      Default value: false

      Whether the operator should be case sensitive or not. Defaults to false (being case sensitive).

    • inverted boolean

      Default value: false

      Whether the result should be negated or not. If true, will turn a true result into a false result and vice versa.

    • values string[]

      The context values that should be used for constraint evaluation. Use this property instead of value for properties that accept multiple values.

    • value string

      The context value that should be used for constraint evaluation. Use this property instead of values for properties that only accept single values.

    • ]
    • variants object[]

      Strategy level variants

    • Array [
    • name string required

      The variant name. Must be unique for this feature toggle

    • weight integer required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is an integer between 0 and 1000. See the section on variant weights for more information

    • weightType string required

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000. Refer to the variant weight documentation.

    • stickiness string required

      The stickiness to use for distribution of this variant. Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • ]
    • parameters object

      A list of parameters for a strategy

    • property name* string
    • ]
    • variants object[]

      A list of variants for the feature environment

    • Array [
    • name string required

      The variants name. Is unique for this feature toggle

    • weight number required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is a number between 0 and 1000. See the section on variant weights for more information

    • weightType string

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000

    • stickiness string

      Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • overrides object[]

      Overrides assigning specific variants to specific users. The weighting system automatically assigns users to specific groups for you, but any overrides in this list will take precedence.

    • Array [
    • contextName string required

      The name of the context field used to determine overrides

    • values string[] required

      Which values that should be overriden

    • ]
    • ]
    • lastSeenAt date-time nullable

      The date when metrics where last collected for the feature environment

    • hasStrategies boolean

      Whether the feature has any strategies defined.

    • hasEnabledStrategies boolean

      Whether the feature has any enabled strategies defined.

    • ]
    • variants object[]deprecated

      The list of feature variants

    • Array [
    • name string required

      The variants name. Is unique for this feature toggle

    • weight number required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is a number between 0 and 1000. See the section on variant weights for more information

    • weightType string

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000

    • stickiness string

      Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • overrides object[]

      Overrides assigning specific variants to specific users. The weighting system automatically assigns users to specific groups for you, but any overrides in this list will take precedence.

    • Array [
    • contextName string required

      The name of the context field used to determine overrides

    • values string[] required

      Which values that should be overriden

    • ]
    • ]
    • strategies object[] deprecated

      This is a legacy field that will be deprecated

    • tags object[]nullable

      The list of feature tags

    • Array [
    • value string required

      Possible values: >= 2 characters and <= 50 characters

      The value of the tag

    • type string required

      Possible values: >= 2 characters and <= 50 characters

      Default value: simple

      The type of the tag

    • ]
    • children string[]

      The list of child feature names. This is an experimental field and may change.

    • dependencies object[]

      The list of parent dependencies. This is an experimental field and may change.

    • Array [
    • feature string required

      The name of the parent feature

    • enabled boolean

      Whether the parent feature is enabled or not

    • variants string[]

      The list of variants the parent feature should resolve to. Only valid when feature is enabled.

    • ]
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/toggle-maintenance.html b/reference/api/unleash/toggle-maintenance.html index 16303e91c6..72d9b0339b 100644 --- a/reference/api/unleash/toggle-maintenance.html +++ b/reference/api/unleash/toggle-maintenance.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Enabled/disabled maintenance mode

    POST /api/admin/maintenance

    Lets administrators put Unleash into a mostly read-only mode. While Unleash is in maintenance mode, users can not change any configuration settings

    Request​

    Body

    required

    toggleMaintenanceSchema

    • enabled boolean required

      true if you want to activate maintenance mode, false if you want to deactivate it.

    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/unleash-api.html b/reference/api/unleash/unleash-api.html index 98296d10b7..07e193d8d7 100644 --- a/reference/api/unleash/unleash-api.html +++ b/reference/api/unleash/unleash-api.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content
    Version: 5.8.2

    Unleash API

    Authentication​

    Security Scheme Type:apiKey
    Header parameter name:Authorization
    - + \ No newline at end of file diff --git a/reference/api/unleash/unstable.html b/reference/api/unleash/unstable.html index 96960859f1..c41328dd92 100644 --- a/reference/api/unleash/unstable.html +++ b/reference/api/unleash/unstable.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Unstable

    Experimental endpoints that may change or disappear at any time.

    - + \ No newline at end of file diff --git a/reference/api/unleash/update-addon.html b/reference/api/unleash/update-addon.html index 2796ad4889..76019a9f6f 100644 --- a/reference/api/unleash/update-addon.html +++ b/reference/api/unleash/update-addon.html @@ -20,7 +20,7 @@ - + @@ -37,7 +37,7 @@
  • webhook for webhooks

    • The provider you choose for your addon dictates what properties the parameters object needs. Refer to the documentation for each provider for more information.

  • description string

    A description of the addon.

  • enabled boolean required

    Whether the addon should be enabled or not.

  • parameters objectrequired

    Parameters for the addon provider. This object has different required and optional properties depending on the provider you choose. Consult the documentation for details.

  • events string[] required

    The event types that will trigger this specific addon.

  • projects string[]

    The projects that this addon will listen to events from. An empty list means it will listen to events from all projects.

  • environments string[]

    The list of environments that this addon will listen to events from. An empty list means it will listen to events from all environments.

    • Responses

    addonSchema

    Schema
    • id integer required

      Possible values: >= 1

      The addon's unique identifier.

    • provider string required

      The addon provider, such as "webhook" or "slack".

    • description string nullable required

      A description of the addon. null if no description exists.

    • enabled boolean required

      Whether the addon is enabled or not.

    • parameters objectrequired

      Parameters for the addon provider. This object has different required and optional properties depending on the provider you choose.

    • events string[] required

      The event types that trigger this specific addon.

    • projects string[]

      The projects that this addon listens to events from. An empty list means it listens to events from all projects.

    • environments string[]

      The list of environments that this addon listens to events from. An empty list means it listens to events from all environments.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/update-api-token.html b/reference/api/unleash/update-api-token.html index b0ea2ff3bd..6b9a3424c0 100644 --- a/reference/api/unleash/update-api-token.html +++ b/reference/api/unleash/update-api-token.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Update API token

    PUT /api/admin/api-tokens/:token

    Updates an existing API token with a new expiry date. The token path parameter is the token's secret. If the token does not exist, this endpoint returns a 200 OK, but does nothing.

    Request​

    Path Parameters

    • token string required

    Body

    required

    updateApiTokenSchema

    • expiresAt date-time required

      The new time when this token should expire.

    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/update-banner.html b/reference/api/unleash/update-banner.html index 1a5c638a22..0bb687f514 100644 --- a/reference/api/unleash/update-banner.html +++ b/reference/api/unleash/update-banner.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Update a banner.

    PUT /api/admin/banners/:id

    Updates an existing banner identified by its id.

    Request​

    Path Parameters

    • id string required

    Body

    required

    createBannerSchema

    • message string required

      The message to display to all users. Supports markdown.

    • enabled boolean

      Whether the banner should be displayed currently. If not specified, defaults to true.

    • variant string

      The variant of the banner. One of "info", "warning", "error", or "success". If not specified, defaults to "info".

    • sticky boolean

      Whether the banner should be sticky on the screen. If not specified, defaults to false.

    • icon string nullable

      The icon to display on the banner. Can be one of https://fonts.google.com/icons. If not specified, this will be the default icon for the variant. If "none", no icon will be displayed.

    • link string nullable

      The link to display on the banner. Can either be an absolute or a relative link (e.g. absolute: "https://example.com" or relative: "/admin/service-accounts"). If "dialog", will display a dialog when clicked. If not specified, no link will be displayed.

    • linkText string nullable

      The text to display on the link. If not specified, will be displayed as "More info".

    • dialogTitle string nullable

      The title to display on the dialog. If not specified, this will be the same as linkText.

    • dialog string nullable

      The markdown to display on the dialog. If not specified, no dialog will be displayed.

    Responses

    bannerSchema

    Schema
    • id integer required

      Possible values: >= 1

      The banner's ID. Banner IDs are incrementing integers. In other words, a more recently created banner will always have a higher ID than an older one.

    • message string required

      The message to display to all users. Supports markdown.

    • enabled boolean

      Whether the banner should be displayed currently. If not specified, defaults to true.

    • variant string

      The variant of the banner. One of "info", "warning", "error", or "success". If not specified, defaults to "info".

    • sticky boolean

      Whether the banner should be sticky on the screen. If not specified, defaults to false.

    • icon string nullable

      The icon to display on the banner. Can be one of https://fonts.google.com/icons. If not specified, this will be the default icon for the variant. If "none", no icon will be displayed.

    • link string nullable

      The link to display on the banner. Can either be an absolute or a relative link (e.g. absolute: "https://example.com" or relative: "/admin/service-accounts"). If "dialog", will display a dialog when clicked. If not specified, no link will be displayed.

    • linkText string nullable

      The text to display on the link. If not specified, will be displayed as "More info".

    • dialogTitle string nullable

      The title to display on the dialog. If not specified, this will be the same as linkText.

    • dialog string nullable

      The markdown to display on the dialog. If not specified, no dialog will be displayed.

    • createdAt date-time required

      The date and time of when the banner was created.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/update-change-request-state.html b/reference/api/unleash/update-change-request-state.html index b1795e5dea..0eb8205378 100644 --- a/reference/api/unleash/update-change-request-state.html +++ b/reference/api/unleash/update-change-request-state.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    This endpoint will update the state of a change request

    PUT /api/admin/projects/:projectId/change-requests/:id/state

    This endpoint will update the state of a change request if the business rules allow it. The state can be one of the following: Draft, In review, Approved, Cancelled, Applied. In order to be approved, the change request must have at least one change and the number of approvals must be greater than or equal to the number of approvals required for the environment.

                    Once a change request has been approved, it can be applied. Once a change request has been applied, it cannot be changed. Once a change request has been cancelled, it cannot be changed. Any change to a change request in the state of Approved will result in the state being set to In Review and the number of approvals will be reset.

    Request​

    Path Parameters

    • projectId string required
    • id string required
    Responses

    changeRequestStateSchema

    Schema
      oneOf
    • state string required

      Possible values: [Draft, In review, Approved, Applied, Cancelled, Rejected]

      The new desired state for the change request

    • comment string

      Any comments accompanying the state changed. Used when sending a draft to review.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/update-change-request-title.html b/reference/api/unleash/update-change-request-title.html index 6e047d8a10..5264d6dba1 100644 --- a/reference/api/unleash/update-change-request-title.html +++ b/reference/api/unleash/update-change-request-title.html @@ -20,7 +20,7 @@ - + @@ -29,7 +29,7 @@
    Skip to main content

    This endpoint will update the custom title of a change request

    PUT /api/admin/projects/:projectId/change-requests/:id/title

    Change requests get a default title e.g. Change Request #1. This endpoint allows to make the title more meaningful and describe the intent behind the Change Request

    Request​

    Path Parameters

    • projectId string required
    • id string required
    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/update-context-field.html b/reference/api/unleash/update-context-field.html index f65fac269f..a4ca6e34dd 100644 --- a/reference/api/unleash/update-context-field.html +++ b/reference/api/unleash/update-context-field.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Update an existing context field

    PUT /api/admin/context/:contextField

    Endpoint that allows updating a custom context field. Used to toggle stickiness and add/remove legal values for this context field

    Request​

    Path Parameters

    • contextField string required

    Body

    required

    updateContextFieldSchema

    • description string

      A description of the context field

    • stickiness boolean

      true if this field should be available for use with custom stickiness, otherwise false

    • sortOrder integer

      How this context field should be sorted if no other sort order is selected

    • legalValues object[]

      A list of allowed values for this context field

    • Array [
    • value string required

      The valid value

    • description string

      Describes this specific legal value

    • ]
    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/update-environment.html b/reference/api/unleash/update-environment.html index ec81fdc2ab..015756b8b0 100644 --- a/reference/api/unleash/update-environment.html +++ b/reference/api/unleash/update-environment.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Updates an environment by name

    PUT /api/admin/environments/update/:name

    Given an environment by name updates the environment with the given payload. Note that name, enabled and protected cannot be changed by this API

    Request​

    Path Parameters

    • name string required

    Body

    required

    updateEnvironmentSchema

    • type string

      Updates the type of environment (i.e. development or production).

    • sortOrder integer

      Changes the sort order of this environment.

    Responses

    environmentSchema

    Schema
    • name string required

      The name of the environment

    • type string required
    • enabled boolean required

      true if the environment is enabled for the project, otherwise false.

    • protected boolean required

      true if the environment is protected, otherwise false. A protected environment can not be deleted.

    • sortOrder integer required

      Priority of the environment in a list of environments, the lower the value, the higher up in the list the environment will appear. Needs to be an integer

    • projectCount integer nullable

      The number of projects with this environment

    • apiTokenCount integer nullable

      The number of API tokens for the project environment

    • enabledToggleCount integer nullable

      The number of enabled toggles for the project environment

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/update-feature-strategy-segments.html b/reference/api/unleash/update-feature-strategy-segments.html index ce70c69213..ecce6a4edf 100644 --- a/reference/api/unleash/update-feature-strategy-segments.html +++ b/reference/api/unleash/update-feature-strategy-segments.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Update strategy segments

    POST /api/admin/segments/strategies

    Sets the segments of the strategy specified to be exactly the ones passed in the payload. Any segments that were used by the strategy before will be removed if they are not in the provided list of segments.

    Request​

    Body

    required

    updateFeatureStrategySegmentsSchema

    • projectId string required

      The ID of the project that the strategy belongs to.

    • strategyId string required

      The ID of the strategy to update segments for.

    • environmentId string required

      The ID of the strategy environment.

    • segmentIds integer[] required

      The new list of segments (IDs) to use for this strategy. Any segments not in this list will be removed from the strategy.

    Responses

    The resource was successfully created.

    Response Headers
    • location string

      The location of the newly created resource.

    Schema
    • projectId string required

      The ID of the project that the strategy belongs to.

    • strategyId string required

      The ID of the strategy to update segments for.

    • environmentId string required

      The ID of the strategy environment.

    • segmentIds integer[] required

      The new list of segments (IDs) to use for this strategy. Any segments not in this list will be removed from the strategy.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/update-feature-strategy.html b/reference/api/unleash/update-feature-strategy.html index 2b90cbae66..f3aa882b80 100644 --- a/reference/api/unleash/update-feature-strategy.html +++ b/reference/api/unleash/update-feature-strategy.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Update a strategy

    PUT /api/admin/projects/:projectId/features/:featureName/environments/:environment/strategies/:strategyId

    Replace strategy configuration for a feature toggle in the specified environment.

    Request​

    Path Parameters

    • projectId string required
    • featureName string required
    • environment string required
    • strategyId string required

    Body

    required

    updateFeatureStrategySchema

    • name string

      The name of the strategy type

    • sortOrder number

      The order of the strategy in the list in feature environment configuration

    • constraints object[]

      A list of the constraints attached to the strategy. See https://docs.getunleash.io/reference/strategy-constraints

    • Array [
    • contextName string required

      The name of the context field that this constraint should apply to.

    • operator string required

      Possible values: [NOT_IN, IN, STR_ENDS_WITH, STR_STARTS_WITH, STR_CONTAINS, NUM_EQ, NUM_GT, NUM_GTE, NUM_LT, NUM_LTE, DATE_AFTER, DATE_BEFORE, SEMVER_EQ, SEMVER_GT, SEMVER_LT]

      The operator to use when evaluating this constraint. For more information about the various operators, refer to the strategy constraint operator documentation.

    • caseInsensitive boolean

      Default value: false

      Whether the operator should be case sensitive or not. Defaults to false (being case sensitive).

    • inverted boolean

      Default value: false

      Whether the result should be negated or not. If true, will turn a true result into a false result and vice versa.

    • values string[]

      The context values that should be used for constraint evaluation. Use this property instead of value for properties that accept multiple values.

    • value string

      The context value that should be used for constraint evaluation. Use this property instead of values for properties that only accept single values.

    • ]
    • title string nullable

      A descriptive title for the strategy

    • disabled boolean nullable

      A toggle to disable the strategy. defaults to true. Disabled strategies are not evaluated or returned to the SDKs

    • parameters object

      A list of parameters for a strategy

    • property name* string
    Responses

    featureStrategySchema

    Schema
    • id string

      A uuid for the feature strategy

    • name string required

      The name or type of strategy

    • title string nullable

      A descriptive title for the strategy

    • disabled boolean nullable

      A toggle to disable the strategy. defaults to false. Disabled strategies are not evaluated or returned to the SDKs

    • featureName string

      The name or feature the strategy is attached to

    • sortOrder number

      The order of the strategy in the list

    • segments number[]

      A list of segment ids attached to the strategy

    • constraints object[]

      A list of the constraints attached to the strategy. See https://docs.getunleash.io/reference/strategy-constraints

    • Array [
    • contextName string required

      The name of the context field that this constraint should apply to.

    • operator string required

      Possible values: [NOT_IN, IN, STR_ENDS_WITH, STR_STARTS_WITH, STR_CONTAINS, NUM_EQ, NUM_GT, NUM_GTE, NUM_LT, NUM_LTE, DATE_AFTER, DATE_BEFORE, SEMVER_EQ, SEMVER_GT, SEMVER_LT]

      The operator to use when evaluating this constraint. For more information about the various operators, refer to the strategy constraint operator documentation.

    • caseInsensitive boolean

      Default value: false

      Whether the operator should be case sensitive or not. Defaults to false (being case sensitive).

    • inverted boolean

      Default value: false

      Whether the result should be negated or not. If true, will turn a true result into a false result and vice versa.

    • values string[]

      The context values that should be used for constraint evaluation. Use this property instead of value for properties that accept multiple values.

    • value string

      The context value that should be used for constraint evaluation. Use this property instead of values for properties that only accept single values.

    • ]
    • variants object[]

      Strategy level variants

    • Array [
    • name string required

      The variant name. Must be unique for this feature toggle

    • weight integer required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is an integer between 0 and 1000. See the section on variant weights for more information

    • weightType string required

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000. Refer to the variant weight documentation.

    • stickiness string required

      The stickiness to use for distribution of this variant. Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • ]
    • parameters object

      A list of parameters for a strategy

    • property name* string
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/update-feature-type-lifetime.html b/reference/api/unleash/update-feature-type-lifetime.html index bd74df9bd5..c34353c696 100644 --- a/reference/api/unleash/update-feature-type-lifetime.html +++ b/reference/api/unleash/update-feature-type-lifetime.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Update feature type lifetime

    PUT /api/admin/feature-types/:id/lifetime

    Updates the lifetime configuration for the specified feature toggle type. The expected lifetime is an integer representing the number of days before Unleash marks a feature toggle of that type as potentially stale. If set to null or 0, then feature toggles of that particular type will never be marked as potentially stale.

    When a feature toggle type's expected lifetime is changed, this will also cause any feature toggles of this type to be reevaluated for potential staleness.

    Request​

    Path Parameters

    • id string required

    Body

    required

    updateFeatureTypeLifetimeSchema

    • lifetimeDays integer nullable required

      Possible values: <= 2147483647

      The new lifetime (in days) that you want to assign to the feature toggle type. If the value is null or 0, then the feature toggles of that type will never be marked as potentially stale. Otherwise, they will be considered potentially stale after the number of days indicated by this property.

    Responses

    featureTypeSchema

    Schema
    • id string required

      The identifier of this feature toggle type.

    • name string required

      The display name of this feature toggle type.

    • description string required

      A description of what this feature toggle type is intended to be used for.

    • lifetimeDays integer nullable required

      How many days it takes before a feature toggle of this typed is flagged as potentially stale by Unleash. If this value is null, Unleash will never mark it as potentially stale.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/update-feature.html b/reference/api/unleash/update-feature.html index 9981afff40..61225e9ab1 100644 --- a/reference/api/unleash/update-feature.html +++ b/reference/api/unleash/update-feature.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Update a feature toggle

    PUT /api/admin/projects/:projectId/features/:featureName

    Updates the specified feature if the feature belongs to the specified project. Only the provided properties are updated; any feature properties left out of the request body are left untouched.

    Request​

    Path Parameters

    • projectId string required
    • featureName string required

    Body

    required

    updateFeatureSchema

    • description string

      Detailed description of the feature

    • type string

      Type of the toggle e.g. experiment, kill-switch, release, operational, permission

    • stale boolean

      true if the feature is archived

    • archived boolean

      If true the feature toggle will be moved to the archive with a property archivedAt set to current time

    • impressionData boolean

      true if the impression data collection is enabled for the feature

    Responses

    featureSchema

    Schema
    • name string required

      Unique feature name

    • type string

      Type of the toggle e.g. experiment, kill-switch, release, operational, permission

    • description string nullable

      Detailed description of the feature

    • archived boolean

      true if the feature is archived

    • project string

      Name of the project the feature belongs to

    • enabled boolean

      true if the feature is enabled, otherwise false.

    • stale boolean

      true if the feature is stale based on the age and feature type, otherwise false.

    • favorite boolean

      true if the feature was favorited, otherwise false.

    • impressionData boolean

      true if the impression data collection is enabled for the feature, otherwise false.

    • createdAt date-time nullable

      The date the feature was created

    • archivedAt date-time nullable

      The date the feature was archived

    • lastSeenAt date-time nullable deprecated

      The date when metrics where last collected for the feature. This field is deprecated, use the one in featureEnvironmentSchema

    • environments object[]

      The list of environments where the feature can be used

    • Array [
    • name string required

      The name of the environment

    • featureName string

      The name of the feature

    • environment string

      The name of the environment

    • type string

      The type of the environment

    • enabled boolean required

      true if the feature is enabled for the environment, otherwise false.

    • sortOrder number

      The sort order of the feature environment in the feature environments list

    • variantCount number

      The number of defined variants

    • strategies object[]

      A list of activation strategies for the feature environment

    • Array [
    • id string

      A uuid for the feature strategy

    • name string required

      The name or type of strategy

    • title string nullable

      A descriptive title for the strategy

    • disabled boolean nullable

      A toggle to disable the strategy. defaults to false. Disabled strategies are not evaluated or returned to the SDKs

    • featureName string

      The name or feature the strategy is attached to

    • sortOrder number

      The order of the strategy in the list

    • segments number[]

      A list of segment ids attached to the strategy

    • constraints object[]

      A list of the constraints attached to the strategy. See https://docs.getunleash.io/reference/strategy-constraints

    • Array [
    • contextName string required

      The name of the context field that this constraint should apply to.

    • operator string required

      Possible values: [NOT_IN, IN, STR_ENDS_WITH, STR_STARTS_WITH, STR_CONTAINS, NUM_EQ, NUM_GT, NUM_GTE, NUM_LT, NUM_LTE, DATE_AFTER, DATE_BEFORE, SEMVER_EQ, SEMVER_GT, SEMVER_LT]

      The operator to use when evaluating this constraint. For more information about the various operators, refer to the strategy constraint operator documentation.

    • caseInsensitive boolean

      Default value: false

      Whether the operator should be case sensitive or not. Defaults to false (being case sensitive).

    • inverted boolean

      Default value: false

      Whether the result should be negated or not. If true, will turn a true result into a false result and vice versa.

    • values string[]

      The context values that should be used for constraint evaluation. Use this property instead of value for properties that accept multiple values.

    • value string

      The context value that should be used for constraint evaluation. Use this property instead of values for properties that only accept single values.

    • ]
    • variants object[]

      Strategy level variants

    • Array [
    • name string required

      The variant name. Must be unique for this feature toggle

    • weight integer required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is an integer between 0 and 1000. See the section on variant weights for more information

    • weightType string required

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000. Refer to the variant weight documentation.

    • stickiness string required

      The stickiness to use for distribution of this variant. Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • ]
    • parameters object

      A list of parameters for a strategy

    • property name* string
    • ]
    • variants object[]

      A list of variants for the feature environment

    • Array [
    • name string required

      The variants name. Is unique for this feature toggle

    • weight number required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is a number between 0 and 1000. See the section on variant weights for more information

    • weightType string

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000

    • stickiness string

      Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • overrides object[]

      Overrides assigning specific variants to specific users. The weighting system automatically assigns users to specific groups for you, but any overrides in this list will take precedence.

    • Array [
    • contextName string required

      The name of the context field used to determine overrides

    • values string[] required

      Which values that should be overriden

    • ]
    • ]
    • lastSeenAt date-time nullable

      The date when metrics where last collected for the feature environment

    • hasStrategies boolean

      Whether the feature has any strategies defined.

    • hasEnabledStrategies boolean

      Whether the feature has any enabled strategies defined.

    • ]
    • variants object[]deprecated

      The list of feature variants

    • Array [
    • name string required

      The variants name. Is unique for this feature toggle

    • weight number required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is a number between 0 and 1000. See the section on variant weights for more information

    • weightType string

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000

    • stickiness string

      Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • overrides object[]

      Overrides assigning specific variants to specific users. The weighting system automatically assigns users to specific groups for you, but any overrides in this list will take precedence.

    • Array [
    • contextName string required

      The name of the context field used to determine overrides

    • values string[] required

      Which values that should be overriden

    • ]
    • ]
    • strategies object[] deprecated

      This is a legacy field that will be deprecated

    • tags object[]nullable

      The list of feature tags

    • Array [
    • value string required

      Possible values: >= 2 characters and <= 50 characters

      The value of the tag

    • type string required

      Possible values: >= 2 characters and <= 50 characters

      Default value: simple

      The type of the tag

    • ]
    • children string[]

      The list of child feature names. This is an experimental field and may change.

    • dependencies object[]

      The list of parent dependencies. This is an experimental field and may change.

    • Array [
    • feature string required

      The name of the parent feature

    • enabled boolean

      Whether the parent feature is enabled or not

    • variants string[]

      The list of variants the parent feature should resolve to. Only valid when feature is enabled.

    • ]
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/update-feedback.html b/reference/api/unleash/update-feedback.html index c53e0d0081..ab9c824eb4 100644 --- a/reference/api/unleash/update-feedback.html +++ b/reference/api/unleash/update-feedback.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Update Unleash feedback

    PUT /api/admin/feedback/:id

    Updates the feedback with the provided ID. Only provided fields are updated. Fields left out are left untouched. Must be called with a token with an identifiable user (either from being sent from the UI or from using a PAT).

    Request​

    Path Parameters

    • id string required

    Body

    required

    feedbackUpdateSchema

    • userId integer

      The ID of the user that gave the feedback.

    • neverShow boolean

      true if the user has asked never to see this feedback questionnaire again.

    • given date-time nullable

      When this feedback was given

    Responses

    feedbackResponseSchema

    Schema
    • userId integer

      The ID of the user that gave the feedback.

    • neverShow boolean

      true if the user has asked never to see this feedback questionnaire again.

    • given date-time nullable

      When this feedback was given

    • feedbackId string

      The name of the feedback session

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/update-group.html b/reference/api/unleash/update-group.html index 1cb6e01b8a..c89e01a260 100644 --- a/reference/api/unleash/update-group.html +++ b/reference/api/unleash/update-group.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Update a group

    PUT /api/admin/groups/:groupId

    Update existing user group by group id. It overrides previous group details.

    Request​

    Path Parameters

    • groupId string required

    Body

    required

    createGroupSchema

    • name string required

      The name of the group

    • description string nullable

      A custom description of the group

    • mappingsSSO string[]

      A list of SSO groups that should map to this Unleash group

    • rootRole number nullable

      A role id that is used as the root role for all users in this group. This can be either the id of the Viewer, Editor or Admin role.

    • users object[]

      A list of users belonging to this group

    • Array [
    • user objectrequired

      A minimal user object

    • id integer required

      The user id

    • ]
    Responses

    groupSchema

    Schema
    • id integer

      The group id

    • name string required

      The name of the group

    • description string nullable

      A custom description of the group

    • mappingsSSO string[]

      A list of SSO groups that should map to this Unleash group

    • rootRole number nullable

      A role id that is used as the root role for all users in this group. This can be either the id of the Viewer, Editor or Admin role.

    • createdBy string nullable

      A user who created this group

    • createdAt date-time nullable

      When was this group created

    • users object[]

      A list of users belonging to this group

    • Array [
    • joinedAt date-time

      The date when the user joined the group

    • createdBy string nullable

      The username of the user who added this user to this group

    • user objectrequired

      An Unleash user

    • id integer required

      The user id

    • isAPI boolean deprecated

      (Deprecated): Used internally to know which operations the user should be allowed to perform

    • name string nullable

      Name of the user

    • email string

      Email of the user

    • username string nullable

      A unique username for the user

    • imageUrl string

      URL used for the userprofile image

    • inviteLink string

      If the user is actively inviting other users, this is the link that can be shared with other users

    • loginAttempts integer

      How many unsuccessful attempts at logging in has the user made

    • emailSent boolean

      Is the welcome email sent to the user or not

    • rootRole integer

      Which root role this user is assigned

    • seenAt date-time nullable

      The last time this user logged in

    • createdAt date-time

      The user was created at this time

    • accountType string

      A user is either an actual User or a Service Account

    • permissions string[]

      Deprecated

    • ]
    • projects string[]

      A list of projects where this group is used

    • userCount integer

      The number of users that belong to this group

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/update-license.html b/reference/api/unleash/update-license.html index 46eebca185..97efd82210 100644 --- a/reference/api/unleash/update-license.html +++ b/reference/api/unleash/update-license.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Set a new Unleash license.

    POST /api/admin/license

    Set a new Unleash license. Only available for self-hosted Enterprise customers.

    Request​

    Body

    required

    licenseUpdateSchema

    • token string required

      The actual license token.

    Responses

    The resource was successfully created.

    Response Headers
    • location string

      The location of the newly created resource.

    Schema
    • token string required

      The actual license token.

    • customer string

      Name of the customer that owns the license. This is the name of the company that purchased the license.

    • plan string

      Name of plan that the license is for.

    • seats number

      Number of seats in the license.

    • expireAt date-time

      Date when the license expires.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/update-project-change-request-config.html b/reference/api/unleash/update-project-change-request-config.html index 6efa69a1ed..da7976e399 100644 --- a/reference/api/unleash/update-project-change-request-config.html +++ b/reference/api/unleash/update-project-change-request-config.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Updates change request configuration for an environment in the project

    PUT /api/admin/projects/:projectId/environments/:environment/change-requests/config

    This endpoint will change the change request configuration for a given environment, set it to either on/off and optionally configure the number of approvals needed. The minimum number of approvals is 1 and the maximum number is 10. If you provide a number higher than 10 or lower than 1, Unleash will clamp it to the allowed range.

    Request​

    Path Parameters

    • projectId string required
    • environment string required

    Body

    required

    updateChangeRequestEnvironmentConfigSchema

    • changeRequestsEnabled boolean required

      true if change requests should be enabled, otherwise false.

    • requiredApprovals integer

      The number of approvals required before a change request can be applied in this environment.

    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/update-project-enterprise-settings.html b/reference/api/unleash/update-project-enterprise-settings.html index 6eee9f72c9..4456559faf 100644 --- a/reference/api/unleash/update-project-enterprise-settings.html +++ b/reference/api/unleash/update-project-enterprise-settings.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Update project enterprise settings

    PUT /api/admin/projects/:projectId/settings

    Update project enterprise settings with new values. Any fields not provided are ignored.

    Request​

    Path Parameters

    • projectId string required

    Body

    required

    updateProjectEnterpriseSettingsSchema

    • mode string

      Possible values: [open, protected, private]

      A mode of the project affecting what actions are possible in this project

    • featureNaming object

      Create a feature naming pattern

    • pattern string nullable required

      A JavaScript regular expression pattern, without the start and end delimiters. Optional flags are not allowed.

    • example string nullable

      An example of a feature name that matches the pattern. Must itself match the pattern supplied.

    • description string nullable

      A description of the pattern in a human-readable format. Will be shown to users when they create a new feature flag.

    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/update-project.html b/reference/api/unleash/update-project.html index 0139b65153..cdaf8da07d 100644 --- a/reference/api/unleash/update-project.html +++ b/reference/api/unleash/update-project.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Update project

    PUT /api/admin/projects/:projectId

    Update a project with new configuration. Any fields not provided are ignored.

    Request​

    Path Parameters

    • projectId string required

    Body

    required

    updateProjectSchema

    • name string required

      The new name of the project

    • description string

      A new description for the project

    • mode string

      Possible values: [open, protected, private]

      A mode of the project affecting what actions are possible in this project

    • defaultStickiness string

      A default stickiness for the project affecting the default stickiness value for variants and Gradual Rollout strategy

    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/update-public-signup-token.html b/reference/api/unleash/update-public-signup-token.html index d633f6d719..af9051ea66 100644 --- a/reference/api/unleash/update-public-signup-token.html +++ b/reference/api/unleash/update-public-signup-token.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Update a public signup token

    PUT /api/admin/invite-link/tokens/:token

    Update information about a specific token. The :token part of the URL should be the token's secret.

    Request​

    Path Parameters

    • token string required

    Body

    required

    publicSignupTokenUpdateSchema

    • expiresAt date-time

      The token's expiration date.

    • enabled boolean

      Whether the token is active or not.

    Responses

    publicSignupTokenSchema

    Schema
    • secret string required

      The actual value of the token. This is the part that is used by Unleash to create an invite link

    • url string nullable required

      The public signup link for the token. Users who follow this link will be taken to a signup page where they can create an Unleash user.

    • name string required

      The token's name. Only for displaying in the UI

    • enabled boolean required

      Whether the token is active. This property will always be false for a token that has expired.

    • expiresAt date-time required

      The time when the token will expire.

    • createdAt date-time required

      When the token was created.

    • createdBy string nullable required

      The creator's email or username

    • users object[]nullable

      Array of users that have signed up using the token.

    • Array [
    • id integer required

      The user id

    • isAPI boolean deprecated

      (Deprecated): Used internally to know which operations the user should be allowed to perform

    • name string nullable

      Name of the user

    • email string

      Email of the user

    • username string nullable

      A unique username for the user

    • imageUrl string

      URL used for the userprofile image

    • inviteLink string

      If the user is actively inviting other users, this is the link that can be shared with other users

    • loginAttempts integer

      How many unsuccessful attempts at logging in has the user made

    • emailSent boolean

      Is the welcome email sent to the user or not

    • rootRole integer

      Which root role this user is assigned

    • seenAt date-time nullable

      The last time this user logged in

    • createdAt date-time

      The user was created at this time

    • accountType string

      A user is either an actual User or a Service Account

    • permissions string[]

      Deprecated

    • ]
    • role objectrequired

      A role holds permissions to allow Unleash to decide what actions a role holder is allowed to perform

    • id integer required

      The role id

    • type string required

      A role can either be a global root role (applies to all projects) or a project role

    • name string required

      The name of the role

    • description string

      A more detailed description of the role and what use it's intended for

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/update-role.html b/reference/api/unleash/update-role.html index 4e2a583bdc..b3b52bd055 100644 --- a/reference/api/unleash/update-role.html +++ b/reference/api/unleash/update-role.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Update a role

    PUT /api/admin/roles/:roleId

    Update a custom role by role id

    Request​

    Path Parameters

    • roleId string required

    Body

    required

    createRoleWithPermissionsSchema

      anyOf
    • name string required

      The name of the custom role

    • description string

      A more detailed description of the custom role and what use it's intended for

    • type string

      Possible values: [root-custom, custom]

      Custom root roles (type=root-custom) are root roles with a custom set of permissions. Custom project roles (type=custom) contain a specific set of permissions for project resources.

    • permissions object[]

      A list of permissions assigned to this role

    • Array [
    • name string required

      The name of the permission

    • environment string

      The environments of the permission if the permission is environment specific

    • ]
    Responses

    roleWithVersionSchema

    Schema
    • version integer required

      Possible values: >= 1

      The version of this schema

    • roles objectrequired

      A role holds permissions to allow Unleash to decide what actions a role holder is allowed to perform

    • id integer required

      The role id

    • type string required

      A role can either be a global root role (applies to all projects) or a project role

    • name string required

      The name of the role

    • description string

      A more detailed description of the role and what use it's intended for

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/update-segment.html b/reference/api/unleash/update-segment.html index e004576ee6..a77363a5df 100644 --- a/reference/api/unleash/update-segment.html +++ b/reference/api/unleash/update-segment.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Update segment by id

    PUT /api/admin/segments/:id

    Updates the content of the segment with the provided payload. Any fields not specified will be left untouched.

    Request​

    Path Parameters

    • id string required
    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/update-service-account.html b/reference/api/unleash/update-service-account.html index f186559588..65ba4e83cf 100644 --- a/reference/api/unleash/update-service-account.html +++ b/reference/api/unleash/update-service-account.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Update a service account.

    PUT /api/admin/service-account/:id

    Updates an existing service account identified by its id.

    Request​

    Path Parameters

    • id string required

    Body

    required

    updateServiceAccountSchema

    • name string

      The name of the service account

    • rootRole integer

      The id of the root role for the service account

    • property name* any

      Describes the properties required to update a service account

    Responses

    serviceAccountSchema

    Schema
    • id number required

      The service account id

    • isAPI boolean deprecated

      Deprecated: for internal use only, should not be exposed through the API

    • name string

      The name of the service account

    • email string deprecated

      Deprecated: service accounts don't have emails associated with them

    • username string

      The service account username

    • imageUrl string

      The service account image url

    • inviteLink string deprecated

      Deprecated: service accounts cannot be invited via an invitation link

    • loginAttempts number deprecated

      Deprecated: service accounts cannot log in to Unleash

    • emailSent boolean deprecated

      Deprecated: internal use only

    • rootRole integer

      The root role id associated with the service account

    • seenAt date-time nullable deprecated

      Deprecated. This property is always null. To find out when a service account was last seen, check its tokens list and refer to each token's lastSeen property instead.

    • createdAt date-time

      The service account creation date

    • tokens object[]

      The list of tokens associated with the service account

    • Array [
    • id integer

      Possible values: >= 1

      The unique identification number for this Personal Access Token. (This property is set by Unleash when the token is created and cannot be set manually: if you provide a value when creating a PAT, Unleash will ignore it.)

    • secret string

      The token used for authentication. (This property is set by Unleash when the token is created and cannot be set manually: if you provide a value when creating a PAT, Unleash will ignore it.)

    • expiresAt date-time

      The token's expiration date.

    • createdAt date-time

      When the token was created. (This property is set by Unleash when the token is created and cannot be set manually: if you provide a value when creating a PAT, Unleash will ignore it.)

    • seenAt date-time nullable

      When the token was last seen/used to authenticate with. null if it has not been used yet. (This property is set by Unleash when the token is created and cannot be set manually: if you provide a value when creating a PAT, Unleash will ignore it.)

    • ]
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/update-sort-order.html b/reference/api/unleash/update-sort-order.html index 29de6fd696..b533859ffb 100644 --- a/reference/api/unleash/update-sort-order.html +++ b/reference/api/unleash/update-sort-order.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Update environment sort orders

    PUT /api/admin/environments/sort-order

    Updates sort orders for the named environments. Environments not specified are unaffected.

    Request​

    Body

    required

    sortOrderSchema

    • property name* integer

      Sort order for the object whose ID is the key used for this property.

    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/update-splash-settings.html b/reference/api/unleash/update-splash-settings.html index 9c66520cee..9c348fbe9e 100644 --- a/reference/api/unleash/update-splash-settings.html +++ b/reference/api/unleash/update-splash-settings.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Update splash settings

    POST /api/admin/splash/:id

    This operation updates splash settings for a user, indicating that they have seen a particualar splash screen.

    Request​

    Path Parameters

    • id string required
    Responses

    splashResponseSchema

    Schema
    • userId integer required

      The ID of the user that was shown the splash screen.

    • splashId string required

      The ID of the splash screen that was shown.

    • seen boolean required

      Indicates whether the user has seen the splash screen or not.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/update-strategy.html b/reference/api/unleash/update-strategy.html index 32f1dcbc92..95e8f100f1 100644 --- a/reference/api/unleash/update-strategy.html +++ b/reference/api/unleash/update-strategy.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Update a strategy type

    PUT /api/admin/strategies/:name

    Updates the specified strategy type. Any properties not specified in the request body are left untouched.

    Request​

    Path Parameters

    • name string required

    Body

    required

    updateStrategySchema

    • description string

      A description of the strategy type.

    • parameters object[]required

      The parameter list lets you pass arguments to your custom activation strategy. These will be made available to your custom strategy implementation.

    • Array [
    • name string required

      The name of the parameter

    • type string required

      Possible values: [string, percentage, list, number, boolean]

    • description string

      A description of this strategy parameter. Use this to indicate to the users what the parameter does.

    • required boolean

      Whether this parameter must be configured when using the strategy. Defaults to false

    • ]
    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/update-tag-type.html b/reference/api/unleash/update-tag-type.html index 38580eb31c..504520d074 100644 --- a/reference/api/unleash/update-tag-type.html +++ b/reference/api/unleash/update-tag-type.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Update a tag type

    PUT /api/admin/tag-types/:name

    Update the configuration for the specified tag type.

    Request​

    Path Parameters

    • name string required

    Body

    required

    updateTagTypeSchema

    • description string

      The description of the tag type.

    • icon string

      The icon of the tag type.

    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/update-tags.html b/reference/api/unleash/update-tags.html index fbb4f94edb..aae0924c45 100644 --- a/reference/api/unleash/update-tags.html +++ b/reference/api/unleash/update-tags.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Updates multiple tags for a feature.

    PUT /api/admin/features/:featureName/tags

    Receives a list of tags to add and a list of tags to remove that are mandatory but can be empty. All tags under addedTags are first added to the feature and then all tags under removedTags are removed from the feature.

    Request​

    Path Parameters

    • featureName string required

    Body

    required

    updateTagsSchema

    • addedTags object[]required

      Tags to add to the feature.

    • Array [
    • value string required

      Possible values: >= 2 characters and <= 50 characters

      The value of the tag

    • type string required

      Possible values: >= 2 characters and <= 50 characters

      Default value: simple

      The type of the tag

    • ]
    • removedTags object[]required

      Tags to remove from the feature.

    • Array [
    • value string required

      Possible values: >= 2 characters and <= 50 characters

      The value of the tag

    • type string required

      Possible values: >= 2 characters and <= 50 characters

      Default value: simple

      The type of the tag

    • ]
    Responses

    The resource was successfully created.

    Response Headers
    • location string

      The location of the newly created resource.

    Schema
    • version integer required

      The version of the schema used to model the tags.

    • tags object[]required

      A list of tags.

    • Array [
    • value string required

      Possible values: >= 2 characters and <= 50 characters

      The value of the tag

    • type string required

      Possible values: >= 2 characters and <= 50 characters

      Default value: simple

      The type of the tag

    • ]
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/update-user.html b/reference/api/unleash/update-user.html index 96954a3e37..0191c8fdf8 100644 --- a/reference/api/unleash/update-user.html +++ b/reference/api/unleash/update-user.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Update a user

    PUT /api/admin/user-admin/:id

    Only the explicitly specified fields get updated.

    Request​

    Path Parameters

    • id string required

    Body

    required

    updateUserSchema

    • email string

      The user's email address. Must be provided if username is not provided.

    • name string

      The user's name (not the user's username).

    • rootRole object

      The role to assign to the user. Can be either the role's ID or its unique name.

      oneOf
    • integer
    Responses

    createUserResponseSchema

    Schema
    • id integer required

      The user id

    • isAPI boolean deprecated

      (Deprecated): Used internally to know which operations the user should be allowed to perform

    • name string nullable

      Name of the user

    • email string

      Email of the user

    • username string nullable

      A unique username for the user

    • imageUrl string

      URL used for the userprofile image

    • inviteLink string

      If the user is actively inviting other users, this is the link that can be shared with other users

    • loginAttempts integer

      How many unsuccessful attempts at logging in has the user made

    • emailSent boolean

      Is the welcome email sent to the user or not

    • rootRole object

      Which root role this user is assigned. Usually a numeric role ID, but can be a string when returning newly created user with an explicit string role.

      oneOf
    • integer
    • seenAt date-time nullable

      The last time this user logged in

    • createdAt date-time

      The user was created at this time

    • accountType string

      A user is either an actual User or a Service Account

    • permissions string[]

      Deprecated

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/users.html b/reference/api/unleash/users.html index d2bb4095b0..25947e5479 100644 --- a/reference/api/unleash/users.html +++ b/reference/api/unleash/users.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Users

    Manage users and passwords.

    - + \ No newline at end of file diff --git a/reference/api/unleash/validate-archive-features.html b/reference/api/unleash/validate-archive-features.html index 6e057119b1..d049a214f5 100644 --- a/reference/api/unleash/validate-archive-features.html +++ b/reference/api/unleash/validate-archive-features.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Validates archive features

    POST /api/admin/projects/:projectId/archive/validate

    This endpoint return info about the archive features impact.

    Request​

    Path Parameters

    • projectId string required

    Body

    required

    batchFeaturesSchema

    • features string[] required

      List of feature toggle names

    Responses

    validateArchiveFeaturesSchema

    Schema
    • parentsWithChildFeatures string[] required

      List of parent features that would orphan child features that are not part of the archive operation

    • hasDeletedDependencies boolean required

      Whether any dependencies will be deleted as part of archive

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/validate-constraint.html b/reference/api/unleash/validate-constraint.html index 85e6875f1b..ebd0a73ab2 100644 --- a/reference/api/unleash/validate-constraint.html +++ b/reference/api/unleash/validate-constraint.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Validate constraint

    POST /api/admin/constraints/validate

    Validates a constraint definition. Checks whether the context field exists and whether the applied configuration is valid. Additional properties are not allowed on data objects that you send to this endpoint.

    Request​

    Body

    required

    constraintSchema

    • contextName string required

      The name of the context field that this constraint should apply to.

    • operator string required

      Possible values: [NOT_IN, IN, STR_ENDS_WITH, STR_STARTS_WITH, STR_CONTAINS, NUM_EQ, NUM_GT, NUM_GTE, NUM_LT, NUM_LTE, DATE_AFTER, DATE_BEFORE, SEMVER_EQ, SEMVER_GT, SEMVER_LT]

      The operator to use when evaluating this constraint. For more information about the various operators, refer to the strategy constraint operator documentation.

    • caseInsensitive boolean

      Default value: false

      Whether the operator should be case sensitive or not. Defaults to false (being case sensitive).

    • inverted boolean

      Default value: false

      Whether the result should be negated or not. If true, will turn a true result into a false result and vice versa.

    • values string[]

      The context values that should be used for constraint evaluation. Use this property instead of value for properties that accept multiple values.

    • value string

      The context value that should be used for constraint evaluation. Use this property instead of values for properties that only accept single values.

    Responses

    The constraint is valid

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/validate-environment-name.html b/reference/api/unleash/validate-environment-name.html index 51559630e5..3ad92d3b06 100644 --- a/reference/api/unleash/validate-environment-name.html +++ b/reference/api/unleash/validate-environment-name.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Validates if an environment name exists

    POST /api/admin/environments/validate

    Uses the name provided in the body of the request to validate if the given name exists or not

    Request​

    Body

    required

    nameSchema

    • name string required

      The name of the represented object.

    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/validate-feature.html b/reference/api/unleash/validate-feature.html index 06e10c6586..f1f07757b0 100644 --- a/reference/api/unleash/validate-feature.html +++ b/reference/api/unleash/validate-feature.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Validate a feature toggle name.

    POST /api/admin/features/validate

    Validates a feature toggle name: checks whether the name is URL-friendly and whether a feature with the given name already exists. Returns 200 if the feature name is compliant and unused.

    Request​

    Body

    required

    validateFeatureSchema

    • name string required

      The feature name to validate.

    • projectId string nullable

      The id of the project that the feature flag will belong to. If the target project has a feature naming pattern defined, the name will be validated against that pattern.

    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/validate-import.html b/reference/api/unleash/validate-import.html index d61aa7bdea..56d7a7729f 100644 --- a/reference/api/unleash/validate-import.html +++ b/reference/api/unleash/validate-import.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Validate feature import data

    POST /api/admin/features-batch/validate

    Validates a feature toggle data set. Checks whether the data can be imported into the specified project and environment. The returned value is an object that contains errors, warnings, and permissions required to perform the import, as described in the import documentation.

    Request​

    Body

    required

    importTogglesSchema

    • project string required

      The exported project

    • environment string required

      The exported environment

    • data objectrequired

      The result of the export operation, providing you with the feature toggle definitions, strategy definitions and the rest of the elements relevant to the features (tags, environments etc.)

    • features object[]required

      All the exported features.

    • Array [
    • name string required

      Unique feature name

    • type string

      Type of the toggle e.g. experiment, kill-switch, release, operational, permission

    • description string nullable

      Detailed description of the feature

    • archived boolean

      true if the feature is archived

    • project string

      Name of the project the feature belongs to

    • enabled boolean

      true if the feature is enabled, otherwise false.

    • stale boolean

      true if the feature is stale based on the age and feature type, otherwise false.

    • favorite boolean

      true if the feature was favorited, otherwise false.

    • impressionData boolean

      true if the impression data collection is enabled for the feature, otherwise false.

    • createdAt date-time nullable

      The date the feature was created

    • archivedAt date-time nullable

      The date the feature was archived

    • lastSeenAt date-time nullable deprecated

      The date when metrics where last collected for the feature. This field is deprecated, use the one in featureEnvironmentSchema

    • environments object[]

      The list of environments where the feature can be used

    • Array [
    • name string required

      The name of the environment

    • featureName string

      The name of the feature

    • environment string

      The name of the environment

    • type string

      The type of the environment

    • enabled boolean required

      true if the feature is enabled for the environment, otherwise false.

    • sortOrder number

      The sort order of the feature environment in the feature environments list

    • variantCount number

      The number of defined variants

    • strategies object[]

      A list of activation strategies for the feature environment

    • Array [
    • id string

      A uuid for the feature strategy

    • name string required

      The name or type of strategy

    • title string nullable

      A descriptive title for the strategy

    • disabled boolean nullable

      A toggle to disable the strategy. defaults to false. Disabled strategies are not evaluated or returned to the SDKs

    • featureName string

      The name or feature the strategy is attached to

    • sortOrder number

      The order of the strategy in the list

    • segments number[]

      A list of segment ids attached to the strategy

    • constraints object[]

      A list of the constraints attached to the strategy. See https://docs.getunleash.io/reference/strategy-constraints

    • Array [
    • contextName string required

      The name of the context field that this constraint should apply to.

    • operator string required

      Possible values: [NOT_IN, IN, STR_ENDS_WITH, STR_STARTS_WITH, STR_CONTAINS, NUM_EQ, NUM_GT, NUM_GTE, NUM_LT, NUM_LTE, DATE_AFTER, DATE_BEFORE, SEMVER_EQ, SEMVER_GT, SEMVER_LT]

      The operator to use when evaluating this constraint. For more information about the various operators, refer to the strategy constraint operator documentation.

    • caseInsensitive boolean

      Default value: false

      Whether the operator should be case sensitive or not. Defaults to false (being case sensitive).

    • inverted boolean

      Default value: false

      Whether the result should be negated or not. If true, will turn a true result into a false result and vice versa.

    • values string[]

      The context values that should be used for constraint evaluation. Use this property instead of value for properties that accept multiple values.

    • value string

      The context value that should be used for constraint evaluation. Use this property instead of values for properties that only accept single values.

    • ]
    • variants object[]

      Strategy level variants

    • Array [
    • name string required

      The variant name. Must be unique for this feature toggle

    • weight integer required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is an integer between 0 and 1000. See the section on variant weights for more information

    • weightType string required

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000. Refer to the variant weight documentation.

    • stickiness string required

      The stickiness to use for distribution of this variant. Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • ]
    • parameters object

      A list of parameters for a strategy

    • property name* string
    • ]
    • variants object[]

      A list of variants for the feature environment

    • Array [
    • name string required

      The variants name. Is unique for this feature toggle

    • weight number required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is a number between 0 and 1000. See the section on variant weights for more information

    • weightType string

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000

    • stickiness string

      Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • overrides object[]

      Overrides assigning specific variants to specific users. The weighting system automatically assigns users to specific groups for you, but any overrides in this list will take precedence.

    • Array [
    • contextName string required

      The name of the context field used to determine overrides

    • values string[] required

      Which values that should be overriden

    • ]
    • ]
    • lastSeenAt date-time nullable

      The date when metrics where last collected for the feature environment

    • hasStrategies boolean

      Whether the feature has any strategies defined.

    • hasEnabledStrategies boolean

      Whether the feature has any enabled strategies defined.

    • ]
    • variants object[]deprecated

      The list of feature variants

    • Array [
    • name string required

      The variants name. Is unique for this feature toggle

    • weight number required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is a number between 0 and 1000. See the section on variant weights for more information

    • weightType string

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000

    • stickiness string

      Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • overrides object[]

      Overrides assigning specific variants to specific users. The weighting system automatically assigns users to specific groups for you, but any overrides in this list will take precedence.

    • Array [
    • contextName string required

      The name of the context field used to determine overrides

    • values string[] required

      Which values that should be overriden

    • ]
    • ]
    • strategies object[] deprecated

      This is a legacy field that will be deprecated

    • tags object[]nullable

      The list of feature tags

    • Array [
    • value string required

      Possible values: >= 2 characters and <= 50 characters

      The value of the tag

    • type string required

      Possible values: >= 2 characters and <= 50 characters

      Default value: simple

      The type of the tag

    • ]
    • children string[]

      The list of child feature names. This is an experimental field and may change.

    • dependencies object[]

      The list of parent dependencies. This is an experimental field and may change.

    • Array [
    • feature string required

      The name of the parent feature

    • enabled boolean

      Whether the parent feature is enabled or not

    • variants string[]

      The list of variants the parent feature should resolve to. Only valid when feature is enabled.

    • ]
    • ]
    • featureStrategies object[]required

      All strategy instances that are used by the exported features in the features list.

    • Array [
    • id string

      A uuid for the feature strategy

    • name string required

      The name or type of strategy

    • title string nullable

      A descriptive title for the strategy

    • disabled boolean nullable

      A toggle to disable the strategy. defaults to false. Disabled strategies are not evaluated or returned to the SDKs

    • featureName string

      The name or feature the strategy is attached to

    • sortOrder number

      The order of the strategy in the list

    • segments number[]

      A list of segment ids attached to the strategy

    • constraints object[]

      A list of the constraints attached to the strategy. See https://docs.getunleash.io/reference/strategy-constraints

    • Array [
    • contextName string required

      The name of the context field that this constraint should apply to.

    • operator string required

      Possible values: [NOT_IN, IN, STR_ENDS_WITH, STR_STARTS_WITH, STR_CONTAINS, NUM_EQ, NUM_GT, NUM_GTE, NUM_LT, NUM_LTE, DATE_AFTER, DATE_BEFORE, SEMVER_EQ, SEMVER_GT, SEMVER_LT]

      The operator to use when evaluating this constraint. For more information about the various operators, refer to the strategy constraint operator documentation.

    • caseInsensitive boolean

      Default value: false

      Whether the operator should be case sensitive or not. Defaults to false (being case sensitive).

    • inverted boolean

      Default value: false

      Whether the result should be negated or not. If true, will turn a true result into a false result and vice versa.

    • values string[]

      The context values that should be used for constraint evaluation. Use this property instead of value for properties that accept multiple values.

    • value string

      The context value that should be used for constraint evaluation. Use this property instead of values for properties that only accept single values.

    • ]
    • variants object[]

      Strategy level variants

    • Array [
    • name string required

      The variant name. Must be unique for this feature toggle

    • weight integer required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is an integer between 0 and 1000. See the section on variant weights for more information

    • weightType string required

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000. Refer to the variant weight documentation.

    • stickiness string required

      The stickiness to use for distribution of this variant. Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • ]
    • parameters object

      A list of parameters for a strategy

    • property name* string
    • ]
    • featureEnvironments object[]

      Environment-specific configuration for all the features in the features list. Includes data such as whether the feature is enabled in the selected export environment, whether there are any variants assigned, etc.

    • Array [
    • name string required

      The name of the environment

    • featureName string

      The name of the feature

    • environment string

      The name of the environment

    • type string

      The type of the environment

    • enabled boolean required

      true if the feature is enabled for the environment, otherwise false.

    • sortOrder number

      The sort order of the feature environment in the feature environments list

    • variantCount number

      The number of defined variants

    • strategies object[]

      A list of activation strategies for the feature environment

    • Array [
    • id string

      A uuid for the feature strategy

    • name string required

      The name or type of strategy

    • title string nullable

      A descriptive title for the strategy

    • disabled boolean nullable

      A toggle to disable the strategy. defaults to false. Disabled strategies are not evaluated or returned to the SDKs

    • featureName string

      The name or feature the strategy is attached to

    • sortOrder number

      The order of the strategy in the list

    • segments number[]

      A list of segment ids attached to the strategy

    • constraints object[]

      A list of the constraints attached to the strategy. See https://docs.getunleash.io/reference/strategy-constraints

    • Array [
    • contextName string required

      The name of the context field that this constraint should apply to.

    • operator string required

      Possible values: [NOT_IN, IN, STR_ENDS_WITH, STR_STARTS_WITH, STR_CONTAINS, NUM_EQ, NUM_GT, NUM_GTE, NUM_LT, NUM_LTE, DATE_AFTER, DATE_BEFORE, SEMVER_EQ, SEMVER_GT, SEMVER_LT]

      The operator to use when evaluating this constraint. For more information about the various operators, refer to the strategy constraint operator documentation.

    • caseInsensitive boolean

      Default value: false

      Whether the operator should be case sensitive or not. Defaults to false (being case sensitive).

    • inverted boolean

      Default value: false

      Whether the result should be negated or not. If true, will turn a true result into a false result and vice versa.

    • values string[]

      The context values that should be used for constraint evaluation. Use this property instead of value for properties that accept multiple values.

    • value string

      The context value that should be used for constraint evaluation. Use this property instead of values for properties that only accept single values.

    • ]
    • variants object[]

      Strategy level variants

    • Array [
    • name string required

      The variant name. Must be unique for this feature toggle

    • weight integer required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is an integer between 0 and 1000. See the section on variant weights for more information

    • weightType string required

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000. Refer to the variant weight documentation.

    • stickiness string required

      The stickiness to use for distribution of this variant. Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • ]
    • parameters object

      A list of parameters for a strategy

    • property name* string
    • ]
    • variants object[]

      A list of variants for the feature environment

    • Array [
    • name string required

      The variants name. Is unique for this feature toggle

    • weight number required

      Possible values: <= 1000

      The weight is the likelihood of any one user getting this variant. It is a number between 0 and 1000. See the section on variant weights for more information

    • weightType string

      Possible values: [variable, fix]

      Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000

    • stickiness string

      Stickiness is how Unleash guarantees that the same user gets the same variant every time

    • payload object

      Extra data configured for this variant

    • type string required

      Possible values: [json, csv, string, number]

      The type of the value. Commonly used types are string, number, json and csv.

    • value string required

      The actual value of payload

    • overrides object[]

      Overrides assigning specific variants to specific users. The weighting system automatically assigns users to specific groups for you, but any overrides in this list will take precedence.

    • Array [
    • contextName string required

      The name of the context field used to determine overrides

    • values string[] required

      Which values that should be overriden

    • ]
    • ]
    • lastSeenAt date-time nullable

      The date when metrics where last collected for the feature environment

    • hasStrategies boolean

      Whether the feature has any strategies defined.

    • hasEnabledStrategies boolean

      Whether the feature has any enabled strategies defined.

    • ]
    • contextFields object[]

      A list of all the context fields that are in use by any of the strategies in the featureStrategies list.

    • Array [
    • name string required

      The name of the context field

    • description string nullable

      The description of the context field.

    • stickiness boolean

      Does this context field support being used for stickiness calculations

    • sortOrder integer

      Used when sorting a list of context fields. Is also used as a tiebreaker if a list of context fields is sorted alphabetically.

    • createdAt date-time nullable

      When this context field was created

    • usedInFeatures integer nullable

      Number of projects where this context field is used in

    • usedInProjects integer nullable

      Number of projects where this context field is used in

    • legalValues object[]

      Allowed values for this context field schema. Can be used to narrow down accepted input

    • Array [
    • value string required

      The valid value

    • description string

      Describes this specific legal value

    • ]
    • ]
    • featureTags object[]

      A list of all the tags that have been applied to any of the features in the features list.

    • Array [
    • featureName string required

      The name of the feature this tag is applied to

    • tagType string

      The [type](https://docs.getunleash.io/reference/tags#tag-types tag types) of the tag

    • tagValue string required

      The value of the tag

    • type string deprecated

      The [type](https://docs.getunleash.io/reference/tags#tag-types tag types) of the tag. This property is deprecated and will be removed in a future version of Unleash. Superseded by the tagType property.

    • value string deprecated

      The value of the tag. This property is deprecated and will be removed in a future version of Unleash. Superseded by the tagValue property.

    • createdByUserId number nullable

      The id of the user who created this tag

    • ]
    • segments object[]

      A list of all the segments that are used by the strategies in the featureStrategies list.

    • Array [
    • id number required
    • name string required
    • ]
    • tagTypes object[]required

      A list of all of the tag types that are used in the featureTags list.

    • Array [
    • name string required

      The name of the tag type.

    • description string

      The description of the tag type.

    • icon string nullable

      The icon of the tag type.

    • ]
    • dependencies object[]

      A list of all the dependencies for features in features list.

    • Array [
    • feature string required

      The name of the child feature.

    • dependencies object[]required

      List of parent features for the child feature

    • Array [
    • feature string required

      The name of the feature we depend on.

    • enabled boolean

      Whether the parent feature should be enabled. When false variants are ignored. true by default.

    • variants string[]

      The list of variants the parent feature should resolve to. Leave empty when you only want to check the enabled status.

    • ]
    • ]
    Responses

    importTogglesValidateSchema

    Schema
    • errors object[]required

      A list of errors that prevent the provided data from being successfully imported.

    • Array [
    • message string required

      The validation error message

    • affectedItems string[] required

      The items affected by this error message

    • ]
    • warnings object[]required

      A list of warnings related to the provided data.

    • Array [
    • message string required

      The validation error message

    • affectedItems string[] required

      The items affected by this error message

    • ]
    • permissions object[]

      Any additional permissions required to import the data. If the list is empty, you require no additional permissions beyond what your user already has.

    • Array [
    • message string required

      The validation error message

    • affectedItems string[] required

      The items affected by this error message

    • ]
    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/validate-password.html b/reference/api/unleash/validate-password.html index 664ad05901..0dd7b536b9 100644 --- a/reference/api/unleash/validate-password.html +++ b/reference/api/unleash/validate-password.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Validates password

    POST /auth/reset/validate-password

    Verifies that the password adheres to the Unleash password guidelines

    Request​

    Body

    required

    validatePasswordSchema

    • password string required

      The password to validate

    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/validate-project.html b/reference/api/unleash/validate-project.html index 089e2d5e2f..1032fa4838 100644 --- a/reference/api/unleash/validate-project.html +++ b/reference/api/unleash/validate-project.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Validate project ID

    POST /api/admin/projects/validate

    Validate a project ID against Unleash's rules

    Request​

    Body

    required

    validateProjectSchema

    • id string required

      The project ID to validate

    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/validate-public-signup-token.html b/reference/api/unleash/validate-public-signup-token.html index 1b242222f2..2ffd56b171 100644 --- a/reference/api/unleash/validate-public-signup-token.html +++ b/reference/api/unleash/validate-public-signup-token.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Validate signup token

    GET /invite/:token/validate

    Check whether the provided public sign-up token exists, has not expired and is enabled

    Request​

    Path Parameters

    • token string required
    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/validate-role.html b/reference/api/unleash/validate-role.html index 9b7b8fe30b..c8be3a30d7 100644 --- a/reference/api/unleash/validate-role.html +++ b/reference/api/unleash/validate-role.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Validate a role

    POST /api/admin/roles/validate

    Check if the role matches schema and has a unique name

    Request​

    Body

    required

    createRoleWithPermissionsSchema

      anyOf
    • name string required

      The name of the custom role

    • description string

      A more detailed description of the custom role and what use it's intended for

    • type string

      Possible values: [root-custom, custom]

      Custom root roles (type=root-custom) are root roles with a custom set of permissions. Custom project roles (type=custom) contain a specific set of permissions for project resources.

    • permissions object[]

      A list of permissions assigned to this role

    • Array [
    • name string required

      The name of the permission

    • environment string

      The environments of the permission if the permission is environment specific

    • ]
    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/validate-segment.html b/reference/api/unleash/validate-segment.html index a7995b1a41..ab4509c0c6 100644 --- a/reference/api/unleash/validate-segment.html +++ b/reference/api/unleash/validate-segment.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Validates if a segment name exists

    POST /api/admin/segments/validate

    Uses the name provided in the body of the request to validate if the given name exists or not

    Request​

    Body

    required

    nameSchema

    • name string required

      The name of the represented object.

    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/validate-tag-type.html b/reference/api/unleash/validate-tag-type.html index a68b6fb357..87e2d106ee 100644 --- a/reference/api/unleash/validate-tag-type.html +++ b/reference/api/unleash/validate-tag-type.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Validate a tag type

    POST /api/admin/tag-types/validate

    Validates whether if the body of the request is a valid tag and whether the a tag type with that name already exists or not. If a tag type with the same name exists, this operation will return a 409 status code.

    Request​

    Body

    required

    tagTypeSchema

    • name string required

      The name of the tag type.

    • description string

      The description of the tag type.

    • icon string nullable

      The icon of the tag type.

    Responses

    validateTagTypeSchema

    Schema
    • valid boolean required

      Whether or not the tag type is valid.

    • tagType objectrequired

      A tag type.

    • name string required

      The name of the tag type.

    • description string

      The description of the tag type.

    • icon string nullable

      The icon of the tag type.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/validate-token.html b/reference/api/unleash/validate-token.html index 5a7dcd2999..829a163ec8 100644 --- a/reference/api/unleash/validate-token.html +++ b/reference/api/unleash/validate-token.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Validates a token

    GET /auth/reset/validate

    If the token is valid returns the user that owns the token

    Request​

    Responses

    tokenUserSchema

    Schema
    • id integer required

      The user id

    • name string

      The name of the user

    • email string required

      The email of the user

    • token string required

      A token uniquely identifying a user

    • createdBy string nullable required

      A username or email identifying which user created this token

    • role objectrequired

      A role holds permissions to allow Unleash to decide what actions a role holder is allowed to perform

    • id integer required

      The role id

    • type string required

      A role can either be a global root role (applies to all projects) or a project role

    • name string required

      The name of the role

    • description string

      A more detailed description of the role and what use it's intended for

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/validate-user-password.html b/reference/api/unleash/validate-user-password.html index 61e71191bd..a5698e79c3 100644 --- a/reference/api/unleash/validate-user-password.html +++ b/reference/api/unleash/validate-user-password.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Validate password for a user

    POST /api/admin/user-admin/validate-password

    Validate the password strength. Minimum 10 characters, uppercase letter, number, special character.

    Request​

    Body

    required

    passwordSchema

    • password string required

      The new password to change or validate.

    • oldPassword string

      The old password the user is changing. This field is for the non-admin users changing their own password.

    • confirmPassword string

      The confirmation of the new password. This field is for the non-admin users changing their own password.

    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/api/unleash/validate.html b/reference/api/unleash/validate.html index db665ff3f2..1ecd0965b6 100644 --- a/reference/api/unleash/validate.html +++ b/reference/api/unleash/validate.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Validate a context field

    POST /api/admin/context/validate

    Check whether the provided data can be used to create a context field. If the data is not valid, ...?

    Request​

    Body

    required

    nameSchema

    • name string required

      The name of the represented object.

    Responses

    This response has no body.

    Loading...
    - + \ No newline at end of file diff --git a/reference/archived-toggles.html b/reference/archived-toggles.html index 04fb969eea..1380fa4f38 100644 --- a/reference/archived-toggles.html +++ b/reference/archived-toggles.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Archived Toggles

    You can archive a feature toggle when it is not needed anymore. You do this by clicking the "Archive" button on the feature toggle details view. When you archive a feature toggle, it will no longer be available to Client SDKs.

    The Unleash toggle view showing a focused &quot;archive feature toggle&quot; button, highlighted by a red arrow.

    Viewing archived toggles​

    Archived toggles are displayed in two places:

    1. The global toggle archive
    2. The containing project's toggle archive

    Unleash keeps a list of all archived toggles across projects in the global archive. The global archive is accessible from the global feature list.

    Additionally, each project keeps a list of all of its archived toggles. That is, when you archive a toggle, Unleash adds it to the containing project's archive.

    Reviving a feature toggle​

    If you want to re-use a feature toggle that you previously archived, you can revive in from the feature toggle archive. Click the "revive icon" to revive the toggle. Revived toggles will be in the disabled state when you re-enable them.

    A list of archived toggles. Each toggle displays its name and project it belongs to. Each toggle also has a &quot;revive&quot; button, as highlighted by a red arrow.

    Deleting a feature toggle​

    caution

    We generally discourage deleting feature toggles. The reason is that feature toggle names in Unleash are used as identifiers, so if you were to delete a toggle and then create a new one with the same name, the new one would reactivate any code that uses the old toggle.

    The only way to fully delete a feature toggle in Unleash is by using the archive. An archived toggle can be deleted via the API or by using the "delete feature toggle" button in the global or project-level archive.

    A list of archived toggles, each with a button to delete the toggle permanently.

    - + \ No newline at end of file diff --git a/reference/banners.html b/reference/banners.html index ec4b5622c9..40d22adc9e 100644 --- a/reference/banners.html +++ b/reference/banners.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Banners

    Availability

    Banners were introduced as a beta feature in Unleash 5.6 and are only available in Unleash Enterprise. We plan to make this feature generally available to all Enterprise users in Unleash 5.7.

    Banners allow you to configure and display internal messages that all users of your Unleash instance can see and interact with. They are displayed at the top of the Unleash UI, and can be configured to be interactive.

    Banners table

    A common use case could be to have some pre-configured banners that you can enable when you need to communicate something to your users. For example, you could have a banner that you enable when you're doing maintenance on your Unleash instance, and another banner that you enable when you're running a survey.

    In order to create and display a banner, you can follow the how to create and display banners guide.

    Banners can be enabled or disabled at any time. For more information on how to enable or disable a banner, see the section on displaying banners.

    OptionDescription
    EnabledWhether the banner is currently displayed to all users of your Unleash instance.

    Configuration​

    Banners can be configured with the following options:

    OptionDescription
    TypeThe type of banner, which controls the banner's color and its icon, if using the default icon option.
    IconThe icon displayed on the banner. This can be the default for the banner type, a custom icon, or hidden by selecting "None".
    MessageThe banner's message. Supports Markdown.

    Custom icon​

    To further personalize your banner, you can configure it with a custom icon.

    To use a custom icon in your banner:

    1. Select "Custom" in the icon dropdown.
    2. Enter the name of the desired Material Symbol.
      • For example, for the "Rocket Launch" icon, enter rocket_launch in the custom icon field.
    OptionDescription
    Custom iconThe custom icon to be displayed on the banner, using Material Symbols.

    You can set up an action for your banner:

    OptionDescription
    Banner actionThe action activated when a user interacts with the banner link. Defaults to "None". Options include a link or a dialog.

    When choosing the link action, a link will be displayed on the banner that directs users to a specified URL.

    The configured URL can be absolute, as in e.g. https://docs.getunleash.io/, or relative as in e.g. /admin/network. Absolute URLs will open in a new tab.

    OptionDescription
    URLThe URL to open when the user uses the banner link.
    TextThe text to display on the banner link.

    Dialog​

    When opting for a dialog action, an interactable link appears on the banner which opens a dialog with additional information.

    OptionDescription
    TextThe text to display on the banner link.
    Dialog titleThe title to display on the dialog.
    Dialog contentThe content to display on the dialog. Supports Markdown.

    Sticky banner​

    For added visibility, banners can be configured to be "sticky," ensuring they remain at the top of the Unleash UI, even after scrolling the page. This is useful for banners that you want to make sure that your users see and interact with.

    OptionDescription
    StickyWhether the banner is sticky on the screen when scrolling.
    - + \ No newline at end of file diff --git a/reference/change-requests.html b/reference/change-requests.html index 65c781707b..4d18715a02 100644 --- a/reference/change-requests.html +++ b/reference/change-requests.html @@ -20,7 +20,7 @@ - + @@ -30,7 +30,7 @@
    Skip to main content

    Change Requests

    Availability

    The change requests feature is an enterprise-only feature that was introduced in Unleash 4.19.0. The change requests for segments was introduced in Unleash 5.4.0.

    Feature flagging is a powerful tool, and because it's so powerful, you sometimes need to practice caution. The ability to have complete control over your production environment comes at the cost of the potential to make mistakes in production. Change requests were introduced in version 4.19.0 to alleviate this fear. Change requests allow you to group changes together and apply them to production at the same time, instead of applying changes directly to production. This allows you to make multiple changes to feature toggles and their configuration and status (on/off) all at once, reducing the risk of errors in production.

    Our goal is developer efficiency, but we also recognize that we have users and customers in highly regulated industries, governed by law and strict requirements. Therefore, we have added a capability to change requests that will allow you to enforce the 4 eyes principle.

    Change request configuration​

    The change request configuration can be set up per project, per environment. This means that you can have different change request configurations for different environments, such as production and development. This is useful because different environments may have different requirements, so you can customize the change request configuration to fit those requirements. However, this also means that you cannot change toggles across projects in the same change request.

    Currently there are two configuration options for change requests:

    • Enable change requests - This is a boolean value that enables or disables change requests for the project and environment.
    • Required approvals - This is an integer value that indicates how many approvals are required before a change request can be applied. Specific permissions are required to approve and apply change requests.

    The change request configuration can be set up in the project settings page:

    Change request configuration

    Change request flow​

    Once a change request flow is configured for a project and environment, you can no longer directly change the status of a toggle. Instead, you will be asked to put your changes into a draft. The change request flow handles the following scenarios:

    • Updating the status of a toggle in the environment
    • Adding a strategy to the feature toggle in the environment
    • Updating a strategy of a feature toggle in the environment
    • Deleting a strategy from a feature toggle in the environment

    The flow can be summarized as follows:

    Change request flow

    Once a change is added to a draft, the draft needs to be completed before another change request can be opened. The draft is personal to the user that created the change request draft, until it is sent for review. Once changes are added to draft, the user will have a banner in the top of the screen indicating that a draft exists. The state of a change request can be one of the following:

    • Draft - The change request is in draft mode, and can be edited by the user that created the draft.
    • In review - The change request is in review mode, and can be edited by the user that created the draft. If editing occurs, all current approvals are revoked
    • Approved - The change request has been approved by the required number of users.
    • Scheduled - The change request has been scheduled and will be applied at the scheduled time (unless there are conflicts, as described in the section on scheduling change requests).
    • Applied - The change request has been applied to the environment. The feature toggle configuration is updated.
    • Cancelled - The change request has been cancelled by the change request author or by an admin.
    • Rejected - The change request has been rejected by the reviewer or by an admin.

    Change request banner

    Once a change request is sent to review by the user who created it, it becomes available for everyone in the change request tab in the project.

    From here, you can navigate to the change request overview page. This page will give you information about the changes the change request contains, the state the change request is in, and what action needs to be taken next.

    Change request banner

    From here, if you have the correct permissions, you can approve and schedule or apply the change request. Once applied, the changes will be live in production.

    Scheduled changes​

    Availability

    Change request scheduling is currently in development and will be released in an upcoming version of Unleash. How the feature works (and as such, the contents of this subsection) can change before the feature is released.

    When a change request is approved, you can schedule it to be applied at a later time. This allows you to group changes together and apply them at a time that is convenient for you, such as during a maintenance window, or at a time when you know there will be less traffic to your application.

    Scheduled changes can be rescheduled, applied immediately, or rejected. They can not be edited or moved back to any of the previous states.

    Unleash will attempt to apply the changes at the scheduled time. However, if there are conflicts, the changes will not be applied and the change request will be marked as failed. Conflicts will occur if the change request contains changes that affect a flag that has been archived or a strategy that has been deleted.

    Be aware that if a strategy or variants affected by a scheduled change request are updated after the change request was scheduled, the application of the scheduled change request will overwrite those changes with the state in the scheduled change request.

    Unleash will warn you ahead of time if you make changes that conflict with a scheduled change request.

    If Unleash fails to apply a scheduled change request, the change request will remain in the scheduled state. You can reschedule it and try to apply it again later, or you can reject it.

    If a scheduled change request can not be applied, Unleash will send a notification to the person who scheduled it and to the person who created the change request.

    When a scheduled change request is applied, the person who scheduled it and the person who created it will each receive a notification.

    Edge cases: what happens when ...?​

    If the user who scheduled a change request is deleted from the Unleash users list before the scheduled time, the changes will not be applied. Instead, the schedule will be put into a special suspended state. A change request with suspended schedule will not be applied at its scheduled time. A user with the required permission can reschedule, apply, or reject the change request. Any of these actions will put the change request back into the regular flow.

    If a change request has been scheduled and change requests are then disabled for the project and environment, the change request will still be applied according to schedule. To prevent this, you can reject the scheduled change request.

    Different ways to schedule changes​

    Unleash currently offers two distinct ways to schedule changes. Each method has its own pros and cons, and you can also combine the methods for maximum flexibility.

    The first method is through scheduled change requests, as we have explained in the preceding sections. Scheduled change requests make it easy to see all the changes across multiple flags and strategies in one view and makes it easy to reschedule or reject them. However, because scheduled changes rely on flags and strategy configurations, conflicts can arise causing the schedule to fail.

    The second method uses Unleash's constraints and the DATE_AFTER operator to encode when changes should take effect. The pros of this method is that because these changes can be applied immediately, you won't run into any conflicts when they happen. The cons are that you'll need to apply the same constraints to all the parts that you want to change and that there is no easy way to see all the changes in one view. You also can not scheduled changes to a segment in this way. When using this option, we recommend that you use segments if you want to schedule multiple changes, so that their application time stays in sync.

    Another important distinction is how these changes affect your connected SDKs. If you use constraints (or segments), then any connected SDK will be aware of the schedule ahead of time. That means that even if the SDK can not connect to Unleash at the scheduled time, it will still activate the changes because it's encoded in its constraints. On the other hand, if you use change requests to schedule changes, SDKs must update their configuration after the scheduled time to be aware of the changes.

    Change request permissions​

    Change requests have their own set of environment-specific permissions that can be applied to custom project roles. These permissions let users

    • approve/reject change requests
    • apply change requests
    • skip the change request flow

    None of the predefined roles have any change request permissions, so you must create your own project roles to take advantage of change requests. In other words, even a user with the project "owner" role can not approve or apply change requests.

    There is no permission to create change requests: Anyone can create change requests, even Unleash users with the root viewer role. Change requests don't cause any changes until approved and applied by someone with the correct permissions.

    You can prevent non-project members from submitting change requests by setting a protected project collaboration mode.

    Circumventing change requests​

    The skip change requests permission allows users to bypass the change request flow. Users with this permission can change feature toggles directly (they are of course still limited by any other permissions they have).

    The skip change requests permission was designed to make it possible to quickly turn something off in the event that a feature release didn't go as expected or was causing issues.

    The skip change requests permission does not grant any other permissions, so to be allowed to do things as enabling/disabling a toggle, the user will still need the explicit permissions to do that too.

    In the UI non-admin users with skip change requests permission and explicit permission to perform the actual action will be able to make changes directly without change requests.

    Admin users will always see the change request UI so that they can test the change request flow. Admin users can however self-approve and self-apply their own changes.

    Change Request for segments​

    Changes to project segments (as opposed to global segments) also go through the change request process. This is to prevent a backdoor in the change request process.

    Since projects segments are not environment specific and change requests are always environment specific we allow to attach segment change to any environment with change requests enabled. When you make changes though the Change Request UI it will automatically select first environment with change requests enabled, giving priority to production environments.

    Changes to segments can be only circumvented by admin users through the API calls.

    - + \ No newline at end of file diff --git a/reference/custom-activation-strategies.html b/reference/custom-activation-strategies.html index 6b57257b76..4fb5d29142 100644 --- a/reference/custom-activation-strategies.html +++ b/reference/custom-activation-strategies.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Custom Activation Strategies

    tip

    This document is a reference for custom activation strategies. If you're looking for a guide on how to use them, see the how to use custom strategies guide.

    Custom activation strategies should be considered an advanced feature. In most cases strategy constraints provides enough control without the additional complexity.

    Custom activation strategies let you define your own activation strategies to use with Unleash. When the built-in activation strategies aren't enough, custom activation strategies are there to provide you with the flexibility you need.

    Custom activation strategies work exactly like the built-in activation strategies when working in the admin UI.

    Definition​

    A strategy creation form. It has fields labeled &quot;strategy name&quot; — &quot;TimeStamp&quot; — and &quot;description&quot; — &quot;activate toggle after a given timestamp&quot;. It also has fields for a parameter named &quot;enableAfter&quot;. The parameter is of type &quot;string&quot; and the parameter description is &quot;Expected format: YYYY-MM-DD HH:MM&quot;. The parameter is required.

    You define custom activation strategies on your Unleash instance, either via the admin UI or via the API. A strategy contains:

    • A strategy name: You'll use this to refer to the strategy in the UI and in code. The strategy name should make it easy to understand what the strategy does. For instance, if a strategy uses contact numbers to determine whether a feature should be enabled, then ContactNumbers would be a good name.
    • An optional description: Use this to describe what the strategy should do.
    • An optional list of parameters: The parameter list lets you pass arguments to your custom activation strategy. These will be made available to your custom strategy implementation. How you interact with them differs between SDKs, but refer to the Node.js example in the how-to guide for a rough idea.

    The strategy name is the only required parameter, but adding a good description will make it easier to remember what a strategy should do. The list of parameters lets you pass data from the Unleash instance to the strategy implementation.

    Parameters​

    A strategy with five parameters, one of each type.

    Parameters let you provide arguments to your strategy that it can access for evaluation. When creating a strategy, each parameter can be either required or optional. This marking is to help the user understand what they need to fill out; they can still save the strategy without filling out a required field.

    Each parameter consists of three parts:

    • a name: must be unique among the strategy's parameters.
    • an optional description: describe the purpose or format of the parameter.
    • a parameter type: dictates the kind of input field the user will see in the admin UI and the type of the value in the implementation code.

    Parameter types​

    Each parameter has one of five different parameter types. A parameter's type impacts the kind of controls shown in the admin UI and how it's represented in code.

    The below table lists the types and how they're represented in the JSON payload returned from the Unleash server. When parsed, the exact types will vary based on your programming language's type system.

    All values have an empty string ("") as the default value. As such, if you don't interact with a control or otherwise set a value, the value will be an empty string.

    type namecode representationexample valueUI control
    stringstring"a string"A standard input field
    percentagea string representing a number between 0 and 100 (inclusive)"99"A value slider
    liststring (values are comma-separated)"one,two"A multi-input text field
    numberstring"123"A numeric text field
    booleana string: one of "true" or "false""true"An on/off toggle

    Implementation​

    note

    If you have not implemented the strategy in your client SDK, the check will always return false because the client doesn't recognize the strategy.

    While custom strategies are defined on the Unleash server, they must be implemented on the client. All official Unleash client SDKs provide a way for you to implement custom strategies. You should refer to the individual SDK's documentation for specifics, but for an example, you can have a look at the Node.js client implementation section in the how to use custom strategies guide.

    The exact method for implementing custom strategies will vary between SDKs, but the server SDKs follow the same patterns. For front-end client SDKs (Android, JavaScript, React, iOS, Flutter), the custom activation strategy must be implemented in the Unleash Proxy.

    When implementing a strategy in your client, you will get access to the strategy's parameters and the Unleash Context. Again, refer to your specific SDK's documentation for more details.

    - + \ No newline at end of file diff --git a/reference/dependent-features.html b/reference/dependent-features.html index e564d29477..0ab401f043 100644 --- a/reference/dependent-features.html +++ b/reference/dependent-features.html @@ -20,7 +20,7 @@ - + @@ -29,7 +29,7 @@
    Skip to main content

    Dependent Features

    Availability

    Dependent features were first introduced in Unleash 5.7 for Pro and Enterprise users.

    Overview​

    Dependent features allow to define a child feature flag that depends on a parent feature flag.
    A feature flag can have only one parent dependency but multiple child flags can share the same parent. For a child flag to be activated, its parent dependency must be enabled.

    Parent dependency criteria​

    • Project Association: Both parent and child flags should belong to the same project.
    • Single Level Dependency: The parent flag can’t have its own parent, ensuring a straightforward, single-level dependency.

    Managing dependencies​

    Adding​

    Introduce dependencies either through the UI or API, also applicable when copying a child feature with an existing parent dependency.

    A button for adding parent dependency.

    Removing​

    Eliminate them through the UI or API. Dependencies are also removed when archiving a child feature. A parent feature can’t be removed if it would leave a child feature orphaned. To remove both, batch archive them. If Unleash confirms no other child features are using the parent, archiving proceeds.

    A button for deleting parent dependency.

    Permissions​

    The Update feature dependency project permission, auto-assigned to admin and project members, allows managing dependencies.

    Metrics calculation​

    Metrics are influenced solely by the evaluation of child features.

    Client SDK Support​

    To make use of dependent feature, you need to use a compatible client. Client SDK with variant support:

    If you would like to give feedback on this feature, experience issues or have questions, please feel free to open an issue on GitHub.

    - + \ No newline at end of file diff --git a/reference/environments.html b/reference/environments.html index a4066315af..3607e101b4 100644 --- a/reference/environments.html +++ b/reference/environments.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Environments

    Availability

    Environments were released in Unleash v4.3.0.

    Environments is a new way to organize activation strategy configurations for feature toggles into separate environments. In Unleash, a feature lives across all your environments — after all, the goal is to get the new feature released as soon as possible — but it makes sense to configure the activation differently per environment. You might want the feature enabled for everyone in development, but only for yourself in production, for instance.

    Previously, Unleash Enterprise could use strategy constraints to control the rollout across environments. With the new environments feature, this is no longer necessary. Now all activation strategies belong to an explicit environment instead.

    Further, connected applications will use environment-scoped API keys to make sure they only download feature toggle configurations for the environment they are running in.

    Finally, metrics have also been upgraded to record the environment. This, in turn, means that Unleash can display usage metrics per environment.

    Despite this being a shift in how Unleash works, everything will continue to work exactly how it did for existing users. For backwards compatibility, we have created an environment named "default" that will contain all of the existing toggles and API keys. Read more about that in the migration section.

    A graph showing how environments work. Each project can have multiple features, and each feature can have different activation strategies in each of its environments.

    Environment types​

    All environments in Unleash have a type. When you create a new environment, you must also assign it a type.

    The built-in environment types are:

    • Development
    • Test
    • Pre-production
    • Production

    The production environment type is special: Unleash will show additional confirmation prompts when you change something that could impact users in environments of this type. The built-in "production" environment is a production-type environment.

    The other environment types do not currently have any functionality associated with them. This may change in the future.

    Global and project-level environments​

    Environments exist on a global level, so they are available to all projects within Unleash. However, every project might not need to use every environment. That's why you can also choose which of the global environments should be available within a project.

    How to start using environments​

    In order to start using environments you need to be on Unleash v4.2 or higher.

    If you are on v4.2, you also need to have the environment feature enabled (if you are using Unleash Hosted, please reach out on contact@getunleash.io if you want to start using environments.

    If you are on v4.3 or later, environments are already enabled for you.

    Note that in order to enable an environment for a feature toggle, you must first add activation strategies for that environment. You cannot enable an environment without activation strategies.

    Step 1: Enable new environments for your Project​

    Navigate to the project and choose the “environments” tab.

    A project view showing the Environments tab. The UI displays three environment toggles: &quot;default&quot;, &quot;development&quot;, and &quot;production&quot;. The &quot;default&quot; environment is enabled.

    Step 2: Configure activation strategies for the new environment​

    From the “feature toggle view” you will now be able to configure activation strategies per environment. You can also enable and disable environments here. Remember that an environment must have activation strategies before you can enable it.

    A feature toggle strategies tab showing three different environments, of which one is active. The UI displays data about the currently selected environment,

    Step 3: Create environment specific API keys​

    In order for the SDK to download the feature toggle configuration for the correct environment you will need to create an API token for a defined environment.

    An API key creation form. The form&#39;s fields are &quot;username&quot;, &quot;token type&quot;, &quot;project&quot;, and, crucially, &quot;environment&quot;. The development environment is selected.

    Cloning environments​

    Availability

    Environment cloning was made available in Unleash 4.19.

    Unleash environments can be cloned. Cloning an environment creates a new environment based on the selected source environment. When cloning an environment, you select any number of projects whose feature toggle configurations will also be cloned. These projects will have identical configurations for the source and target environments. However, the environments can then be configured independently and will not stay in sync with each other.

    When cloning an environment, you must give the new environment

    • a name
    • an environment type
    • a list of projects to clone feature configurations in

    You can also clone user permissions into the new environment. When you do that, permissions in the new environment will be the same as in the environment you cloned from. If you don't clone permissions, only admins and project editors can make changes in the new environment. You can change permissions after creation by using custom project roles.

    In order to clone an environment, you can follow the how to clone environments guide.

    Once created, the new environment works just as any other environment.

    Migration​

    To ease migration we have created a special environment called “default”. All existing activation strategies have been added to this environment. All existing Client API keys have also been scoped to work against the default environment to ensure zero disruption as part of the upgrade.

    If you're currently using strategy constraints together with the “environment” field on the Unleash Context, you should be aware that the new environment support works slightly differently. With environments, the SDK API will use the client's API key to determine which environment the client is configured for. The API then sends only strategies belonging to the client's environment. This means that you might not need the "environment" property of the Unleash Context anymore.

    A strategy constraint using the environment field of the unleash context.

    Integrations​

    We have made some slight changes to events related to feature toggles: there's one deprecation and several new event types. Most of the new events contain project and environment data.

    To avoid missing important updates, you will also need to update your integration configuration to subscribe to the new events.

    Deprecated events:

    • FEATURE_UPDATE - not used after switching to environments

    New Events

    • FEATURE-METADATA-UPDATED - The feature toggle metadata was updated (across all environments).
    • FEATURE-STRATEGY-ADD¹ - An activation strategy was added to a feature toggle in an environment. The data will contain the updated strategy configuration.
    • FEATURE-STRATEGY-UPDATE¹ - An activation strategy was updated for a feature toggle. The data will contain the updated strategy configuration.
    • FEATURE-STRATEGY-REMOVE¹ - An activation strategy was removed for a feature toggle.
    • FEATURE-ENVIRONMENT-ENABLED¹ - Signals that a feature toggle has been enabled in a defined environment.
    • FEATURE-ENVIRONMENT-DISABLED¹ - Signals that a feature toggle has been disabled in a defined environment.
    • FEATURE-PROJECT-CHANGE¹ - The feature toggle was moved to a new project.
    1. These feature events will contain project and environment as part of the event metadata.

    API​

    In order to support configuration per environment we had to rebuild our feature toggle admin API to account for environments as well. This means that we're making the following changes to the API:

    • /api/admin/features - deprecated (scheduled for removal in Unleash v5.0). The old feature toggles admin API still works, but strategy configuration will be assumed to target the “default” environment.
    • /api/admin/projects/:projectId/features - New feature API to be used for feature toggles which also adds support for environments. See the documentation to learn more.

    Plan Differences​

    Open-Source (free)​

    • Will get access to two preconfigured environments: “development” and “production”. Existing users of Unleash will also get an additional “default” environment to simplify the adoption of environments.
    • Will be possible to turn environments on/off for all projects.

    Pro (commercial)​

    • Will get access to two preconfigured environments: “development” and “production”. Existing users of Unleash will also get an additional “default” environment to simplify the adoption of environments.
    • Will be possible to turn environments on/off for the default project.

    Enterprise (commercial)​

    • Will get access to two preconfigured environments: “development” and “production”. Existing users of Unleash will also get an additional “default” environment to simplify the adoption of environments.
    • Will be possible to turn environments on/off for all projects
    • Will be allowed to update and remove environments.
    • Will be allowed to create new environments and clone existing environments.

    Rollout Plan​

    • Unleash v4.2 will provide early access to environment support. This means that it can be enabled per customer via a feature flag.
    • Unleash v4.3 plans to provide general access to the environment support for all users of Unleash (Open-Source, Pro, Enterprise).
    - + \ No newline at end of file diff --git a/reference/event-log.html b/reference/event-log.html index a44732a973..ea9cb67e6b 100644 --- a/reference/event-log.html +++ b/reference/event-log.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Event Log

    The event log lets you track changes in Unleash. It lists what changed, when it changed, and who performed the change.

    Feature toggle log​

    Each feature toggle has its own event log. The event log is available under the "Event log" tab in the tab view.

    The event log for a feature toggle. The &quot;Event log&quot; tab is highlighted and the UI shows the most recent changes, including a JSON diff and the change details.

    Global Event Log​

    Unleash also keeps an event log across all toggles and activation strategies, tracking all changes. You access the global event log via the “event log”, which you can find in the drawer menu. The global event log is only accessible by users with instance admin access.

    The global event log and how to get there. It shows a number of events and their changes as well as the navigation steps: use the admin menu and navigate to &quot;event history&quot;.

    - + \ No newline at end of file diff --git a/reference/event-types.html b/reference/event-types.html index fd66cfe36c..9bf40e598e 100644 --- a/reference/event-types.html +++ b/reference/event-types.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Event Types

    Unleash emits a large number of different events (described in more detail in the next sections). The exact fields an event contains varies from event to event, but they all conform to the following TypeScript interface before being transformed to JSON:

    interface IEvent {
      id: number;
      createdAt: Date;
      type: string;
      createdBy: string;
      project?: string;
      environment?: string;
      featureName?: string;
      data?: any;
      preData?: any;
      tags?: ITag[];
    }

    The event properties are described in short in the table below. For more info regarding specific event types, refer to the following sections.

    PropertyDescription
    createdAtThe time the event happened as a RFC 3339-conformant timestamp.
    dataExtra associated data related to the event, such as feature toggle state, segment configuration, etc., if applicable.
    environmentThe feature toggle environment the event relates to, if applicable.
    featureNameThe name of the feature toggle the event relates to, if applicable.
    idThe ID of the event. An increasing natural number.
    preDataData relating to the previous state of the event's subject.
    projectThe project the event relates to, if applicable.
    tagsAny tags related to the event, if applicable.
    typeThe event type, as described in the rest of this section.

    Feature toggle events​

    These events pertain to feature toggles and their life cycle.

    feature-created​

    This event fires when you create a feature. The data property contains the details for the new feature.

    example event: feature-created
    {
      "id": 899,
      "type": "feature-created",
      "createdBy": "user@company.com",
      "createdAt": "2022-05-31T13:32:20.560Z",
      "data": {
        "name": "new-feature",
        "description": "Toggle description",
        "type": "release",
        "project": "my-project",
        "stale": false,
        "variants": [],
        "createdAt": "2022-05-31T13:32:20.547Z",
        "lastSeenAt": null,
        "impressionData": true
      },
      "preData": null,
      "tags": [],
      "featureName": "new-feature",
      "project": "my-project",
      "environment": null
    }

    feature-updated​

    Deprecation notice

    This event type was replaced by more granular event types in Unleash 4.3. From Unleash 4.3 onwards, you'll need to use the events listed later in this section instead.

    This event fires when a feature gets updated in some way. The data property contains the new state of the toggle. This is a legacy event, so it does not populate preData property.

    example event: feature-updated
    {
      "id": 899,
      "type": "feature-updated",
      "createdBy": "user@company.com",
      "createdAt": "2022-05-31T13:32:20.560Z",
      "data": {
        "name": "new-feature",
        "description": "Toggle description",
        "type": "release",
        "project": "my-project",
        "stale": false,
        "variants": [],
        "createdAt": "2022-05-31T13:32:20.547Z",
        "lastSeenAt": null,
        "impressionData": true
      },
      "preData": null,
      "tags": [],
      "featureName": "new-feature",
      "project": "my-project",
      "environment": null
    }

    feature-deleted​

    This event fires when you delete a feature toggle. The preData property contains the deleted toggle data.

    example event: feature-deleted
    {
      "id": 903,
      "type": "feature-deleted",
      "createdBy": "admin-account",
      "createdAt": "2022-05-31T14:06:14.574Z",
      "data": null,
      "preData": {
        "name": "new-feature",
        "type": "experiment",
        "stale": false,
        "project": "my-project",
        "variants": [],
        "createdAt": "2022-05-31T13:32:20.547Z",
        "lastSeenAt": null,
        "description": "Toggle description",
        "impressionData": true
      },
      "tags": [],
      "featureName": "new-feature",
      "project": "my-project",
      "environment": null
    }

    feature-archived​

    This event fires when you archive a toggle.

    example event: feature-archived
    {
      "id": 902,
      "type": "feature-archived",
      "createdBy": "user@company.com",
      "createdAt": "2022-05-31T14:04:38.661Z",
      "data": null,
      "preData": null,
      "tags": [],
      "featureName": "new-feature",
      "project": "my-project",
      "environment": null
    }

    feature-revived​

    This event fires when you revive an archived feature toggle (when you take a toggle out from the archive).

    example-event: feature-revived
    {
      "id": 914,
      "type": "feature-revived",
      "createdBy": "user@company.com",
      "createdAt": "2022-06-01T09:57:10.719Z",
      "data": null,
      "preData": null,
      "tags": [],
      "featureName": "new-feature",
      "project": "my-other-project",
      "environment": null
    }

    feature-metadata-updated​

    This event fires when a feature's metadata (its description, toggle type, or impression data settings) are changed. The data property contains the new toggle data. The preData property contains the toggle's previous data.

    The below example changes the toggle's type from release to experiment.

    example event: feature-metadata-updated
    {
      "id": 901,
      "type": "feature-metadata-updated",
      "createdBy": "user@company.com",
      "createdAt": "2022-05-31T13:35:25.244Z",
      "data": {
        "name": "new-feature",
        "description": "Toggle description",
        "type": "experiment",
        "project": "my-project",
        "stale": false,
        "variants": [],
        "createdAt": "2022-05-31T13:32:20.547Z",
        "lastSeenAt": null,
        "impressionData": true
      },
      "preData": {
        "name": "new-feature",
        "type": "release",
        "stale": false,
        "project": "my-project",
        "variants": [],
        "createdAt": "2022-05-31T13:32:20.547Z",
        "lastSeenAt": null,
        "description": "Toggle description",
        "impressionData": true
      },
      "tags": [],
      "featureName": "new-feature",
      "project": "my-project",
      "environment": null
    }

    feature-project-change​

    This event fires when you move a feature from one project to another. The data property contains the names of the old and the new project.

    example event: feature-project-change
    {
      "id": 11,
      "type": "feature-project-change",
      "createdBy": "admin",
      "createdAt": "2022-06-03T11:09:41.444Z",
      "data": {
        "newProject": "default",
        "oldProject": "2"
      },
      "preData": null,
      "tags": [],
      "featureName": "feature",
      "project": "default",
      "environment": null
    }

    feature-import​

    This event fires when you import a feature as part of an import process. The data property contains the feature data.

    example event: feature-import
    {
      "id": 26,
      "type": "feature-import",
      "createdBy": "import-API-token",
      "createdAt": "2022-06-03T11:30:40.570Z",
      "data": {
        "name": "feature",
        "description": "",
        "type": "release",
        "project": "default",
        "stale": false,
        "variants": [],
        "impressionData": false,
        "enabled": false,
        "archived": false
      },
      "preData": null,
      "tags": [],
      "featureName": null,
      "project": null,
      "environment": null
    }

    feature-tagged​

    This event fires when you add a tag to a feature. The data property contains the new tag.

    example event: feature-tagged
    {
      "id": 897,
      "type": "feature-tagged",
      "createdBy": "user@company.com",
      "createdAt": "2022-05-31T13:06:31.047Z",
      "data": {
        "type": "simple",
        "value": "tag2"
      },
      "preData": null,
      "tags": [],
      "featureName": "example-feature-name",
      "project": null,
      "environment": null
    }

    feature-untagged​

    This event fires when you remove a tag from a toggle. The data property contains the tag that was removed.

    example event: feature-untagged
    {
      "id": 893,
      "type": "feature-untagged",
      "createdBy": "user@company.com",
      "createdAt": "2022-05-31T12:58:10.241Z",
      "data": {
        "type": "simple",
        "value": "thisisatag"
      },
      "preData": null,
      "tags": [],
      "featureName": "example-feature-name",
      "project": null,
      "environment": null
    }

    feature-tag-import​

    This event fires when you import a tagged feature as part of an import job. The data property contains the name of the feature and the tag.

    example event: feature-tag-import
    {
      "id": 43,
      "type": "feature-tag-import",
      "createdBy": "import-API-token",
      "createdAt": "2022-06-03T11:30:40.606Z",
      "data": {
        "featureName": "new-feature",
        "tag": {
          "type": "simple",
          "value": "tag1"
        }
      },
      "preData": null,
      "tags": [],
      "featureName": null,
      "project": null,
      "environment": null
    }

    feature-strategy-add​

    This event fires when you add a strategy to a feature. The data property contains the configuration for the new strategy.

    example event: feature-strategy-add
    {
      "id": 919,
      "type": "feature-strategy-add",
      "createdBy": "user@company.com",
      "createdAt": "2022-06-01T10:03:08.290Z",
      "data": {
        "id": "3f4bf713-696c-43a4-8ce7-d6c607108858",
        "name": "flexibleRollout",
        "constraints": [],
        "parameters": {
          "groupId": "new-feature",
          "rollout": "67",
          "stickiness": "default"
        }
      },
      "preData": null,
      "tags": [],
      "featureName": "new-feature",
      "project": "my-other-project",
      "environment": "default"
    }

    feature-strategy-update​

    This event fires when you update a feature strategy. The data property contains the new strategy configuration. The preData property contains the previous strategy configuration.

    example event: feature-strategy-update
    {
      "id": 920,
      "type": "feature-strategy-update",
      "createdBy": "user@company.com",
      "createdAt": "2022-06-01T10:03:11.549Z",
      "data": {
        "id": "3f4bf713-696c-43a4-8ce7-d6c607108858",
        "name": "flexibleRollout",
        "constraints": [],
        "parameters": {
          "groupId": "new-feature",
          "rollout": "32",
          "stickiness": "default"
        }
      },
      "preData": {
        "id": "3f4bf713-696c-43a4-8ce7-d6c607108858",
        "name": "flexibleRollout",
        "parameters": {
          "groupId": "new-feature",
          "rollout": "67",
          "stickiness": "default"
        },
        "constraints": []
      },
      "tags": [],
      "featureName": "new-feature",
      "project": "my-other-project",
      "environment": "default"
    }

    feature-strategy-remove​

    This event fires when you remove a strategy from a feature. The preData contains the configuration of the strategy that was removed.

    example event: feature-strategy-remove
    {
      "id": 918,
      "type": "feature-strategy-remove",
      "createdBy": "user@company.com",
      "createdAt": "2022-06-01T10:03:00.229Z",
      "data": null,
      "preData": {
        "id": "9591090e-acb0-4088-8958-21faaeb7147d",
        "name": "default",
        "parameters": {},
        "constraints": []
      },
      "tags": [],
      "featureName": "new-feature",
      "project": "my-other-project",
      "environment": "default"
    }

    feature-stale-on​

    This event fires when you mark a feature as stale.

    example event: feature-stale-on
    {
      "id": 926,
      "type": "feature-stale-on",
      "createdBy": "user@company.com",
      "createdAt": "2022-06-01T10:10:46.737Z",
      "data": null,
      "preData": null,
      "tags": [
        {
          "value": "tag",
          "type": "simple"
        },
        {
          "value": "tog",
          "type": "simple"
        }
      ],
      "featureName": "new-feature",
      "project": "my-other-project",
      "environment": null
    }

    feature-stale-off​

    This event fires when you mark a stale feature as no longer being stale.

    example event: feature-stale-off
    {
      "id": 928,
      "type": "feature-stale-off",
      "createdBy": "user@company.com",
      "createdAt": "2022-06-01T10:10:52.790Z",
      "data": null,
      "preData": null,
      "tags": [
        {
          "value": "tag",
          "type": "simple"
        },
        {
          "value": "tog",
          "type": "simple"
        }
      ],
      "featureName": "new-feature",
      "project": "my-other-project",
      "environment": null
    }

    feature-environment-enabled​

    This event fires when you enable an environment for a feature. The environment property contains the name of the environment.

    example event: feature-environment-enabled
    {
      "id": 930,
      "type": "feature-environment-enabled",
      "createdBy": "user@company.com",
      "createdAt": "2022-06-02T12:09:03.045Z",
      "data": null,
      "preData": null,
      "tags": [
        {
          "value": "tag",
          "type": "simple"
        },
        {
          "value": "tog",
          "type": "simple"
        }
      ],
      "featureName": "new-feature",
      "project": "my-other-project",
      "environment": "development"
    }

    feature-environment-disabled​

    This event fires when you disable an environment for a feature. The environment property contains the name of the environment.

    example event: feature-environment-disabled
    {
      "id": 931,
      "type": "feature-environment-disabled",
      "createdBy": "user@company.com",
      "createdAt": "2022-06-02T12:09:04.469Z",
      "data": null,
      "preData": null,
      "tags": [
        {
          "value": "tag",
          "type": "simple"
        },
        {
          "value": "tog",
          "type": "simple"
        }
      ],
      "featureName": "new-feature",
      "project": "my-other-project",
      "environment": "development"
    }

    drop-features​

    This event fires when you delete existing features as part of an import job. The data.name property will always be "all-features".

    example event: drop-features
    {
      "id": 25,
      "type": "drop-features",
      "createdBy": "import-API-token",
      "createdAt": "2022-06-03T11:30:40.563Z",
      "data": {
        "name": "all-features"
      },
      "preData": null,
      "tags": [],
      "featureName": null,
      "project": null,
      "environment": null
    }

    drop-feature-tags​

    This event fires when you drop all existing tags as part of a configuration import. The data.name property will always be "all-feature-tags".

    example event: drop-feature-tags
    {
      "id": 36,
      "type": "drop-feature-tags",
      "createdBy": "import-API-token",
      "createdAt": "2022-06-03T11:30:40.596Z",
      "data": {
        "name": "all-feature-tags"
      },
      "preData": null,
      "tags": [],
      "featureName": null,
      "project": null,
      "environment": null
    }

    feature-potentially-stale-on​

    Availability

    feature-potentially-stale-on events are currently in development and expected to be stabilized in one of the upcoming releases.

    This event fires when Unleash marks a feature toggle as potentially stale. Feature toggles are marked as potentially stale when they exceed the expected lifetime of their feature toggle type.

    Example event when my-feature is marked as potentially stale
    {
      "id": 561,
      "type": "feature-potentially-stale-on",
      "createdBy": "unleash-system",
      "createdAt": "2023-07-19T09:12:31.313Z",
      "data": null,
      "preData": null,
      "tags": [],
      "featureName": "helix",
      "project": "viridian-forest",
      "environment": null
    }

    Strategy events​

    strategy-created​

    This event fires when you create a strategy. The data property contains the strategy configuration.

    example event: strategy-created
    {
      "id": 932,
      "type": "strategy-created",
      "createdBy": "user@company.com",
      "createdAt": "2022-06-02T12:20:52.111Z",
      "data": {
        "name": "new-strategy",
        "description": "this strategy does ...",
        "parameters": [],
        "editable": true,
        "deprecated": false
      },
      "preData": null,
      "tags": [],
      "featureName": null,
      "project": null,
      "environment": null
    }

    strategy-updated​

    This event fires when you change a strategy's configuration. The data property contains the new strategy configuration.

    example event: strategy-updated
    {
      "id": 933,
      "type": "strategy-updated",
      "createdBy": "user@company.com",
      "createdAt": "2022-06-02T12:21:23.741Z",
      "data": {
        "name": "new-strategy",
        "description": "this strategy does something else!",
        "parameters": [],
        "editable": true,
        "deprecated": false
      },
      "preData": null,
      "tags": [],
      "featureName": null,
      "project": null,
      "environment": null
    }

    strategy-deleted​

    This event fires when you delete a strategy. The data property contains the name of the deleted strategy.

    example event: strategy-deleted
    {
      "id": 936,
      "type": "strategy-deleted",
      "createdBy": "user@company.com",
      "createdAt": "2022-06-02T12:22:01.302Z",
      "data": {
        "name": "new-strategy"
      },
      "preData": null,
      "tags": [],
      "featureName": null,
      "project": null,
      "environment": null
    }

    strategy-deprecated​

    This event fires when you deprecate a strategy. The data property contains the name of the deprecated strategy.

    example event: strategy-deprecated
    {
      "id": 934,
      "type": "strategy-deprecated",
      "createdBy": "user@company.com",
      "createdAt": "2022-06-02T12:21:45.041Z",
      "data": {
        "name": "new-strategy"
      },
      "preData": null,
      "tags": [],
      "featureName": null,
      "project": null,
      "environment": null
    }

    strategy-reactivated​

    This event fires when you bring reactivate a deprecated strategy. The data property contains the name of the reactivated strategy.

    example event: strategy-reactivated
    {
      "id": 935,
      "type": "strategy-reactivated",
      "createdBy": "user@company.com",
      "createdAt": "2022-06-02T12:21:49.010Z",
      "data": {
        "name": "new-strategy"
      },
      "preData": null,
      "tags": [],
      "featureName": null,
      "project": null,
      "environment": null
    }

    strategy-import​

    This event fires when you import a strategy as part of an import job. The data property contains the strategy's configuration.

    example event: strategy-import
    {
      "id": 29,
      "type": "strategy-import",
      "createdBy": "import-API-token",
      "createdAt": "2022-06-03T11:30:40.583Z",
      "data": {
        "name": "gradualRolloutSessionId",
        "description": "Gradually activate feature toggle. Stickiness based on session id.",
        "parameters": [
          {
            "name": "percentage",
            "type": "percentage",
            "description": "",
            "required": false
          },
          {
            "name": "groupId",
            "type": "string",
            "description": "Used to define a activation groups, which allows you to correlate across feature toggles.",
            "required": true
          }
        ],
        "deprecated": true
      },
      "preData": null,
      "tags": [],
      "featureName": null,
      "project": null,
      "environment": null
    }

    drop-strategies​

    This event fires when you delete existing strategies as part of an important job. The data.name property will always be "all-strategies".

    example event: drop-strategies
    {
      "id": 28,
      "type": "drop-strategies",
      "createdBy": "import-API-token",
      "createdAt": "2022-06-03T11:30:40.579Z",
      "data": {
        "name": "all-strategies"
      },
      "preData": null,
      "tags": [],
      "featureName": null,
      "project": null,
      "environment": null
    }

    Context field events​

    context-field-created​

    This event fires when you create a context field. The data property contains the context field configuration.

    example event: context-field-created
    {
      "id": 937,
      "type": "context-field-created",
      "createdBy": "user@company.com",
      "createdAt": "2022-06-02T13:17:17.499Z",
      "data": {
        "name": "new-context-field",
        "description": "this context field is for describing events",
        "legalValues": [],
        "stickiness": false
      },
      "preData": null,
      "tags": [],
      "featureName": null,
      "project": null,
      "environment": null
    }

    context-field-updated​

    This event fires when you update a context field. The data property contains the new context field configuration.

    example event: context-field-updated
    {
      "id": 939,
      "type": "context-field-updated",
      "createdBy": "user@company.com",
      "createdAt": "2022-06-02T13:19:19.422Z",
      "data": {
        "name": "new-context-field",
        "description": "this context field is for describing events",
        "legalValues": [
          {
            "value": "0fcf7d07-276c-41e1-a207-e62876d9c949",
            "description": "Red team"
          },
          {
            "value": "176ab647-4d50-41bf-afe0-f8b856d9bbb9",
            "description": "Blue team"
          }
        ],
        "stickiness": false
      },
      "preData": null,
      "tags": [],
      "featureName": null,
      "project": null,
      "environment": null
    }

    context-field-deleted​

    This event fires when you delete a context field. The data property contains the name of the deleted context field.

    example event: context-field-deleted
    {
      "id": 940,
      "type": "context-field-deleted",
      "createdBy": "user@company.com",
      "createdAt": "2022-06-02T13:20:41.386Z",
      "data": {
        "name": "new-context-field"
      },
      "preData": null,
      "tags": [],
      "featureName": null,
      "project": null,
      "environment": null
    }

    Project events​

    project-created​

    This event fires when you create a project. The data property contains the project configuration.

    example event: project-created
    {
      "id": 905,
      "type": "project-created",
      "createdBy": "user@company.com",
      "createdAt": "2022-05-31T14:16:14.498Z",
      "data": {
        "id": "my-other-project",
        "name": "my other project",
        "description": "a project for important work"
      },
      "preData": null,
      "tags": [],
      "featureName": null,
      "project": "my-other-project",
      "environment": null
    }

    project-updated​

    This event fires when you update a project's configuration. The data property contains the new project configuration. The preData property contains the previous project configuration.

    example event: project-updated
    {
      "id": 941,
      "type": "project-updated",
      "createdBy": "user@company.com",
      "createdAt": "2022-06-02T13:23:55.025Z",
      "data": {
        "id": "my-other-project",
        "name": "my other project",
        "description": "a project for important work!"
      },
      "preData": {
        "id": "my-other-project",
        "name": "my other project",
        "health": 50,
        "createdAt": "2022-05-31T14:16:14.483Z",
        "updatedAt": "2022-06-02T12:30:48.095Z",
        "description": "a project for important work"
      },
      "tags": [],
      "featureName": null,
      "project": "my-other-project",
      "environment": null
    }

    project-deleted​

    This event fires when you delete a project. The project property contains the name of the deleted project.

    example event: project-deleted
    {
      "id": 944,
      "type": "project-deleted",
      "createdBy": "user@company.com",
      "createdAt": "2022-06-02T13:25:53.820Z",
      "data": null,
      "preData": null,
      "tags": [],
      "featureName": null,
      "project": "my-other-project",
      "environment": null
    }

    project-import​

    This event fires when you import a project. The data property contains the project's configuration details.

    example event: project-import
    {
      "id": 35,
      "type": "project-import",
      "createdBy": "import-API-token",
      "createdAt": "2022-06-03T11:30:40.591Z",
      "data": {
        "id": "default",
        "name": "Default",
        "description": "Default project",
        "createdAt": "2022-06-03T09:30:40.587Z",
        "health": 100,
        "updatedAt": "2022-06-03T11:30:40.587Z"
      },
      "preData": null,
      "tags": [],
      "featureName": null,
      "project": null,
      "environment": null
    }

    drop-projects​

    This event fires when you delete existing projects as part of an import job. The data.name property will always be "all-projects".

    example event: drop-projects
    {
      "id": 33,
      "type": "drop-projects",
      "createdBy": "import-API-token",
      "createdAt": "2022-06-03T11:30:40.586Z",
      "data": {
        "name": "all-projects"
      },
      "preData": null,
      "tags": [],
      "featureName": null,
      "project": null,
      "environment": null
    }

    Tag events​

    tag-created​

    This event fires when you create a new tag. The data property contains the tag that was created.

    example event: tag-created
    {
      "id": 959,
      "type": "feature-tagged",
      "createdBy": "user@company.com",
      "createdAt": "2022-06-03T10:13:39.401Z",
      "data": {
        "type": "heartag",
        "value": "tag-value"
      },
      "preData": null,
      "tags": [],
      "featureName": "new-feature",
      "project": null,
      "environment": null
    }

    tag-deleted​

    This event fires when you delete a tag. The data property contains the tag that was deleted.

    example event: tag-deleted
    {
      "id": 957,
      "type": "tag-deleted",
      "createdBy": "user@company.com",
      "createdAt": "2022-06-03T10:12:17.310Z",
      "data": {
        "type": "heartag",
        "value": "tag-value"
      },
      "preData": null,
      "tags": [],
      "featureName": null,
      "project": null,
      "environment": null
    }

    tag-import​

    This event fires when you import a tag as part of an import job. The data property contains the imported tag.

    example event: tag-import
    {
      "id": 41,
      "type": "tag-import",
      "createdBy": "import-API-token",
      "createdAt": "2022-06-03T11:30:40.603Z",
      "data": {
        "type": "simple",
        "value": "tag1"
      },
      "preData": null,
      "tags": [],
      "featureName": null,
      "project": null,
      "environment": null
    }

    drop-tags​

    This event fires when you delete existing tags as part of an import job. The data.name property will always be "all-tags".

    example event: drop-tags
    {
      "id": 37,
      "type": "drop-tags",
      "createdBy": "import-API-token",
      "createdAt": "2022-06-03T11:30:40.596Z",
      "data": {
        "name": "all-tags"
      },
      "preData": null,
      "tags": [],
      "featureName": null,
      "project": null,
      "environment": null
    }

    Tag type events​

    tag-type-created​

    This event fires when you create a new tag type. The data property contains the tag type configuration.

    example event: tag-type-created
    {
      "id": 945,
      "type": "tag-type-created",
      "createdBy": "user@company.com",
      "createdAt": "2022-06-02T13:27:01.235Z",
      "data": {
        "name": "new-tag-type",
        "description": "event testing"
      },
      "preData": null,
      "tags": [],
      "featureName": null,
      "project": null,
      "environment": null
    }

    tag-type-updated​

    This event fires when you update a tag type. The data property contains the new tag type configuration.

    example event: tag-type-updated
    {
      "id": 946,
      "type": "tag-type-updated",
      "createdBy": "user@company.com",
      "createdAt": "2022-06-02T13:27:31.126Z",
      "data": {
        "name": "new-tag-type",
        "description": "This tag is for testing events."
      },
      "preData": null,
      "tags": [],
      "featureName": null,
      "project": null,
      "environment": null
    }

    tag-type-deleted​

    This event fires when you delete a tag type. The data property contains the name of the deleted tag type.

    example event: tag-type-deleted
    {
      "id": 947,
      "type": "tag-type-deleted",
      "createdBy": "user@company.com",
      "createdAt": "2022-06-02T13:27:37.277Z",
      "data": {
        "name": "new-tag-type"
      },
      "preData": null,
      "tags": [],
      "featureName": null,
      "project": null,
      "environment": null
    }

    tag-type-import​

    This event fires when you import a tag type as part of an import job. The data property contains the imported tag.

    example event: tag-type-import
    {
      "id": 40,
      "type": "tag-type-import",
      "createdBy": "import-API-token",
      "createdAt": "2022-06-03T11:30:40.599Z",
      "data": {
        "name": "custom-tag-type",
        "description": "custom tag type",
        "icon": null
      },
      "preData": null,
      "tags": [],
      "featureName": null,
      "project": null,
      "environment": null
    }

    drop-tag-types​

    This event fires when you drop all existing tag types as part of a configuration import. The data.name property will always be "all-tag-types".

    example event: drop-tag-types
    {
      "id": 38,
      "type": "drop-tag-types",
      "createdBy": "import-API-token",
      "createdAt": "2022-06-03T11:30:40.596Z",
      "data": {
        "name": "all-tag-types"
      },
      "preData": null,
      "tags": [],
      "featureName": null,
      "project": null,
      "environment": null
    }

    Integration events​

    addon-config-created​

    This event fires when you create an integration configuration. The data property contains the provider type.

    example event: addon-config-created
    {
      "id": 960,
      "type": "addon-config-created",
      "createdBy": "user@company.com",
      "createdAt": "2022-06-03T10:15:45.040Z",
      "data": {
        "provider": "webhook"
      },
      "preData": null,
      "tags": [],
      "featureName": null,
      "project": null,
      "environment": null
    }

    addon-config-updated​

    This event fires when you update an integration configuration. The data property contains the integration's ID and provider type.

    example event: addon-config-updated
    {
      "id": 961,
      "type": "addon-config-updated",
      "createdBy": "user@company.com",
      "createdAt": "2022-06-03T10:16:11.732Z",
      "data": {
        "id": "2",
        "provider": "webhook"
      },
      "preData": null,
      "tags": [],
      "featureName": null,
      "project": null,
      "environment": null
    }

    addon-config-deleted​

    This event fires when you update an integration configuration. The data property contains the integration's ID.

    example event: addon-config-deleted
    {
      "id": 964,
      "type": "addon-config-deleted",
      "createdBy": "user@company.com",
      "createdAt": "2022-06-03T10:16:59.723Z",
      "data": {
        "id": "2"
      },
      "preData": null,
      "tags": [],
      "featureName": null,
      "project": null,
      "environment": null
    }

    User events​

    user-created​

    This event fires when you create a new user. The data property contains the user's information.

    example event: user-created
    {
      "id": 965,
      "type": "user-created",
      "createdBy": "user@company.com",
      "createdAt": "2022-06-03T10:23:47.713Z",
      "data": {
        "id": 44,
        "name": "New User Name",
        "email": "newuser@company.com"
      },
      "preData": null,
      "tags": [],
      "featureName": null,
      "project": null,
      "environment": null
    }

    user-updated​

    This event fires when you update a user. The data property contains the updated user information; the preData property contains the previous state of the user's information.

    example event: user-updated
    {
      "id": 967,
      "type": "user-updated",
      "createdBy": "user@company.com",
      "createdAt": "2022-06-03T10:24:26.301Z",
      "data": {
        "id": 44,
        "name": "New User's Name",
        "email": "newuser@company.com"
      },
      "preData": {
        "id": 44,
        "name": "New User Name",
        "email": "newuser@company.com"
      },
      "tags": [],
      "featureName": null,
      "project": null,
      "environment": null
    }

    user-deleted​

    This event fires when you delete a user. The preData property contains the deleted user's information.

    example event: user-deleted
    {
      "id": 968,
      "type": "user-deleted",
      "createdBy": "user@company.com",
      "createdAt": "2022-06-03T10:24:49.153Z",
      "data": null,
      "preData": {
        "id": 44,
        "name": "New User's Name",
        "email": "newuser@company.com"
      },
      "tags": [],
      "featureName": null,
      "project": null,
      "environment": null
    }

    Environment events​

    environment-import​

    This event fires when you import an environment (custom or otherwise) as part of an import job. The data property contains the configuration of the imported environment.

    example event: environment-import
    {
      "id": 24,
      "type": "environment-import",
      "createdBy": "import-API-token",
      "createdAt": "2022-06-03T11:30:40.557Z",
      "data": {
        "name": "custom-environment",
        "type": "test",
        "sortOrder": 9999,
        "enabled": true,
        "protected": false
      },
      "preData": null,
      "tags": [],
      "featureName": null,
      "project": null,
      "environment": null
    }

    drop-environments​

    This event fires when you delete existing environments as part of an import job. The data.name property will always be "all-environments".

    example event: drop-environments
    {
      "id": 21,
      "type": "drop-environments",
      "createdBy": "import-API-token",
      "createdAt": "2022-06-03T11:30:40.549Z",
      "data": {
        "name": "all-projects"
      },
      "preData": null,
      "tags": [],
      "featureName": null,
      "project": null,
      "environment": null
    }

    Segment events​

    segment-created​

    This event fires when you create a segment. The data property contains the newly created segment.

    example event: segment-created
    {
      "id": 969,
      "type": "segment-created",
      "createdBy": "user@company.com",
      "createdAt": "2022-06-03T10:29:43.977Z",
      "data": {
        "id": 5,
        "name": "new segment",
        "description": "this segment is for events",
        "constraints": [
          {
            "values": ["appA", "appB", "appC"],
            "inverted": false,
            "operator": "IN",
            "contextName": "appName",
            "caseInsensitive": false
          }
        ],
        "createdBy": "user@company.com",
        "createdAt": "2022-06-03T10:29:43.974Z"
      },
      "preData": null,
      "tags": [],
      "featureName": null,
      "project": null,
      "environment": null
    }

    segment-updated​

    This event fires when you update a segment's configuration. The data property contains the new segment configuration; the preData property contains the previous segment configuration.

    example event: segment-updated
    {
      "id": 970,
      "type": "segment-updated",
      "createdBy": "user@company.com",
      "createdAt": "2022-06-03T10:29:59.892Z",
      "data": {
        "id": 5,
        "name": "new segment",
        "description": "this segment is for events",
        "constraints": [],
        "createdBy": "user@company.com",
        "createdAt": "2022-06-03T10:29:43.974Z"
      },
      "preData": {
        "id": 5,
        "name": "new segment",
        "createdAt": "2022-06-03T10:29:43.974Z",
        "createdBy": "user@company.com",
        "constraints": [
          {
            "values": ["appA", "appB", "appC"],
            "inverted": false,
            "operator": "IN",
            "contextName": "appName",
            "caseInsensitive": false
          }
        ],
        "description": "this segment is for events"
      },
      "tags": [],
      "featureName": null,
      "project": null,
      "environment": null
    }

    segment-deleted​

    This event fires when you delete a segment.

    example event: segment-deleted
    {
      "id": 971,
      "type": "segment-deleted",
      "createdBy": "user@company.com",
      "createdAt": "2022-06-03T10:30:08.128Z",
      "data": {},
      "preData": null,
      "tags": [],
      "featureName": null,
      "project": null,
      "environment": null
    }

    Suggest changes events​

    suggest-change-created​

    This event fires when you create a change-request draft.

    example event: suggest-change-created
    {
      "id": 971,
      "type": "suggest-change-created",
      "createdBy": "user@company.com",
      "createdAt": "2022-06-03T10:30:08.128Z",
      "data": {},
      "preData": null,
      "tags": [],
      "featureName": null,
      "project": null,
      "environment": null
    }
    - + \ No newline at end of file diff --git a/reference/feature-flag-naming-patterns.html b/reference/feature-flag-naming-patterns.html index fcbd8d38c7..8c07d76bb0 100644 --- a/reference/feature-flag-naming-patterns.html +++ b/reference/feature-flag-naming-patterns.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Feature Flag Naming Patterns

    Availability

    Feature flag naming patterns is an in-development, enterprise-only feature.

    A feature flag naming pattern is JavaScript regular expression that is used to validate the name of a feature flag before the flag can be created.

    The pattern is defined in the project settings and is enforced when creating a new feature flag. The pattern is also enforced when creating a new feature flag via the API.

    Patterns are implicitly anchored to the start and end of the string. This means that a pattern is matched against the entire new feature flag name, and not just any subset of it, as if the pattern was surrounded by ^ and $. In other words, the pattern [a-z]+ will be interpreted as ^[a-z]+$ and will match "somefeature", but will not match "some.other.feature".

    Feature flag naming patterns are defined on a per-project basis.

    In addition to the pattern itself, you can also define a an example and a description of the pattern. If defined, both the example and the description will be shown to the user when they are creating a new feature flag.

    Overview​

    The naming pattern consists of three parts:

    Pattern (required)
    The regular expression that is used to validate the name of the feature flag. Must be a valid regular expression. Flags (such as case insensitivity) are not available.
    Example (optional)
    An example of a name that is valid according to the provided pattern. Note: the example must be valid against the described pattern for it to be saved.
    Description (optional)
    Any additional text that you would like to display to users to provide extra information. This can be anything that you think they would find useful and can be as long or short as you want.

    For instance, you might define a pattern that requires all feature flags to follow a specific pattern, such as ^(red|blue|green|yellow)\.[a-z-]+\.[0-9]+$. You could then provide an example of a valid feature flag name (for instance "blue.water-gun.64") and a description of what the pattern should reflect: "<team>.<feature>.<ticket>".

    - + \ No newline at end of file diff --git a/reference/feature-toggle-types.html b/reference/feature-toggle-types.html index 9248e61230..67424bb231 100644 --- a/reference/feature-toggle-types.html +++ b/reference/feature-toggle-types.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Feature Toggle Types

    This feature was introduced in Unleash v3.5.0.

    You can use feature toggles to support different use cases, each with their own specific needs. Heavily inspired by Pete Hodgson's article on feature toggles, Unleash introduced the concept of feature toggle types in version 3.5.0.

    A feature toggle's type affects only two things:

    1. It gives the toggle an appropriate icon
    2. The toggle's expected lifetime changes

    Aside from this, there are no differences between the toggle types and you can always change the type of a toggle after you have created it.

    Classifying feature toggles by their type makes it easier for you manage them: the toggles get different icons in the toggle list and you can sort the toggles by their types.

    Five feature toggles, each of a different type, showing the different icons that Unleash uses for each toggle type.

    A toggle's type also helps Unleash understand the toggle's expected lifetime.

    Feature toggle types​

    Here's the list of the feature toggle types that Unleash supports together with their intended use case and expected lifetime:

    Feature toggle typeUsed to ...Expected lifetime
    ReleaseEnable trunk-based development for teams practicing Continuous Delivery.40 days
    ExperimentPerform multivariate or A/B testing.40 days
    OperationalControl operational aspects of the system's behavior.7 days
    Kill switchGracefully degrade system functionality. You can read about kill switch best practices on our blog.Permanent
    PermissionChange the features or product experience that certain users receive.Permanent

    Expected lifetimes​

    info

    The ability to update a feature toggle type's expected lifetime is currently in development. We expect to release it in one of the upcoming releases.

    A feature toggle's expected lifetime is an indicator of how long Unleash expects toggles of that type to be around. Some feature toggles are meant to live for a few weeks as you work on new functionality, while others stick around for much longer. As a part of good code hygiene, you should clean up your feature toggles when they have served their purpose. This is further explored in the document on technical debt.

    Each feature toggle type in Unleash has an assigned expected lifetime, after which the system will consider this feature potentially stale. The reasoning behind each type's expected lifetime is detailed in this blog post on best practices for feature toggle lifetimes.

    Unleash admins can change the expected lifetime of Unleash's feature types from the Unleash configuration menu.

    Deprecating feature toggles​

    You can mark feature toggles as stale. This is a way to deprecate a feature toggle without removing the active configuration for connected applications. Use this to signal that you should stop using the feature in your applications. Stale toggles will show as stale in the "technical debt dashboard".

    When you mark a toggle as stale, Unleash will emit an event. You can use an integration to integrate this with your systems, for instance to post a message in a Slack channel.

    Additionally, with some extra work, you can also use the stale property to:

    • Inform developers that a toggle is stale while they're developing.
    • Break a project build if the code contains stale feature toggles.
    • Send automatic PRs to remove usage of toggles that have served their purpose.
    - + \ No newline at end of file diff --git a/reference/feature-toggle-variants.html b/reference/feature-toggle-variants.html index 07100dc2eb..c0125e7c89 100644 --- a/reference/feature-toggle-variants.html +++ b/reference/feature-toggle-variants.html @@ -20,7 +20,7 @@ - + @@ -29,7 +29,7 @@
    Skip to main content

    Feature Toggle Variants

    Availability

    Feature toggle variants were first introduced in Unleash 3.2. In Unleash 4.21, variants were updated to be environment-dependent, meaning the same feature could have different variant configurations in different environments.

    Every toggle in Unleash can have something called variants. Where feature toggles allow you to decide which users get access to a feature, toggle variants allow you to further split those users into segments. Say, for instance, that you're testing out a new feature, such as an alternate sign-up form. The feature toggle would expose the form only to a select group of users. The variants could decide whether the user sees a blue or a green submit button on that form.

    Variants facilitate A/B testing and experimentation by letting you create controlled and measurable experiments. Check our blog post on using Unleash for A/B/n experiments for some more insights into how you can set it up.

    What are variants?​

    Whenever you create a feature toggle, you can assign it any number of variants. This is commonly done in cases where you want to serve your users different versions of a feature to see which performs better. A feature can have different variants in each of its environments.

    A variant has four components that define it:

    • a name:

      This must be unique among the toggle's variants in the specified environment. When working with a feature with variants in a client, you will typically use the variant's name to find out which variant it is.

    • a weight:

      The weight is the likelihood of any one user getting this specific variant. See the weights section for more info.

    • an optional payload:

      A variant can also have an associated payload. Use this to deliver more data or context. See the payload section for a more details.

    • an optional override

      Overrides let you specify that certain users (as identified either by their user ID or by another custom stickiness value) will always get this variant, regardless of the variant's weight.

    A form for adding new variants. It has fields for name, weight, payload, and overrides.

    Variant weight​

    A variant's weight determines how likely it is that a user will receive that variant. It is a numeric value between 0 and 100 (inclusive) with one decimal's worth of precision.

    When you have multiple variants, the sum of all their weights must add up to exactly 100. Depending on the weight type, Unleash may automatically determine the weight of the new variant and balance it out with the other variants.

    Weight types and calculation​

    There are two kinds of variant weight types: variable and fixed. Unleash requires you to always have at least one variable weight variant.

    The default weight type is variable. Variable weight variants will adjust their weight based on the number of other variable weight variants and whatever weight is not used up by fixed weight variants.

    Fixed weight variants have a set weight which will not change. All fixed weight variants' weights can not add up to more than 100.

    To calculate what the weight of a variable weight variant is, Unleash first subtracts the sum of fixed weights from 100 and then distributes the remaining weight evenly among the variable weight variants.

    For instance, if you have three variable weight variants and two fixed weight variants weighted at 25 and 15 respectively, Unleash will:

    1. Subtract the fixed weight from the total available: 100 - 40 = 60
    2. Divide the remainder by the number of variable weight variants: 60 / 3 = 20
    3. Assign each variable weight variant the same (up to rounding differences) weight: 20%

    In the example above, 60 divides cleanly by three. In cases where the remainder doesn't divide evenly among the variable weight variants, Unleash will distribute it as evenly as it can to one decimal's precision. If you have three variable weight variants, they will be weighted at 33.4, 33.3, and 33.3 respectively, so that it adds up to 100.0.

    Overrides​

    note

    Overrides are intended to be used for one-off cases and during development and may not be suitable for other use cases.

    The weighting system automatically assigns users to a specific group for you. If you want to make sure that a specific user or group of users receives a certain variant, though, you can use the override functionality to achieve that.

    When adding an override, you choose a field from the Unleash Context and specify that if a context contains one of a given list of values, then the current variant should always activate.

    You can use both standard and custom context fields when creating overrides.

    Each variant can have multiple overrides, so you can use any number of context fields you want to create overrides. When using multiple overrides, each user only has to match one of them. In other words, if you use the following overrides, the users with IDs aa599 and aa65 and any users who use the client with ID 123abc will receive the specified variant:

    • userId: aa599, aa65
    • clientId: 123abc

    Note that if multiple variants use overrides that affect the same user, then Unleash can not guarantee which override will take effect. We recommend that you do not use multiple overrides that can conflict in this way, as it will probably not do what you expect.

    Variant payload​

    Each variant can have an associated payload. Use this to add more context or data to a payload that you can access on the client, such as a customized message or other information.

    Unleash currently supports these payload types:

    • JSON
    • CSV
    • String

    Variant stickiness​

    Variant stickiness is calculated on the received user and context, as described in the stickiness chapter. This ensures that the same user will consistently see the same variant barring overrides and weight changes. If no context data is provided, the traffic will be spread randomly for each request.

    How do I configure variants​

    In the Unleash UI, you can configure variants by navigating to the feature view, and then choosing the 'Variants' tab.

    toggle_variants

    The disabled variant​

    When a toggle has no variants or when a toggle is disabled for a user, Unleash will return it with variant data that looks like this:

    {
      "name": "disabled",
      "enabled": false
    }

    This is a fallback variant that Unleash uses to represent the lack of a variant.

    Note: The actual representation of the built-in fallback variant in the client SDK will vary slightly, to honor best practices in various languages.

    Client SDK Support​

    To make use of toggle variants, you need to use a compatible client. Client SDK with variant support:

    If you would like to give feedback on this feature, experience issues or have questions, please feel free to open an issue on GitHub.

    - + \ No newline at end of file diff --git a/reference/feature-toggles.html b/reference/feature-toggles.html index 948ab9ac19..64a8bdb226 100644 --- a/reference/feature-toggles.html +++ b/reference/feature-toggles.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Feature Toggles

    Feature toggles are the central concept that we built Unleash around. In Unleash, feature toggles are organized within projects. Feature toggles can have different activation strategies for each of their project's environments, and can also be given variants to facilitate A/B testing.

    Configuration options​

    Each feature toggle has the following configuration options

    OptionRequired?Default valueDescription
    nameYesN/AThe feature toggle's name. Must be URL-friendly according to section 2.3 of RFC 3986 and must be unique within your Unleash instance. Must be between 1 and 100 characters long, inclusive.
    feature toggle typeYesReleaseThe feature toggle's type.
    projectYesThe default project. When created from a project page in the admin UI, that project will be the default value instead.The project that should contain the feature toggle.
    descriptionNoN/AA description of the feature toggle's purpose.
    enable impression dataYesNoWhether to enable impression data for this toggle or not.

    Environments​

    You probably won't want to use the same configuration to enable a toggle in development as you do in production. That's why feature toggles have different activation strategy configurations for each environment.

    You can enable and disable a toggle independently in each of the project's environments. When you disable a toggle in an environment, it will always evaluate to false in that environment. When you enable a toggle in an environment, the toggle will evaluate to true or false depending on its activation strategies.

    Refer to the documentation on environments for more details on how environments work.

    Activation strategies​

    To enable a feature in an environment, you must assign it at least one activation strategy. A feature toggle's activation strategies determine whether the toggle gets enabled for a particular Unleash context (typically a user). When using multiple strategies in a single environment, only a single strategy needs to evaluate to true for the toggle to get enabled for a user. Whenever Unleash evaluates a toggle, it will evaluate strategies in the current environment until one of them resolves to true. If no strategies resolve to true, then the toggle's value is false.

    Refer to the activation strategies documentation for a detailed description of all the built-in strategies.

    Variants​

    Variants adds another dimension of flexibility to feature toggles. Each feature toggle can be assigned any number of variants which will then get distributed amongst your users based on your choice of context field. You can find out more about variants in the variants docs.

    Creating toggles with payloads​

    While variants are most often used for A/B testing and the like, you can also use variants to assign a constant payload to a toggle. If you give a toggle only a single variant and that variant has a payload, then all users variants will receive that payload.

    - + \ No newline at end of file diff --git a/reference/front-end-api.html b/reference/front-end-api.html index bb76aff969..714c4fcba0 100644 --- a/reference/front-end-api.html +++ b/reference/front-end-api.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Front-end API access

    Availability

    The Unleash front-end API was released in Unleash 4.18. You can read more in the Unleash 4.18 release blog post.

    The Unleash front-end API offers a simplified workflow for connecting a client-side (front-end) applications to Unleash. It provides the exact same API as Unleash edge and the Unleash proxy - deprecated. The front-end API is a quick and easy way to add Unleash to single-page applications and mobile apps.

    Compared to using Unleash Edge, using the Unleash front-end API has both benefits and drawbacks. The benefits are:

    • You don't need to configure and run Unleash Edge. The front-end API is part of Unleash itself and not an external process. All clients will work exactly the same as they would with Unleash Edge.

    On the other hand, using the front-end API has the following drawbacks compared to using Unleash Edge:

    • It can't handle a large number of requests per second. Because the front-end 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.

    These points make the Unleash front-end 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 front-end API and switch to using Unleash Edge when you need it.

    Using the Unleash front-end API​

    When using the front-end API in an SDK, there's three things you need to configure.

    Front-end API tokens​

    As a client-side API, you should use a front-end API token to interact with it. Refer to the how to create API tokens guide for steps on how to create API tokens.

    Cross-origin resource sharing (CORS) configuration​

    You need to allow traffic from your application domains to use the Unleash front-end API with web and hybrid mobile applications. You can update the front-end API CORS settings from the Unleash UI under admin > CORS or by using the API.

    API URL​

    The client needs to point to the correct API endpoint. The front-end API is available at <your-unleash-instance>/api/frontend.

    API token​

    You can create appropriate token, with type FRONTEND on <YOUR_UNLEASH_URL>/admin/api/create-token page or with a request to /api/admin/api-tokens. See our guide on how to create API tokens for more details.

    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 toggle 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.

    - + \ No newline at end of file diff --git a/reference/impression-data.html b/reference/impression-data.html index 4f8e354867..5adf455420 100644 --- a/reference/impression-data.html +++ b/reference/impression-data.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Impression Data

    Availability

    The impression data feature was introduced in Unleash 4.7. It is available in the JavaScript-based proxy clients and in some server-side SDKs. Please refer to the SDK compatibility table for an overview of server-side SDKs that support it.

    Unleash can provide you with impression data about the toggles in your application. Impression data contains information about a specific feature toggle activation check: The client SDK will emit an impression event when it calls isEnabled or getVariant. Some front-end SDKs emit impression events only when a toggle is enabled.

    Front-end SDKs and disabled toggles

    Older versions of the front-end SDKs and other SDKs that connect the Unleash proxy or the Unleash front-end API would not emit impression events when a toggle is disabled.

    This is because impression data is a per-toggle setting and the Proxy and front-end API only transmit information about toggles that are enabled. As such, the SDK will never know that it should emit an impression event if a toggle is disabled.

    Some of the front-end SDKs now include a include a configuration property that lets you turn on impression data for all toggles regardless of whether they're enabled or not.

    Impression data was designed to make it easier for you to collect analytics data, perform A/B tests, and enrich experiments in your applications. It contains information about the feature toggle and the related Unleash Context.

    Impression data is opt-in on a per-toggle basis. Unleash will not emit impression events for toggles not marked as such. Once you've turned impression data on for a toggle, you can start listening for impression events in your client SDK.

    Impression event data​

    There's two types of impression events you can listen for:

    The getVariant event contains all the information found in an isEnabled event in addition to extra data that's only relevant to getVariant calls.

    This table describes all the properties on the impression events:

    Property nameDescriptionEvent type
    eventTypeThe type of the event: isEnabled or getVariantAll
    eventIdA globally unique id (GUID) assigned to this event.All
    contextA representation of the current Unleash Context.All
    enabledWhether the toggle was enabled or not at when the client made the request.All
    featureNameThe name of the feature toggle.All
    variantThe name of the active variantgetVariant events only

    Example isEnabled event​

    {
      eventType: 'isEnabled',
      eventId: '84b41a43-5ba0-47d8-b21f-a60a319607b0',
      context: {
        sessionId: 54085233,
        appName: 'my-webapp',
        environment: 'default'
      },
      enabled: true,
      featureName: 'my-feature-toggle',
    }

    Example getVariant event​

    {
      eventType: 'getVariant',
      eventId: '84b41a43-5ba0-47d8-b21f-a60a319607b0',
      context: {
        sessionId: 54085233,
        appName: 'my-webapp',
        environment: 'default'
      },
      enabled: true,
      featureName: 'my-feature-toggle',
      variant: 'variantA'
    }

    Enabling impression data​

    Impression data is strictly an opt-in feature and must be enabled on a per-toggle basis. You can enable and disable it both when you create a toggle and when you edit a toggle.

    You can enable impression data via the impression data toggle in the admin UI's toggle creation form. You can also go via the the API, using the impressionData option. For more detailed instructions, see the section on enabling impression data in the how-to guide for capturing impression data.

    A feature toggle creation form. At the end of the form is a heading that says &quot;Impression data&quot;, a short paragraph that describes the feature, and a toggle to opt in or out of it.

    Example setup​

    The exact setup will vary depending on your client SDK. The below example configures the [Unleash Proxy client../reference/sdks/javascript-browser) to listen for impression events and log them to the console. If "my-feature-toggle" is configured to emit impression data, then it will trigger an impression event as soon as Unleash is ready.

    const unleash = new UnleashClient({
      url: 'https://eu.unleash-hosted.com/hosted/proxy',
      clientKey: 'your-proxy-key',
      appName: 'my-webapp',
    });

    unleash.start();

    unleash.on('ready', () => {
      unleash.isEnabled('my-feature-toggle');
    });

    unleash.on('impression', (event) => {
      // Capture the event here and pass it internal data lake or analytics provider
      console.log(event);
    });
    - + \ No newline at end of file diff --git a/reference/integrations.html b/reference/integrations.html index 8d987f386b..82fc28626c 100644 --- a/reference/integrations.html +++ b/reference/integrations.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Integrations

    Availability

    Unleash integrations were introduced in Unleash v3.11.0.

    Integrations were previously known as addons.

    Unleash integrations allows you to extend Unleash with new functionality and to connect to external applications.

    Unleash has two types of integrations: Integrations that allow you to listen to changes in Unleash and trigger updates in other systems (for instance via webhooks or direct integrations) and integrations that communicate with Unleash (such as the Jira integrations).

    Official integrations​

    Unleash currently supports the following integrations out of the box:

    • Datadog - Allows Unleash to post Updates to Datadog when a feature toggle is updated.
    • Jira Cloud - Allows you to create, view and manage Unleash feature flags directly from a Jira Cloud issue
    • Jira Server - Allows you to create and link Unleash feature flags directly from a Jira Server issue
    • Microsoft Teams - Allows Unleash to post updates to Microsoft Teams.
    • Slack App - The Unleash Slack App posts messages to the selected channels in your Slack workspace.
    • Webhook - A generic way to post messages from Unleash to third party services.
    Missing an integration? Request it!

    If you're looking for an integration that Unleash doesn't have at the moment, you can fill out this integration request form to register it with us.

    Deprecated integrations​

    These integrations are deprecated and will be removed in a future release:

    • Slack - Allows Unleash to post updates to Slack. Please try the new Slack App integration instead.

    Community integrations​

    Our wonderful community has also created the following integrations:

    Notes​

    When updating or creating a new integration configuration it can take up to one minute before Unleash picks up the new config on all instances due to caching.

    Integration pages​

    - + \ No newline at end of file diff --git a/reference/integrations/datadog.html b/reference/integrations/datadog.html index b9514509be..ed40fb2df5 100644 --- a/reference/integrations/datadog.html +++ b/reference/integrations/datadog.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Datadog

    This feature was introduced in Unleash v4.0.0.

    The Datadog integration allows Unleash to post Updates to Datadog when a feature toggle is updated. To set up this integration, you need to set up a webhook connector for your channel. You can follow Submitting events to Datadog on how to do that.

    The Datadog integration will perform a single retry if the HTTP POST against the Datadog Webhook URL fails (either a 50x or network error). Duplicate events may happen, and you should never assume events always comes in order.

    Configuration​

    Events​

    You can choose to trigger updates for the following events:

    • feature-created
    • feature-updated (*)
    • feature-metadata-updated
    • feature-project-change
    • feature-archived
    • feature-revived
    • feature-strategy-update
    • feature-strategy-add
    • feature-strategy-remove
    • feature-stale-on
    • feature-stale-off
    • feature-environment-enabled
    • feature-environment-disabled
    • feature-environment-variants-updated
    • feature-potentially-stale-on

    *) Deprecated, and will not be used after transition to environments in Unleash v4.3

    Parameters​

    Unleash Datadog integration takes the following parameters.

    • Datadog API key - This is a required property. The API key to use to authenticate with Datadog.

    • Datadog Source Type Name - This is an optional property. Sets source_type_name parameter to be included in Datadog events. List of valid api source values

    • Extra HTTP Headers - This is an optional property. Used to set the additional headers when Unleash communicates with Datadog.

    Example:

    {
      "SOME_CUSTOM_HTTP_HEADER": "SOME_VALUE",
      "SOME_OTHER_CUSTOM_HTTP_HEADER": "SOME_OTHER_VALUE"
    }
    Body template availability

    The body template property is available from Unleash 5.6 onwards.

    • Body template - This is an optional property. The template is used to override the body template used by Unleash when performing the HTTP POST. You can format your message using a Mustache template. Refer to the Unleash event types reference to find out which event properties you have access to in the template.

    Example:

    {
      "event": "{{event.type}}",
      "createdBy": "{{event.createdBy}}",
      "featureToggle": "{{event.data.name}}",
      "timestamp": "{{event.data.createdAt}}"
    }

    If you don't specify anything Unleash will send a formatted markdown body.

    Example:

    username created feature toggle (featurename)[http://your.url/projects/projectname/features/featurename] in project *projectname*

    Tags​

    Datadog's incoming webhooks are app specific. You will be able to create multiple integrations to support messaging on different apps.

    - + \ No newline at end of file diff --git a/reference/integrations/jira-cloud-plugin-installation.html b/reference/integrations/jira-cloud-plugin-installation.html index d2fba808d6..915dc3f289 100644 --- a/reference/integrations/jira-cloud-plugin-installation.html +++ b/reference/integrations/jira-cloud-plugin-installation.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Jira Cloud Integration - Installation

    Prerequisites​

    Jira Cloud​

    For Jira Data Center, check out the Jira Server plugin

    Unleash​

    • Unleash v4 or higher

    Required access levels​

    Unleash​

    You will need an Unleash admin user to configure the access tokens needed to connect the plugin to Unleash.

    This plugin requires an Unleash Pro or an Unleash Enterprise instance.

    We recommend using a service account token for communicating with Unleash. Service accounts are also required to integrate with Change Requests

    Jira​

    You will need a Jira admin user.

    Installation​

    Start by visiting the Landing page for the Unleash Enterprise For Jira plugin on Atlassian marketplace.

    Atlassian marketplace landing page for the Unleash Enterprise For Jira plugin.

    1. Click the yellow button in the top right corner labeled "Get it now"
    2. Choose which site to install the app to.
    3. Click the blue "Install app" button located at the bottom right.

    Configuring the plugin​

    After the plugin has been installed, each project's settings page in Jira will have a menu entry link called "Unleash Project Settings" under the "Apps" menu section.

    Jira Cloud project settings page with the apps menu open. The link to Unleash project settings is highlighted.

    Following that link takes you to the "Unleash Project Settings" configuration page. This is where you specify the connection details (Unleash server URL and access token) for the Unleash server to be used with this particular project.

    Jira Cloud: Unleash project settings. A form with inputs for Unleash URL and an Unleash auth token.

    Once you have configured the connection for the Unleash server, your users should be ready to use the Jira Cloud plugin

    - + \ No newline at end of file diff --git a/reference/integrations/jira-cloud-plugin-usage.html b/reference/integrations/jira-cloud-plugin-usage.html index d51392ca33..e7b59d8b1d 100644 --- a/reference/integrations/jira-cloud-plugin-usage.html +++ b/reference/integrations/jira-cloud-plugin-usage.html @@ -20,7 +20,7 @@ - + @@ -32,7 +32,7 @@ from Jira.

    Change Requests​

    The plugin respects Unleash's change requests. If change requests are turned on in the connected project and the selected environment, the plugin will ask whether you want to create a change request or not.

    If you already have an active change request for that project and that environment, the changes will be added to your existing change request.

    If you confirm that you would like to open a change request, then the plugin will create one for you and present a confirmation dialog.

    When the Change Request has been reviewed and applied in Unleash, the toggle will show the requested state after the next refresh of the issue and toggle status page.

    Disconnecting toggle from Issue​

    If a toggle is no longer relevant for your Jira Issue, you can disconnect it using the "disconnect toggle" button. This button is only available if your user has edit permissions for the Jira issue.

    Jira Cloud: issue with a connected toggle. The &#39;disconnect toggle&#39; button (highlighted) is displayed next to the toggle&#39;s name.

    The toggle will be disconnected immediately. However, the plugin will not delete the toggle from Unleash, so you can still reconnect your Jira issue to the same toggle using the "Connect to existing toggle" functionality

    - + \ No newline at end of file diff --git a/reference/integrations/jira-server-plugin-installation.html b/reference/integrations/jira-server-plugin-installation.html index f898a54765..57b33b54bf 100644 --- a/reference/integrations/jira-server-plugin-installation.html +++ b/reference/integrations/jira-server-plugin-installation.html @@ -20,7 +20,7 @@ - + @@ -36,7 +36,7 @@ server. Since this is a destructive operation, our plugin will ask for confirmation that you're sure you want to do this.

    A plugin deletion confirmation dialog. It gives you two options: &quot;Delete connection&quot;, and &quot;Cancel&quot;.

    You cannot delete a server that has toggles connected to issues. Instead, you'll get a warning dialog telling you that you'll need to disconnect the toggles from their issues first.

    A warning dialog telling you that you can&#39;t delete a server.

    - + \ No newline at end of file diff --git a/reference/integrations/jira-server-plugin-usage.html b/reference/integrations/jira-server-plugin-usage.html index 35c4695a7f..e342efbcc7 100644 --- a/reference/integrations/jira-server-plugin-usage.html +++ b/reference/integrations/jira-server-plugin-usage.html @@ -20,7 +20,7 @@ - + @@ -33,7 +33,7 @@ from Jira.

    Jira Server - Toggle status

    Disconnecting toggle from Issue​

    If a toggle is no longer relevant for your Jira Issue, you can disconnect it using the Disconnect toggle button ( provided your user has edit rights on the issue)

    Jira Server - Disconnect toggle

    Once you click the button, you'll need to confirm the dialog that opens up.

    Jira Server - Disconnect toggle dialog

    If confirmed, the toggle will be disconnected immediately. However, the plugin will not delete the toggle from Unleash, so you can still reconnect your Jira issue to the same toggle using the "Connect to existing toggle" functionality

    - + \ No newline at end of file diff --git a/reference/integrations/slack-app.html b/reference/integrations/slack-app.html index df004c34bc..9a7c73db7d 100644 --- a/reference/integrations/slack-app.html +++ b/reference/integrations/slack-app.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Slack App

    Availability

    The Slack App integration was introduced in Unleash 5.5.

    The Slack App integration posts messages to a specified set of channels in your Slack workspace. The channels can be public or private, and can be specified on a per-flag basis by using Slack tags.

    Installation​

    To install the Slack App integration, follow these steps:

    1. Navigate to the integrations page in the Unleash admin UI (available at the URL /integrations) and select "configure" on the Slack App integration.
    2. On the integration configuration form, use the "install & connect" button.
    3. A new tab will open, asking you to select the Slack workspace where you'd like to install the app.
    4. After successful installation of the Unleash Slack App in your chosen Slack workspace, you'll be automatically redirected to a page displaying a newly generated access token.
    5. Copy this access token and paste it into the Access token field within the integration settings.

    By default, the Unleash Slack App is granted access to public channels. If you want the app to post messages to private channels, you'll need to manually invite it to each of those channels.

    Configuration​

    The configuration settings allow you to choose the events you're interested in and whether you want to filter them by projects and environments. You can configure a comma-separated list of channels to post the configured events to. These channels are always notified, regardless of the event type or the presence of Slack tags.

    Events​

    You can choose to trigger updates for the following events:

    • addon-config-created
    • addon-config-deleted
    • addon-config-updated
    • api-token-created
    • api-token-deleted
    • change-added
    • change-discarded
    • change-edited
    • change-request-applied
    • change-request-approval-added
    • change-request-approved
    • change-request-cancelled
    • change-request-created
    • change-request-discarded
    • change-request-rejected
    • change-request-sent-to-review
    • context-field-created
    • context-field-deleted
    • context-field-updated
    • feature-archived
    • feature-created
    • feature-deleted
    • feature-environment-disabled
    • feature-environment-enabled
    • feature-environment-variants-updated
    • feature-metadata-updated
    • feature-potentially-stale-on
    • feature-project-change
    • feature-revived
    • feature-stale-off
    • feature-stale-on
    • feature-strategy-add
    • feature-strategy-remove
    • feature-strategy-update
    • feature-tagged
    • feature-untagged
    • group-created
    • group-deleted
    • group-updated
    • project-created
    • project-deleted
    • segment-created
    • segment-deleted
    • segment-updated
    • service-account-created
    • service-account-deleted
    • service-account-updated
    • user-created
    • user-deleted
    • user-updated

    Parameters​

    The Unleash Slack App integration takes the following parameters.

    • Access token - This is the only required property. After successful installation of the Unleash Slack App in your chosen Slack workspace, you'll be automatically redirected to a page displaying a newly generated access token. You should copy this access token and paste it into this field.
    • Channels - A comma-separated list of channels to post the configured events to. These channels are always notified, regardless of the event type or the presence of a Slack tag.

    Tags​

    Besides the configured channels, you can choose to notify other channels by tagging your feature flags with Slack-specific tags. For instance, if you want the Unleash Slack App to send notifications to the #general channel, add a Slack-type tag with the value "general" (or "#general"; both will work) to your flag. This will ensure that any configured events related to that feature flag will notify the tagged channel in addition to any channels configured on the integration-level.

    To exclusively use tags for determining notification channels, you can leave the "channels" field blank in the integration configuration. Since you can have multiple configurations for the integration, you're free to mix and match settings to meet your precise needs. Before posting a message, all channels for that event, both configured and tagged, are combined and duplicates are removed.

    We have defined two Slack tags for the "new-payment-system" flag. In this example Unleash will post updates to the #notifications and #random channels, along with any channels defined in the integration configuration.
    - + \ No newline at end of file diff --git a/reference/integrations/slack.html b/reference/integrations/slack.html index ac730da4ac..78f1081fe6 100644 --- a/reference/integrations/slack.html +++ b/reference/integrations/slack.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Slack (deprecated)

    Deprecation notice

    This Slack integration is deprecated and will be removed in a future release. We recommend using the new Slack App integration instead.

    This feature was introduced in Unleash v3.11.0.

    The Slack integration allows Unleash to post Updates when a feature toggle is updated. To set up Slack, you need to configure an incoming Slack webhook URL. You can follow Sending messages using Incoming Webhooks on how to do that. You can also choose to create a slack app for Unleash, which will provide you with additional functionality to control how Unleash communicates messages on your Slack workspace.

    The Slack integration will perform a single retry if the HTTP POST against the Slack Webhook URL fails (either a 50x or network error). Duplicate events may happen. You should never assume events always comes in order.

    Configuration​

    Events​

    You can choose to trigger updates for the following events:

    • feature-created
    • feature-updated (*)
    • feature-metadata-updated
    • feature-project-change
    • feature-archived
    • feature-revived
    • feature-strategy-update
    • feature-strategy-add
    • feature-strategy-remove
    • feature-stale-on
    • feature-stale-off
    • feature-environment-enabled
    • feature-environment-disabled

    *) Deprecated, and will not be used after transition to environments in Unleash v4.3

    Parameters​

    Unleash Slack integration takes the following parameters.

    • Slack Webhook URL - This is the only required property. If you are using a Slack Application you must also make sure your application is allowed to post to the channel you want to post to.
    • Username - Used to override the username used to post the update to a Slack channel.
    • Emoji Icon - Used to override the emoji icon used to post the update to a Slack channel.
    • Default channel - Where to post the message if the feature toggles has not overridden the channel via the slack tags.

    Global configuration​

    • Unleash URL - The slack plugin uses the server.unleashUrl property to create the link back to Unleash in the posts. This can be set using the UNLEASH_URL environment variable or the server.unleashUrl property when starting the server from node.

    Tags​

    The Slack integration also defined the Tag type "slack". You may use this tag to override which Slack channel Unleash should post updates to for this feature toggle.

    Slack Tags

    In the picture you can see we have defined two slack tags for the "new-payment-system" toggle. In this example Unleash will post updates to the #notifications and #random channel.

    - + \ No newline at end of file diff --git a/reference/integrations/teams.html b/reference/integrations/teams.html index 742fa08b9f..3ad65853c4 100644 --- a/reference/integrations/teams.html +++ b/reference/integrations/teams.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Microsoft Teams

    This feature was introduced in Unleash v4.0.0.

    The MicrosoftTeams integration allows Unleash to post Updates when a feature toggle is updated. To set up this integration, you need to set up a webhook connector for your channel. You can follow Creating an Incoming Webhook for a channel on how to do that.

    The Microsoft Teams integration will perform a single retry if the HTTP POST against the Microsoft Teams Webhook URL fails (either a 50x or network error). Duplicate events may happen, and you should never assume events always comes in order.

    Configuration​

    Events​

    You can choose to trigger updates for the following events:

    • feature-created
    • feature-updated (*)
    • feature-metadata-updated
    • feature-project-change
    • feature-archived
    • feature-revived
    • feature-strategy-update
    • feature-strategy-add
    • feature-strategy-remove
    • feature-stale-on
    • feature-stale-off
    • feature-environment-enabled
    • feature-environment-disabled

    *) Deprecated, and will not be used after transition to environments in Unleash v4.3

    Parameters​

    Unleash Microsoft Teams integration takes the following parameters.

    • Microsoft Teams Webhook URL - This is the only required property.

    Tags​

    Microsoft teams's incoming webhooks are channel specific. You will be able to create multiple integrations to support messaging on multiple channels.

    - + \ No newline at end of file diff --git a/reference/integrations/webhook.html b/reference/integrations/webhook.html index bab20892ef..6599e9f5a8 100644 --- a/reference/integrations/webhook.html +++ b/reference/integrations/webhook.html @@ -20,7 +20,7 @@ - + @@ -30,7 +30,7 @@
    Skip to main content

    Webhook

    This feature was introduced in Unleash v3.11.0.

    The Webhook Integration introduces a generic way to post messages from Unleash to third party services. Unleash allows you to define a webhook which listens for changes in Unleash and posts them to third party services.

    The webhook will perform a single retry if the HTTP POST call fails (either a 50x or network error). Duplicate events may happen, and you should never assume events always comes in order.

    Configuration​

    Events​

    You can choose to trigger updates for the following events (we might add more event types in the future):

    • feature-created
    • feature-updated (*)
    • feature-metadata-updated
    • feature-project-change
    • feature-archived
    • feature-revived
    • feature-strategy-update
    • feature-strategy-add
    • feature-strategy-remove
    • feature-stale-on
    • feature-stale-off
    • feature-environment-enabled
    • feature-environment-disabled

    *) Deprecated, and will not be used after transition to environments in Unleash v4.3

    Parameters​

    Unleash Webhook integration takes the following parameters.

    Webhook URL This is the only required property. If you are using a Slack Application you must also make sure your application is allowed to post the channel you want to post to.

    Content-Type Used to set the content-type header used when unleash performs an HTTP POST to the defined endpoint.

    Body template Used to override the body template used by Unleash when performing the HTTP POST. You may format you message using a Mustache template. You will have the Unleash event format available in the rendering context.

    Example:

    {
      "event": "{{event.type}}",
      "createdBy": "{{event.createdBy}}",
      "featureToggle": "{{event.data.name}}",
      "timestamp": "{{event.data.createdAt}}"
    }

    If you don't specify anything Unleash will use the Unleash event format.

    Custom SSL certificates​

    If your webhook endpoint uses a custom SSL certificate, you will need to start Unleash with the NODE_EXTRA_CA_CERTS environment variable set. It needs to point to your custom certificate file in pem format.

    For more information, see the official Node.js documentation on setting extra certificate files.

    - + \ No newline at end of file diff --git a/reference/login-history.html b/reference/login-history.html index efca9a42d3..6657cb3f4d 100644 --- a/reference/login-history.html +++ b/reference/login-history.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Login History

    Availability

    Login history is an enterprise feature available from Unleash 4.22 onwards.

    Unleash's login history lets you track login events in your Unleash instance, and whether the attempts were successful in logging in or not.

    Login history table

    For each login event, it lists:

    • Created: When it happened
    • Username: The username that was used
    • Authentication: The authentication type that was used
    • IP address: The IP address that made the attempt
    • Success: Whether the attempt was successful or not
    • Failure reason: If the attempt was not successful, the reason why

    You can see the failure reason by hovering over the "False" badge in the "Success" column.

    Login history table failure reason

    Use the login history to:

    • Audit login events in your Unleash instance
    • Identify failed login attempts and investigate the cause
    • Debug misconfigured authentication providers

    The login history is mutable: You can remove individual login events or clear the entire history by deleting all of them.

    Finally, the login history can be downloaded (how do I download my Unleash login history) for external backups, audits, and the like.

    Retention​

    Events in the login history are retained for 336 hours (14 days).

    Events older than the retention period are automatically deleted, and you won't be able to recover them. If you would like to collect login event information past the retention period, we suggest periodically downloading the login history.

    - + \ No newline at end of file diff --git a/reference/maintenance-mode.html b/reference/maintenance-mode.html index 8515787935..80fbeda3cf 100644 --- a/reference/maintenance-mode.html +++ b/reference/maintenance-mode.html @@ -20,7 +20,7 @@ - + @@ -30,7 +30,7 @@
    Skip to main content

    Maintenance Mode

    Availability

    Maintenance mode was introduced in Unleash 4.22.0.

    Unleash maintenance mode is a feature that lets administrators put Unleash into a mostly read-only mode. While Unleash is in maintenance mode:

    • Unleash users can not change any configuration settings
    • Unleash's APIs will not allow you to persist any changes

    However, any metrics sent to Unleash from client SDKs are still processed, so this mode does not have any effect on client SDKs.

    Maintenance mode is particularly useful during important events when any accidental or deliberate changes the feature/strategy configurations could lead to issues.

    Maintenance mode configuration​

    Maintenance mode is controlled from the "maintenance" section of the Unleash admin configuration page.

    Maintenance mode being toggled on

    When maintenance mode is enabled, a warning banner appears at the top of the Unleash dashboard, indicating that any changes made during this period will not be saved and may result in errors.

    Maintenance mode banner when maintenance mod is toggled on

    Maintenance mode and scheduled jobs​

    When maintenance mode is enabled all internal jobs performed by Unleash such as updating metrics and statistics are paused. When maintenance mode is toggled back to disabled later, all scheduled jobs are resumed.

    Maintenance mode and read-only DB user​

    When maintenance mode is enabled most DB operations are suspended so you can use even read-only DB user. There's one exception though. Unleash DB user role needs a DELETE and UPDATE permission on the unleash_session table.

    GRANT DELETE ON unleash_session TO my_db_role;
    GRANT UPDATE ON unleash_session TO my_db_role;
    - + \ No newline at end of file diff --git a/reference/network-view.html b/reference/network-view.html index f887899916..e21cbea1f0 100644 --- a/reference/network-view.html +++ b/reference/network-view.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Network View

    Availability

    The network view was released in Unleash 4.21. It is available to Pro and Enterprise users.

    You must configure the data source to activate the feature.

    The Unleash admin UI contains a network view as part of the admin configuration pages. This network view was designed to give you an overview and understanding of incoming requests to your Unleash instance. It makes it possible to pinpoint sources of sudden request surges, and can therefore also help you identify issues with SDK setups1.

    The network view offers two different visualizations of the same data, known as the network overview and the network traffic views.

    Because Unleash doesn't store this kind of data itself, the network view requires you to configure an external data source for the network overview to work. The network view is only available if you tell Unleash where it can find the data (refer to the data source section).

    The network view is intended to provide a simple and Unleash-centric overview that serves basic use cases. If you need detailed metrics and connection graphs, you may be better off using specialized network monitoring tools.

    Applications​

    Both the network overview and the network traffic diagrams show you applications that have made requests to the Unleash instance. An application is defined as anything that sends requests to the Unleash client API, the Unleash front-end API, the Unleash admin API, or any other API that Unleash exposes. This includes Unleash SDKs, Unleash Edge, the Unleash proxy, and even the admin UI.

    "unknown" applications​

    Requests that come from Unleash SDKs and other official Unleash applications will always have an application name defined. But you might sometimes see some applications listed as "unknown" in the diagrams.

    This happens when Unleash receives requests that don't contain an application name header (UNLEASH_APPNAME). This can happen, for instance, if you make HTTP requests from the command line to test Unleash connections or if you write your own HTTP client for Unleash that doesn't provide an application name.

    Because Unleash can't separate these based on their application names, all "unknown" clients will get lumped together as one application in the overview.

    Network overview​

    The network overview is a diagram that shows the Unleash instance and known applications that have connected to it within the last five minutes. Unknown applications are not shown.

    Each application shown on the diagram has:

    • An application name
    • the average number of requests per second (req/s) that we have registered over the last five minutes.
    The network overview shows applications that have recently made requests to Unleash. In this figure, it's showing three different instances of the Unleash proxy connected to Unleash. Each instance has an average of 20 req/s.

    Network traffic​

    The network traffic diagram is a line chart that presents requests that have used the most network traffic over the last six hours, grouped by client and base URL for the request. For legibility, this chart only shows the ten groups that have caused the most traffic over the last six hours.

    Unleash aggregates requests by client (using application name) and base URL. Base URLs are batched together using the first two path segments following the /api part of the URL. In essence, that means:

    1. Separate requests by API: Admin API requests are separate from client API requests.
    2. Within each of these groups, group all requests by their next URL path segment. For instance: /client/features and /client/features/feature-a are grouped together, while /client/register and /admin/features are separate groups.
    The network traffic chart plots req/s on the Y axis and time on the X axis. Requests are bundled per endpoint per application.

    Data source​

    Prometheus and other sources

    The network view was written to be used with Prometheus and is therefore compatible with Prometheus' API.

    Other services that offer the same capabilities and the same API may work as substitutes, but we make no guarantees.

    This section will refer to the external source as Prometheus for simplicity.

    The network view uses an external Prometheus-like API to create diagrams. Because of this, Unleash will not enable the network view feature unless you set the PROMETHEUS_API environment variable.

    The PROMETHEUS_API environment variable should point to the base path of the Prometheus installation, and Prometheus should be configured to get its data from Unleash's internal backstage API. This can for example be done via a scraping job2:

    Scraping job for Unleash metrics
      - job_name: unleash_internal_metrics
        metrics_path: /internal-backstage/prometheus
        static_configs:
          - targets: ['unleash-url']

    This setup means that there is a mutual dependency between Unleash and Prometheus, where Prometheus regularly fetches data from Unleash's backstage API and Unleash fetches and displays this data when you use the network view. This diagram provides a visual representation of that.

    1. For instance: when using Unleash in an API setting, a common mistake is to instantiate a new SDK for every request instead of sharing a single instance across requests. This would be visible in the network overview graph as a large number of requests from the same app.↩
    2. How to set up Prometheus to collect metrics from that API is outside of the scope of this document.↩
    - + \ No newline at end of file diff --git a/reference/notifications.html b/reference/notifications.html index 8f39435d4a..fe9777ac27 100644 --- a/reference/notifications.html +++ b/reference/notifications.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Notifications

    Availability

    Notifications were introduced in Unleash 4.22.0 for pro and enteprise customers.

    Unleash's notifications give you updates when certain events occur in projects that you are part of. The notifications are accessible from the notifications button in the navigation section of the admin UI.

    Your notifications will only contain updates from other members; you will not get notifications about actions you perform yourself.

    The notifications overview. It&#39;s telling the user about a feature that was enabled in production and that there is a change request ready for review.

    From within the notifications list, you can:

    • navigate to the features or change request that the notification is for
    • mark all notifications as read
    • filter out unread notifications

    Notifications can not be disabled.

    Notification events​

    The following actions in your projects will trigger notifications for your project members:

    • Creating a feature
    • Archiving a feature
    • Enabling a feature in an environment
    • Submitting a change request
    • Approving change request
    • Rejecting change request
    • Applying change request
    - + \ No newline at end of file diff --git a/reference/playground.html b/reference/playground.html index cb852946b1..c2d1ec488b 100644 --- a/reference/playground.html +++ b/reference/playground.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Playground

    Availability

    The Unleash playground is available in all Unleash versions from Unleash 4.14 onwards. Unleash 5.3 introduced a more advanced playground that allows you to query multiple environments and multiple values for a single context value at the same time.

    The Unleash Playground form and an indication of where in the nav menu it is located.

    The unleash playground is a part of the Unleash Admin UI and an accompanying API. The playground lets you see which of your instance's feature toggles would be enabled for a given Unleash context. It has multiple uses, such as:

    • Understanding how Unleash evaluates strategies, constraints, and segments.
    • Debugging Unleash contexts and toggles behaving differently from what you expect.
    • Tailoring a set of strategies for given contexts.

    Each feature toggle will contain info on whether it was enabled or not and which variant it was assigned. Later versions of the playground also contain detailed evaluation results to help you understand exactly why the feature was enabled or disabled.

    Configuring the query​

    This section describes what information the playground needs to evaluate your Unleash context against your existing features.

    Environments and projects​

    The playground needs to know which environments and which projects to use when evaluating features. The playground UI will default to using the first environment in your list of instance environments and all projects.

    You can select as many of your environments as you want. All environments must be environments that exist in your Unleash instance. Prior to Unleash 5.3, features could only be evaluated against a single environment at a time.

    The playground will only evaluate features belonging to the projects you specify. The projects parameter can either be a list of projects or all projects.

    The Unleash context​

    The Unleash context represents a client SDK's configuration and used for evaluating your features. You can construct your own context or use a JSON version of a context from a client.

    Multiple values for a single context field​

    Availability

    The ability to specifiy multiple values for a single context field was introduced in Unleash 5.3.

    You can specify multiple values for a single context field by separating the values with a comma. For instance: "value1, value2".

    When you specify multiple values for context field, each value will be used to populate one variant of the response.

    Implicit context fields​

    You can add any fields you want to the context used for the evaluation, and you can also leave out any fields you want. However, there are some fields that will be set for you if don't provide them:

    • appName: Unleash clients all require an appName to start up. If you do not provide an appName, the playground will assign a default value to this property instead.
    • currentTime: The currentTime property of the Unleash context gets auto-populated with the current time. You can override this manually by providing a value of your own.

    The response​

    Playground results: a table of feature names and whether they&#39;re enabled or not.

    The playground's response contains a list of all the feature toggles that have been evaluated based on your configured environments, projects and context. The full response will contain results for all combinations of context fields and all environments that you selected.

    In the UI, the playground displays the features in a table. Each row of the table corresponds to a single feature. The table has a separate column for each of the environments that you selected for your query.

    Each row contains a feature and columns for the selected environments. In this screenshot, the "development" and "production" environments have been selected.

    Because you can add multiple values for each context field, each feature-environment cell contains the number of combinations that evaluated to true and false for the feature in the given environment. This can be expanded into a more detailed overview over what combinations of context fields evaluated to true and false along with any variants.

    A small table showing the detailed evaluation for a feature in the "development" environment. The provided context contained three values for the "userId" property, so the table contains three rows, showing all different combinations of the context.

    As with all of Unleash's client SDKs, the playground respects stickiness. The stickiness algorithm guarantees that you'll always get the same variants and the same gradual rollout results if you provide the same context, as long as you provide the context field used for calculating stickiness.

    The diff view​

    You can compare how a feature evaluates in different environments. If you select more than one environment for your playground query, the table will have an additional "Diff" column in each row. Using the "preview diff" button, you can open a table that gives an overview over how the feature evaluated for each context combination in each environment.

    A table with three rows. Each row contains a context combination and results in the form of `true` and `false` each environment. In this case, it shows that when the "userId" context field is "2", then the feature is enabled in development, but not in production.

    Detailed evaluation results​

    Availability

    Detailed evaluation results were added to the playground in Unleash 4.15.

    Detailed strategy evaluation results. A list of strategies and their constraints along with indicators of whether each one is `true` or `false`.

    Each feature in the response contains information about all of its evaluated strategies. Each of a feature's strategies lists all of the strategies constraints and segments and how it all evaluated (as best as the playground can, as mentioned in the unknown strategies section).

    In addition to the results of individual strategies, each strategy is also assigned an overall strategy evaluation result: one of true, false, and unknown. The rules for the overall result are:

    • If at least one strategy evaluates to true, then the overall result is true.
    • If all strategies evaluate to false, the overall result is false.
    • If one or more strategies evaluate to unknown and all other strategies evaluate to false, then the overall result is unknown.

    Unknown strategies​

    Not all strategies can be correctly evaluated by the playground. Strategies that cannot be fully evaluated will be given an evaluation result status of 'unknown'.

    There's currently two cases where the playground can't evaluate the strategy:

    1. The strategy is a custom strategy and the playground doesn't have an implementation for the strategy.
    2. The strategy is the 'Application Hostname' strategy.

    Even if the playground doesn't recognize or otherwise can't evaluate a specific strategy, it may still evaluate the overall strategy result to false (and be certain that it is the right result). If a strategy has constraints or segments that are not satisfied, the playground knows that the strategy result wouldn't be true, regardless of the actual strategy implementation. As such, if a strategy can't be evaluated, it can be either unknown or false.

    Custom Strategies​

    The playground does not have any implementations for custom strategies and adding custom strategy implementations to Unleash is not currently supported. Because of this, custom strategies will never be evaluated as true.

    The Application Hostname strategy​

    The application hostname strategy is a little different from the other built-in strategies: it depends on external state and not on the Unleash context to evaluate. In short, the strategy checks its application environment to get the hostname, so the Unleash context has no effect on the result of this strategy.

    Because the application hostname strategy depends on external state, the playground can't guarantee whether the strategy would be true or false in a client. Further, the result in the playground would most likely be different from what you'd see in a client. Because of this, the playground does not evaluate this strategy.

    - + \ No newline at end of file diff --git a/reference/project-collaboration-mode.html b/reference/project-collaboration-mode.html index fcaa70cda7..d3f8ce6a67 100644 --- a/reference/project-collaboration-mode.html +++ b/reference/project-collaboration-mode.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Project Collaboration Mode

    Availability

    The project collaboration mode is an enterprise-only feature that was introduced in Unleash 4.22.0.

    A project's collaboration mode specifies who can submit change requests. There are two collaboration modes:

    Open collaboration mode​

    Anyone can submit change requests in an open project, regardless of their permissions within the project and globally. This is the default collaboration mode for projects.

    The open collaboration mode is the default in Unleash and is how all projects worked in Unleash before the introduction of collaboration modes.

    Protected collaboration mode​

    Only admins and project members can submit change requests in a protected project. Other users can not submit change requests.

    Private collaboration mode​

    Private collaboration mode renders the project invisible to all viewers who are not project members. This means that viewers cannot see the project in the project list, nor can they access the project's features or locate the project anywhere within Unleash.

    Editors and admins can still see private projects.

    Change requests​

    When you change a project's collaboration mode from open to protected, users who do not have the right permissions will lose the ability to create new change requests.

    However, existing change requests created by these users will not be deleted. Any users with open change requests will still be able to cancel the change request, but they will not be able to update the change request.

    Project collaboration mode setting​

    The collaboration mode for a project can be set at the time of creation and modified at any subsequent time, found within the 'Enterprise Settings' section.

    Project creation form with a collaboration mode field and corresponding explanation.

    Since the collaboration mode is an integral feature of the project, the options to modify it can be found on the 'Project Settings' page.

    The project-level header section with the &quot;edit project&quot; button highlighted.

    Pre-existing projects​

    Projects that were created in earlier versions of Unleash (before the release of project collaboration modes) get the open mode when they are migrated to a version of Unleash with project collaboration modes.

    To change the project collaboration mode for an existing project you have to edit the project.

    - + \ No newline at end of file diff --git a/reference/projects.html b/reference/projects.html index 0b5348fa9c..71b74584f6 100644 --- a/reference/projects.html +++ b/reference/projects.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Projects

    feature availability

    All users get access to projects, but only pro and enterprise users can create, update, or delete them.

    This document explains how Unleash uses projects, including how to create and maintain them.

    The default project​

    All users get access to the default project. You cannot delete this project. You can, however, rename it if you're using the pro or enterprise version of Unleash.

    Understanding purpose of projects​

    Projects are a way to organize your feature toggles within Unleash. Within a large organization, having multiple feature toggles, staying on top of the feature toggles might become a challenge. Every feature toggle will be part of a project. Projects can be linked to a development team or to functional modules within the software.

    A common pattern is to organize the feature toggles according to key areas of the application, e.g. “Basic user process” and “Advanced user process”. This is illustrated below.

    A diagram with two boxes labeled &quot;Basic user process&quot; and &quot;Advanced user process&quot;, respectively. The former contains features &quot;New login&quot; and &quot;Winter theme enablement&quot;, the latter &quot;New in-app purchase&quot; and &quot;Updated invoice repository&quot;.

    Projects and environments​

    You can configure which environments should be available within a project. By default, all globally available environments are available. You can only enable/disable a feature toggle for the environments you configure for a project.

    Within the admin UI, the projects are available under the "environments" tab of the project page. Changing them requires the project owner role.

    Creating a new project​

    When you log into Unleash for the first time, there is a Default project already created. All feature toggles are included in the Default project, unless explicitly set to a different one.

    From the top-line menu – click on “Projects”

    The Unleash admin UI with the &quot;Projects&quot; nav link in the top bar highlighted.

    The UI shows the currently available projects. To create a new project, use the “new project” button.

    A list of projects. There is a button saying &quot;Add new project&quot;.

    The configuration of a new Project is now available. the following input is available to create the new Project.

    A project creation form. The &quot;Create&quot; button is highlighted.

    ItemDescription
    Project IdId for this Project
    Project nameThe name of the Project.
    DescriptionA short description of the project
    ModeThe project collaboration mode
    Default StickinessThe default stickiness for the project. This setting controls the default stickiness value for variants and for the gradual rollout strategy.

    Deleting an existing project​

    To keep your feature toggles clean, removing deprecated projects is important. From the overview of Projects –

    1. In the top right of the project card, find the project menu represented by three vertical dots.

    A list of projects. Each project has three vertical dots — a kebab menu — next to it.

    1. Click on Delete Project

    A list of projects. Each project has three vertical dots — a kebab menu — next to it, which exposes a menu with the &quot;Edit project&quot; and &quot;Delete project&quot; options when interacted with.

    Filter feature toggles on projects​

    When browsing the feature toggles in Unleash, you might want to filter the view by looking only at the ones included in the project of interest. This is possible from the Feature toggle overview.

    From the UI top navigation menu, choose "Feature toggles".

    The Unleash Admin UI navigation menu with the &quot;Feature toggles&quot; option highlighted by a red arrow.

    The list of features toggles can be filtered on the project of your choice. By default, all feature toggles are listed in the view. You can use the search to filter to a specific project or even for multiple projects in the same time if you need.

    The feature toggle list with toggles scoped to the &quot;fintech&quot; project. The filter is activated by using a form control.

    In the search you can type "project:specific-name" to filter that project only.

    The feature toggle list with an overlay listing all the projects available. You can select a project and the list will update with the toggles belonging to that project.

    The view will now be updated with the filtered feature toggles.

    Assigning project to a new feature toggle​

    When you create a new feature toggle, you can choose which project to create it in. The default project is whatever project you are currently configuring.

    A form to create a toggle. An arrow points to an input labeled &quot;project&quot;.

    All available projects are available from the drop-down menu.

    A form to create a toggle. The &quot;project&quot; input is expanded to show projects you can create the toggle in.

    Change project for an existing feature toggle​

    If you want to change which project a feature toggle belongs to, you can change that from the feature toggle's configuration page. Under the settings tab, choose the project option and choose the new project from the dropdown menu.

    A feature toggle&#39;s settings tab. The project setting shows a dropdown to change projects.

    Project default strategy​

    Availability

    The project default strategy feature is generally available starting with Unleash 5.2.0.

    You can define default strategies for each of a project's environments. The default strategy for an environment will be added to a feature when you enable it in an environment if and only if the feature has no active strategies defined.

    All default project strategies use the gradual rollout activation strategy. By default, the rollout 100%. You can customize the strategies by changing the rollout percentage and adding constraints and segments as you would for any other strategy.

    Configuration​

    Custom strategies are configured from each project's project settings tab.

    The default strategy configuration page is available from the project settings tab.

    The default strategies screen lists a strategy for each of the project's environments

    Each strategy can be individually configured with the corresponding edit button.

    Project overview​

    The project overview gives statistics for a project, including:

    • the number of all changes/events in the past 30 days compared to previous 30 days
    • the average time from when a feature was created to when it was enabled in the "production" environment. This value is calculated for all features in the project lifetime.
    • the number of features created in the past 30 days compared to previous 30 days
    • the number of features archived in the past 30 days compared to previous 30 days

    Project overview with 4 statistics for total changes, average time to production, features created and features archived.

    - + \ No newline at end of file diff --git a/reference/public-signup.html b/reference/public-signup.html index 027a60e369..e4d4d1f036 100644 --- a/reference/public-signup.html +++ b/reference/public-signup.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Public Invite Links

    Public invite links let you invite team members to your Unleash instance. Any user with an invite link can sign up to Unleash instance that created the link. The user will get the viewer role (refer to the predefined roles_ section of the RBAC document for more information on roles).

    User who follow the invite link are taken directly to the Unleash sign-up page, where they can create an account.

    Only Unleash instance admins can create public invite links.

    An Unleash signup form for new users

    Public sign-up tokens​

    The most important part of a public sign-up link is the sign-up token. The token is added as the invite query parameter to the invite link.

    Each token has an expiry date. After this expiry date, the token will stop working and users can no longer sign up using an invite link with that token.

    Creating, updating, and deleting tokens​

    You can create, update and delete tokens via the Unleash Admin UI or via the Unleash API.

    A token is active as soon as it's created and stops working as soon as it's deleted or expired.

    You can only have one active invite token at a time. If you already have an active token, you must delete it to create a new one.

    - + \ No newline at end of file diff --git a/reference/rbac.html b/reference/rbac.html index c6c15cb4fa..1029a281cb 100644 --- a/reference/rbac.html +++ b/reference/rbac.html @@ -20,7 +20,7 @@ - + @@ -68,7 +68,7 @@ within the admin UI. The API endpoints have been superseded by the create/overwrite environment variants (PUT) and update environment variants (PATCH) endpoints, respectively.↩
    - + \ No newline at end of file diff --git a/reference/sdks.html b/reference/sdks.html index 6cdd1d25ea..fbcbf41178 100644 --- a/reference/sdks.html +++ b/reference/sdks.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    SDK overview

    In order to connect your application to Unleash you will need a client SDK (software developer kit) for your programming language and an API token. The SDK will handle connecting to the Unleash server instance and retrieving feature toggles based on your configuration. All versions of Unleash (OSS, Pro, and Enterprise) use the same client SDKs.

    Unleash provides official client SDKs for a number of programming language. Additionally, our community have developed and contributed SDKs for other languages. So if you can't find your favorite language in the list of official SDKs, check out the list of clients written by our fantastic community.

    Official SDKs​

    Server-side SDKs:​

    Server-side clients run on your server and communicate directly with your Unleash instance. We provide these official clients:

    Client-side SDKs​

    Client-side SDKs can connect to the Unleash Proxy or to the Unleash front-end API, but not to the regular Unleash client API.

    Server-side SDK compatibility table​

    The below table shows what features the various server-side SDKs support. Note that certain features make sense only for some clients due to how the programming language works or due to how the client works.

    Legend:

    • ✅: Implemented
    • ⭕: Not yet implemented, but we're looking into it
    • ❌: Not implemented, not planned
    • N/A: Not applicable to this SDK
    note

    If you see an item marked with a ❌ that you would find useful, feel free to reach out to us (on Slack, for instance) with your use case. It may not be something we can prioritize right now, but if you'd like to contribute it back to the community, we'd love to help you build it.

    CapabilityJavaNode.jsGoPythonRuby.NETPHPRust
    Category: Initialization
    Async initialization✅✅✅✅✅✅❌✅
    Can block until synchronized✅✅✅⭕⭕✅✅⭕
    Default refresh interval10s15s15s15s15s30s30s15s
    Default metrics interval60s60s60s60s60s60s30s15s
    Context provider✅N/AN/AN/AN/A✅✅N/A
    Global fallback function✅✅✅✅❌❌❌❌
    Toggle Query: namePrefix✅✅❌❌❌❌✅❌
    Toggle Query: tags✅✅❌❌❌❌✅❌
    Toggle Query: project_name✅✅✅✅✅✅N/A⭕
    Category: Custom Headers
    static✅✅✅✅✅✅✅⭕
    function✅✅⭕✅✅ (4.3)✅✅⭕
    Category: Built-in strategies
    Standard✅✅✅✅✅✅✅✅
    Gradual rollout✅✅✅✅✅✅✅✅
    Gradual rollout: custom stickiness✅✅✅✅✅✅✅⭕
    UserID✅✅✅✅✅✅✅✅
    IP✅✅✅✅✅✅✅✅
    IP: CIDR syntax✅✅✅✅✅⭕✅✅
    Hostname✅✅✅✅✅✅✅✅
    Category: Custom strategies
    Basic support✅✅✅✅✅✅✅✅
    Category: Strategy constraints
    Basic support (IN, NOT_IN operators)✅✅✅✅✅✅✅✅
    Advanced support (Semver, date, numeric and extended string operators) (introduced in)✅ (5.1)✅ (3.12)✅ (3.3)✅ (5.1)✅ (4.2)✅ (2.1)✅ (1.3.1)⭕
    Category: Unleash Context
    Static fields (environment, appName)✅✅✅✅✅✅✅✅
    Defined fields✅✅✅✅✅✅✅✅
    Custom properties✅✅✅✅✅✅✅✅
    Category: isEnabled
    Can take context✅✅✅✅✅✅✅✅
    Override fallback value✅✅✅✅✅✅✅✅
    Fallback function✅✅✅✅✅⭕⭕⭕
    Category: Variants
    Basic support✅✅✅✅✅✅✅✅
    Custom fallback variant✅✅✅✅✅✅✅⭕
    Custom weight✅✅✅✅✅✅✅⭕
    Custom stickiness✅✅✅✅✅✅✅⭕
    Strategy Variants✅✅✅✅✅✅✅⭕
    Category: Local backup
    File based backup✅✅✅✅✅✅✅⭕
    Category: Usage metrics
    Can disable metrics✅✅✅✅✅✅✅✅
    Client registration✅✅✅✅✅✅✅✅
    Basic usage metrics (yes/no)✅✅✅✅✅✅✅✅
    Impression data✅✅⭕✅⭕⭕✅⭕
    Category: Bootstrap (beta)
    Bootstrap from file✅✅✅✅✅✅✅⭕
    Custom Bootstrap implementation✅✅✅✅✅✅✅⭕

    Community SDKs ❤️​

    Here's some of the fantastic work our community has done to make Unleash work in even more contexts. If you still can't find your favorite language, let us know and we'd love to help you create the client for it!

    Implement your own SDK​

    If you can't find an SDK that fits your need, you can also develop your own SDK. To make implementation easier, check out these resources:

    • Unleash Client Specifications - Used by all official SDKs to make sure they behave correctly across different language implementations. This lets us verify that a gradual rollout to 10% of the users would affect the same users regardless of which SDK you're using.
    • Client SDK overview - A brief, overall guide of the Unleash Architecture and important aspects of the SDK role in it all.

    Client-side SDK behavior​

    The following section details the behavior of frontend / client-side SDKs when initializing and fetching flags with respect to network connectivity.

    When the SDK is initialized in the application, an in memory repository is setup and synchronized against the frontent API using the configured token and context. Note that the frontend API is hosted by either the Unleash Proxy/Edge or the upstream Unleash instance directly.

    1. All feature flag evaluation is performed by the Proxy/Edge or Unleash instance. A payload of all enabled flags and their variants (if applicable) is returned as a single request. Disabled flags are not included.

    2. When a page inside the application requests a feature flag, the SDK will return the flag state from memory. No network connection to the frontend API is performed.

    3. The SDK periodically syncs with the frontend API to retrieve the latest set of enabled toggles

    Working offline​

    Once they have been initialized, all Unleash clients will continue to work perfectly well without an internet connection or in the event that the Unleash Server has an outage.

    Because the SDKs and the Unleash Proxy/Edge cache their feature toggle states locally and only communicate with the Unleash server (in the case of the server-side SDKs and the Proxy) or the Proxy/Edge (in the case of front-end SDKs) at predetermined intervals, a broken connection only means that they won't get any new updates.

    Unless the SDK supports bootstrapping, it will need to connect to Unleash at startup to get its initial feature toggle data set. If the SDK doesn't have a feature toggle data set available, all toggles will fall back to evaluating as disabled or as the specified default value (in SDKs that support that).

    Bootstrapping​

    By default, all SDKs reach out to the Unleash Server at startup to fetch their toggle configuration. Additionally, some of the server-side SDKs and the Proxy (see the above compatibility table) also support bootstrapping, which allows them to get their toggle configuration from a file, the environment, or other local resources. These SDKs can work without any network connection whatsoever.

    Bootstrapping is also supported by the following front-end client SDKs:

    - + \ No newline at end of file diff --git a/reference/sdks/android-proxy.html b/reference/sdks/android-proxy.html index 117f8b9001..3c150c62f1 100644 --- a/reference/sdks/android-proxy.html +++ b/reference/sdks/android-proxy.html @@ -20,7 +20,7 @@ - + @@ -34,8 +34,8 @@ You can configure the pollInterval and a listener that gets notified when toggles are updated in the background thread. If you set the poll interval to 0, the SDK will fetch once, but not set up polling.

    The listener is a no-argument lambda that gets called by the RefreshPolicy for every poll that

    1. Does not return 304 - Not Modified
    2. Does not return a list of toggles that's exactly the same as the one we've already stored in local cache. Just in case the ETag/If-None-Match fails.

    Example usage is equal to the Example setup above

    val context = UnleashContext.newBuilder()
        .appName("Your AppName")
        .userId("However you resolve your userid")
        .sessionId("However you resolve your session id")
        .build()
    val config = UnleashConfig.newBuilder()
        .proxyUrl("URL to your front-end API or proxy")
        .clientKey("your front-end API token or proxy client key")
        .pollingMode(PollingModes.autoPoll(60) { // poll interval in seconds
            featuresUpdated()
        })
        .build()
    val client = UnleashClient(unleashConfig = config, unleashContext = context)
    FilePolling (since v0.2)​

    The name FilePolling can be a tad misleading, since this policy doesn't actually poll, it simply loads a file of toggles from disk on startup, and uses that to answer all client calls. Useful when your app might have limited internet connectivity, you'd like to run tests with a known toggle state or you simply do not want background activity.

    The following example shows how to use it, provided the file to use is located at /tmp/proxyresponse.json

    val toggles = File("/tmp/proxyresponse.json")
    val pollingMode = PollingModes.fileMode(toggles)
    val context = UnleashContext.newBuilder()
        .appName("Your AppName")
        .userId("However you resolve your userid")
        .sessionId("However you resolve your session id")
        .build()
    val config = UnleashConfig.newBuilder()
        .proxyUrl("URL to your front-end API or proxy") // These two don't matter for FilePolling,
        .clientKey("front-end API token / proxy client key") // since the client never speaks to the proxy
        .pollingMode(pollingMode)
        .build()
    val client = UnleashClient(unleashConfig = config, unleashContext = context)

    Metrics (since v0.2)​

    If you'd like the client to post metrics to the proxy so the admin interface can be updated, add a call to enableMetrics().

    NB Only supported by SDK version >=26​

    val config = UnleashConfig
        .newBuilder()
        .appName()
        .userId()
        .sessionId()
        .enableMetrics()
        .build()

    The default configuration configures a daemon to report metrics once every minute, this can be altered using the metricsInterval(long milliseconds) method on the builder, so if you'd rather see us post in 5 minutes intervals you could do

    UnleashConfig().newBuilder().metricsInterval(300000) // Every 5 minutes

    Example main activity​

    In the sample app -we use this to update the text on the first view

     this@MainActivity.runOnUiThread {
        val firstFragmentText = findViewById<TextView>(R.id.textview_first)
        firstFragmentText.text = "Variant ${unleashClient.getVariant("unleash_android_sdk_demo").name}"
     }

    This content was generated on

    - +we use this to update the text on the first view

     this@MainActivity.runOnUiThread {
        val firstFragmentText = findViewById<TextView>(R.id.textview_first)
        firstFragmentText.text = "Variant ${unleashClient.getVariant("unleash_android_sdk_demo").name}"
     }

    This content was generated on

    + \ No newline at end of file diff --git a/reference/sdks/dotnet.html b/reference/sdks/dotnet.html index 15fcc00d3d..4666071cb1 100644 --- a/reference/sdks/dotnet.html +++ b/reference/sdks/dotnet.html @@ -20,7 +20,7 @@ - + @@ -37,8 +37,8 @@ HttpClientFactory that inherits from DefaultHttpClientFactory, and override the method CreateHttpClientInstance. Then configure UnleashSettings to use your custom HttpClientFactory. 

    internal class CustomHttpClientFactory : DefaultHttpClientFactory
    {
        protected override HttpClient CreateHttpClientInstance(Uri unleashApiUri)
        {
            var messageHandler = new CustomHttpMessageHandler();
            var httpClient = new HttpClient(messageHandler)
            {
                BaseAddress = apiUri,
                Timeout = TimeSpan.FromSeconds(5)
            };
        }
    }

    var settings = new UnleashSettings
    {
        AppName = "dotnet-test",
        //...
        HttpClientFactory = new CustomHttpClientFactory()
    };

    Dynamic custom HTTP headers​

    If you need custom http headers that change during the lifetime of the client, a provider can be defined via the UnleashSettings. 

    Public Class CustomHttpHeaderProvider
        Implements IUnleashCustomHttpHeaderProvider

        Public Function GetCustomHeaders() As Dictionary(Of String, String) Implements IUnleashCustomHttpHeaderProvider.GetCustomHeaders
            Dim token = ' Acquire or refresh a token
            Return New Dictionary(Of String, String) From
                    {{"Authorization", "Bearer " & token}}
        End Function
    End Class

    ' ...

    Dim unleashSettings As New UnleashSettings()
    unleashSettings.AppName = "dotnet-test"
    unleashSettings.InstanceTag = "instance z"
    ' add the custom http header provider to the settings
    unleashSettings.UnleashCustomHttpHeaderProvider = New CustomHttpHeaderProvider()
    unleashSettings.UnleashApi = new Uri("http://unleash.herokuapp.com/api/")
    unleashSettings.UnleashContextProvider = New AspNetContextProvider()
    Dim unleash = New DefaultUnleash(unleashSettings)

    Logging​

    By default Unleash-client uses LibLog to integrate with the currently configured logger for your application. The supported loggers are:

    Custom logger integration​

    To plug in your own logger you can implement the ILogProvider interface, and register it with Unleash:

    Unleash.Logging.LogProvider.SetCurrentLogProvider(new CustomLogProvider());
    var settings = new UnleashSettings()
    //...

    The GetLogger method is responsible for returning a delegate to be used for logging, and your logging integration should be placed inside that delegate:

    using System;
    using Unleash.Logging;

    namespace Unleash.Demo.CustomLogging
    {
        public class CustomLogProvider : ILogProvider
        {
            public Logger GetLogger(string name)
            {
                return (logLevel, messageFunc, exception, formatParameters) =>
                {
                    // Plug in your logging code here

                    return true;
                };
            }

            public IDisposable OpenMappedContext(string key, object value, bool destructure = false)
            {
                return new EmptyIDisposable();
            }

            public IDisposable OpenNestedContext(string message)
            {
                return new EmptyIDisposable();
            }
        }

        public class EmptyIDisposable : IDisposable
        {
            public void Dispose()
            {
            }
        }
    }

    Local backup​

    By default unleash-client fetches the feature toggles from unleash-server every 20s, and stores the result in temporary .json file which is located in System.IO.Path.GetTempPath() directory. This means that if the unleash-server becomes unavailable, the unleash-client will still be able to toggle the features based on the values stored in .json file. As a result of this, the second argument of IsEnabled will be returned in two cases:

    The backup file name will follow this pattern: {fileNameWithoutExtension}-{AppName}-{InstanceTag}-{SdkVersion}.{extension}, where InstanceTag is either what you configure on UnleashSettings during startup, or a formatted string with a random component following this pattern: {Dns.GetHostName()}-generated-{Guid.NewGuid()}.

    You can configure InstanceTag like this:

    var settings = new UnleashSettings()
    {
        AppName = "dotnet-test",
        UnleashApi = new Uri("http://unleash.herokuapp.com/api/"),
        // Set an instance tag for consistent backup file naming
        InstanceTag = "CustomInstanceTag",
        UnleashContextProvider = new AspNetContextProvider(),
        CustomHttpHeaders = new Dictionary<string, string>()
        {
            {"Authorization", "API token" }
        }
    };

    Bootstrapping​

    Configuring with the UnleashSettings:

    var settings = new UnleashSettings()
    {
        AppName = "dotnet-test",
        UnleashApi = new Uri("http://unleash.herokuapp.com/api/"),
        CustomHttpHeaders = new Dictionary()
        {
          {"Authorization","API token" }
        },
        ToggleOverride = false, // Defaults to true
        ToggleBootstrapProvider = new MyToggleBootstrapProvider() // A toggle bootstrap provider implementing IToggleBootstrapProvider here
    };

    Provided Bootstrappers​

    ToggleBootstrapFileProvider​

    settings.UseBootstrapFileProvider("./path/to/file.json");

    ToggleBootstrapUrlProvider​

    var shouldThrowOnError = true; // Throws for 500, 404, etc
    var customHeaders = new Dictionary<string, string>()
    {
        { "Authorization", "Bearer ABCdefg123" } // Or whichever set of headers would be required to GET this file
    }; // Defaults to null
    settings.UseBootstrapUrlProvider("://domain.top/path/to/file.json", shouldThrowOnError, customHeaders);

    Json Serialization​

    The unleash client is dependant on a json serialization library. If your application already have Newtonsoft.Json >= 9.0.1 installed, everything should work out of the box. If not, you will get an error message during startup telling you to implement an 'IJsonSerializer' interface, which needs to be added to the configuration.

    With Newtonsoft.Json version 7.0.0.0, the following implementation can be used. For older versions, consider to upgrade.

    var settings = new UnleashSettings()
    {
        AppName = "dotnet-test",
        UnleashApi = new Uri("http://unleash.herokuapp.com/api/"),
        JsonSerializer = new NewtonsoftJson7Serializer()
    };

    public class NewtonsoftJson7Serializer : IJsonSerializer
    {
        private readonly Encoding utf8 = Encoding.UTF8;

        private static readonly JsonSerializer Serializer = new JsonSerializer()
        {
            ContractResolver = new CamelCaseExceptDictionaryKeysResolver()
        };

        public T Deserialize<T>(Stream stream)
        {
            using (var streamReader = new StreamReader(stream, utf8))
            using (var textReader = new JsonTextReader(streamReader))
            {
                return Serializer.Deserialize<T>(textReader);
            }
        }

        public void Serialize<T>(Stream stream, T instance)
        {
            using (var writer = new StreamWriter(stream, utf8, 1024 * 4, leaveOpen: true))
            using (var jsonWriter = new JsonTextWriter(writer))
            {
                Serializer.Serialize(jsonWriter, instance);
                
                jsonWriter.Flush();
                stream.Position = 0;
            }
        }

        class CamelCaseExceptDictionaryKeysResolver : CamelCasePropertyNamesContractResolver
        {
            protected override JsonDictionaryContract CreateDictionaryContract(Type objectType)
            {
                var contract = base.CreateDictionaryContract(objectType);

                contract.DictionaryKeyResolver = propertyName =>
                {
                    return propertyName;
                };

                return contract;
            }
        }
    }

    The server api needs camel cased json, but not for certain dictionary keys. The implementation can be naively validated by the JsonSerializerTester.Assert function. (Work in progress).

    Run unleash server with Docker locally​

    The Unleash team have made a separate project which runs unleash server inside docker. Please see unleash-docker for more details.

    Development​

    Visual Studio 2017 / Code

    Cakebuild

    Other information​

    This content was generated on

    - +This should return a ToggleCollection. The UnleashSettings.JsonSerializer can be used to deserialize a JSON string in the same format returned from /api/client/features.
  • Example bootstrap files can be found in the json files located in tests/Unleash.Tests/App_Data
  • Our assumption is this can be use for applications deployed to ephemeral containers or more locked down file systems where Unleash's need to write the backup file is not desirable or possible.
  • Loading with bootstrapping defaults to override feature toggles loaded from Local Backup, this override can be switched off by setting the UnleashSettings.ToggleOverride property to false

    • Configuring with the UnleashSettings:

    var settings = new UnleashSettings()
    {
        AppName = "dotnet-test",
        UnleashApi = new Uri("http://unleash.herokuapp.com/api/"),
        CustomHttpHeaders = new Dictionary()
        {
          {"Authorization","API token" }
        },
        ToggleOverride = false, // Defaults to true
        ToggleBootstrapProvider = new MyToggleBootstrapProvider() // A toggle bootstrap provider implementing IToggleBootstrapProvider here
    };

    Provided Bootstrappers​

    ToggleBootstrapFileProvider​

    settings.UseBootstrapFileProvider("./path/to/file.json");

    ToggleBootstrapUrlProvider​

    var shouldThrowOnError = true; // Throws for 500, 404, etc
    var customHeaders = new Dictionary<string, string>()
    {
        { "Authorization", "Bearer ABCdefg123" } // Or whichever set of headers would be required to GET this file
    }; // Defaults to null
    settings.UseBootstrapUrlProvider("://domain.top/path/to/file.json", shouldThrowOnError, customHeaders);

    Json Serialization​

    The unleash client is dependant on a json serialization library. If your application already have Newtonsoft.Json >= 9.0.1 installed, everything should work out of the box. If not, you will get an error message during startup telling you to implement an 'IJsonSerializer' interface, which needs to be added to the configuration.

    With Newtonsoft.Json version 7.0.0.0, the following implementation can be used. For older versions, consider to upgrade.

    var settings = new UnleashSettings()
    {
        AppName = "dotnet-test",
        UnleashApi = new Uri("http://unleash.herokuapp.com/api/"),
        JsonSerializer = new NewtonsoftJson7Serializer()
    };

    public class NewtonsoftJson7Serializer : IJsonSerializer
    {
        private readonly Encoding utf8 = Encoding.UTF8;

        private static readonly JsonSerializer Serializer = new JsonSerializer()
        {
            ContractResolver = new CamelCaseExceptDictionaryKeysResolver()
        };

        public T Deserialize<T>(Stream stream)
        {
            using (var streamReader = new StreamReader(stream, utf8))
            using (var textReader = new JsonTextReader(streamReader))
            {
                return Serializer.Deserialize<T>(textReader);
            }
        }

        public void Serialize<T>(Stream stream, T instance)
        {
            using (var writer = new StreamWriter(stream, utf8, 1024 * 4, leaveOpen: true))
            using (var jsonWriter = new JsonTextWriter(writer))
            {
                Serializer.Serialize(jsonWriter, instance);
                
                jsonWriter.Flush();
                stream.Position = 0;
            }
        }

        class CamelCaseExceptDictionaryKeysResolver : CamelCasePropertyNamesContractResolver
        {
            protected override JsonDictionaryContract CreateDictionaryContract(Type objectType)
            {
                var contract = base.CreateDictionaryContract(objectType);

                contract.DictionaryKeyResolver = propertyName =>
                {
                    return propertyName;
                };

                return contract;
            }
        }
    }

    The server api needs camel cased json, but not for certain dictionary keys. The implementation can be naively validated by the JsonSerializerTester.Assert function. (Work in progress).

    Run unleash server with Docker locally​

    The Unleash team have made a separate project which runs unleash server inside docker. Please see unleash-docker for more details.

    Development​

    Visual Studio 2017 / Code

    Cakebuild

    Other information​

    This content was generated on

    + \ No newline at end of file diff --git a/reference/sdks/flutter.html b/reference/sdks/flutter.html index 0f21460892..f7aaa8c5c7 100644 --- a/reference/sdks/flutter.html +++ b/reference/sdks/flutter.html @@ -20,7 +20,7 @@ - + @@ -32,8 +32,8 @@ This makes it super simple to use Unleash from any Flutter app.

    How to use the client as a module​

    Step 1: Installation​

    flutter pub add unleash_proxy_client_flutter

    Step 2: Initialize the SDK​

    💡 TIP: As a client-side SDK, this SDK requires you to connect to either an Unleash proxy or to the Unleash front-end API. Refer to the connection options section for more information.

    Configure the client according to your needs. The following example provides only the required options. Refer to the section on available options for the full list.

    import 'package:unleash_proxy_client_flutter/unleash_proxy_client_flutter.dart';

    final unleash = UnleashClient(
        url: Uri.parse('https://<your-unleash-instance>/api/frontend'),
        clientKey: '<your-client-side-token>',
        appName: 'my-app');

    Connection options​

    To connect this SDK to your Unleash instance's front-end API, use the URL to your Unleash instance's front-end API (<unleash-url>/api/frontend) as the url parameter. For the clientKey parameter, use a FRONTEND token generated from your Unleash instance. Refer to the how to create API tokens guide for the necessary steps.

    To connect this SDK to the Unleash proxy, use the proxy's URL and a proxy client key. The configuration section of the Unleash proxy docs contains more info on how to configure client keys for your proxy.

    Step 3: Let the client synchronize​

    You should wait for the client's ready or initialized events before you start working with it. Before it's ready, the client might not report the correct state for your features.

    unleash.on('ready', (_) {
        if (unleash.isEnabled('proxy.demo')) {
          print('proxy.demo is enabled');
        } else {
          print('proxy.demo is disabled');
        }
    });

    The difference between the events is explained below.

    Step 4: Check feature toggle states​

    Once the client is ready, you can start checking features in your application. Use the isEnabled method to check the state of any feature you want:

    unleash.isEnabled('proxy.demo');

    You can use the getVariant method to get the variant of an enabled feature that has variants. If the feature is disabled or if it has no variants, then you will get back the disabled variant

    final variant = unleash.getVariant('proxy.demo');

    if (variant.name == 'blue') {
     // something with variant blue...
    }

    You can also access the payload associated with the variant:

    final variant = unleash.getVariant('proxy.demo');
    final payload = variant.payload;

    if (payload != null) {
      // do something with the payload
      // print(payload "${payload.type} ${payload.value}");
    }

    Updating the Unleash context​

    The Unleash context is used to evaluate features against attributes of a the current user. To update and configure the Unleash context in this SDK, use the updateContext and setContextField methods.

    The context you set in your app will be passed along to the Unleash proxy or the front-end API as query parameters for feature evaluation.

    The updateContext method will replace the entire (mutable part) of the Unleash context with the data that you pass in.

    The setContextField method only acts on the property that you choose. It does not affect any other properties of the Unleash context.

    // Used to set the context fields, shared with the Unleash Proxy. This 
    // method will replace the entire (mutable part) of the Unleash Context.
    unleash.updateContext(UnleashContext(userId: '1233'));

    // Used to update a single field on the Unleash Context.
    unleash.setContextField('userId', '4141');

    Available options​

    The Unleash SDK takes the following options:

    optionrequireddefaultdescription
    urlyesn/aThe Unleash Proxy URL to connect to. E.g.: https://examples.com/proxy
    clientKeyyesn/aThe Unleash Proxy Secret to be used
    appNameyesn/aThe name of the application using this SDK. Will be used as part of the metrics sent to Unleash Proxy. Will also be part of the Unleash Context.
    refreshIntervalno30How often, in seconds, the SDK should check for updated toggle configuration. If set to 0 will disable checking for updates
    disableRefreshnofalseIf set to true, the client will not check for updated toggle configuration
    metricsIntervalno30How often, in seconds, the SDK should send usage metrics back to Unleash Proxy
    disableMetricsnofalseSet this option to true if you want to disable usage metrics
    storageProvidernoSharedPreferencesStorageProviderAllows you to inject a custom storeProvider
    bootstrapno[]Allows you to bootstrap the cached feature toggle configuration.
    bootstrapOverridenotrueShould the bootstrap automatically override cached data in the local-storage. Will only be used if bootstrap is not an empty array.
    headerNamenoAuthorizationProvides possiblity to specify custom header that is passed to Unleash / Unleash Proxy with the clientKey
    customHeadersno{}Additional headers to use when making HTTP requests to the Unleash proxy. In case of name collisions with the default headers, the customHeaders value will be used.
    impressionDataAllnofalseAllows you to trigger "impression" events for all getToggle and getVariant invocations. This is particularly useful for "disabled" feature toggles that are not visible to frontend SDKs.
    fetchernohttp.getAllows you to define your own fetcher. Can be used to add certificate pinning or additional http behavior.
    posternohttp.postAllows you to define your own poster. Can be used to add certificate pinning or additional http behavior.

    Listen for updates via the events_emitter​

    The client is also an event emitter. This means that your code can subscribe to updates from the client. This is a neat way to update your app when toggle state updates.

    unleash.on('update', (_) {
        final myToggle = unleash.isEnabled('proxy.demo');
        //do something useful
    });

    Available events:​

    PS! Please remember that you should always register your event listeners before your call unleash.start(). If you register them after you have started the SDK you risk loosing important events.

    SessionId - Important note!​

    You may provide a custom session id via the "context". If you do not provide a sessionId this SDK will create a random session id, which will also be stored in the provided storage. By always having a consistent sessionId available ensures that even "anonymous" users will get a consistent experience when feature toggles is evaluated, in combination with a gradual (percentage based) rollout.

    Stop the SDK​

    You can stop the Unleash client by calling the stop method. Once the client has been stopped, it will no longer check for updates or send metrics to the server.

    A stopped client can be restarted.

    unleash.stop();

    Bootstrap​

    Now it is possible to bootstrap the SDK with your own feature toggle configuration when you don't want to make an API call.

    This is also useful if you require the toggles to be in a certain state immediately after initializing the SDK.

    How to use it ?​

    Add a bootstrap attribute when create a new UnleashClient.
    -There's also a bootstrapOverride attribute which is by default is true.

    final unleash = UnleashClient(
        url: Uri.parse('https://app.unleash-hosted.com/demo/api/proxy'),
        clientKey: 'proxy-123',
        appName: 'my-app',
        bootstrapOverride: false,
        bootstrap: {
        'demoApp.step4': ToggleConfig(
            enabled: true,
            impressionData: false,
            variant: Variant(enabled: true, name: 'blue'))
    });

    NOTES: ⚠️

    Useful commands development​

    This content was generated on

    - +There's also a bootstrapOverride attribute which is by default is true.

    final unleash = UnleashClient(
        url: Uri.parse('https://app.unleash-hosted.com/demo/api/proxy'),
        clientKey: 'proxy-123',
        appName: 'my-app',
        bootstrapOverride: false,
        bootstrap: {
        'demoApp.step4': ToggleConfig(
            enabled: true,
            impressionData: false,
            variant: Variant(enabled: true, name: 'blue'))
    });

    NOTES: ⚠️

    Useful commands development​

    This content was generated on

    + \ No newline at end of file diff --git a/reference/sdks/go.html b/reference/sdks/go.html index 859193a64a..0635e91ee4 100644 --- a/reference/sdks/go.html +++ b/reference/sdks/go.html @@ -20,7 +20,7 @@ - + @@ -38,8 +38,8 @@ you can add the following to your apps go.mod:

        replace github.com/Unleash/unleash-client-go/v3 => ../unleash-client-go/

    Steps to release​

    Adding client specifications​

    In order to make sure the unleash clients uphold their contract, we have defined a set of client specifications that define this contract. These are used to make sure that each unleash client at any time adhere to the contract, and define a set of functionality that is core to unleash. You can view -the client specifications here.

    In order to make the tests run please do the following steps.

    // in repository root
    // testdata is gitignored
    mkdir testdata
    cd testdata
    git clone https://github.com/Unleash/client-specification.git

    Requirements:

    Run tests:

    make

    Run lint check:

    make lint

    Run code-style checks:(currently failing)

    make strict-check

    Run race-tests:

    make test-race

    Benchmarking​

    You can benchmark feature toggle evaluation by running:

    go test -run=^$ -bench=BenchmarkFeatureToggleEvaluation -benchtime=10s

    Here's an example of how the output could look like:

    goos: darwin
    goarch: arm64
    pkg: github.com/Unleash/unleash-client-go/v3
    BenchmarkFeatureToggleEvaluation-8 Final Estimated Operations Per Day: 101.131 billion (1.011315e+11)
    13635154 854.3 ns/op
    PASS
    ok github.com/Unleash/unleash-client-go/v3 13.388s

    In this example the benchmark was run on a MacBook Pro (M1 Pro, 2021) with 16GB RAM.

    We can see a result of 854.3 ns/op, which means around 101.131 billion feature toggle evaluations per day.

    Note: The benchmark is run with a single CPU core, no parallelism.

    Design philsophy​

    This feature flag SDK is designed according to our design philosophy. You can read more about that here.

    This content was generated on

    - +the client specifications here.

    In order to make the tests run please do the following steps.

    // in repository root
    // testdata is gitignored
    mkdir testdata
    cd testdata
    git clone https://github.com/Unleash/client-specification.git

    Requirements:

    Run tests:

    make

    Run lint check:

    make lint

    Run code-style checks:(currently failing)

    make strict-check

    Run race-tests:

    make test-race

    Benchmarking​

    You can benchmark feature toggle evaluation by running:

    go test -run=^$ -bench=BenchmarkFeatureToggleEvaluation -benchtime=10s

    Here's an example of how the output could look like:

    goos: darwin
    goarch: arm64
    pkg: github.com/Unleash/unleash-client-go/v3
    BenchmarkFeatureToggleEvaluation-8 Final Estimated Operations Per Day: 101.131 billion (1.011315e+11)
    13635154 854.3 ns/op
    PASS
    ok github.com/Unleash/unleash-client-go/v3 13.388s

    In this example the benchmark was run on a MacBook Pro (M1 Pro, 2021) with 16GB RAM.

    We can see a result of 854.3 ns/op, which means around 101.131 billion feature toggle evaluations per day.

    Note: The benchmark is run with a single CPU core, no parallelism.

    Design philsophy​

    This feature flag SDK is designed according to our design philosophy. You can read more about that here.

    This content was generated on

    + \ No newline at end of file diff --git a/reference/sdks/ios-proxy.html b/reference/sdks/ios-proxy.html index 5c431ca796..2bbf502a39 100644 --- a/reference/sdks/ios-proxy.html +++ b/reference/sdks/ios-proxy.html @@ -20,7 +20,7 @@ - + @@ -28,8 +28,8 @@
    Skip to main content

    iOS

    Generated content

    This document was generated from the README in the iOS GitHub repository.

    tip

    To connect to Unleash from a client-side context, you'll need to use the Unleash front-end API (how do I create an API token?) or the Unleash proxy (how do I create client keys?).

    unleash-proxy-client-swift

    The unleash-proxy-client-swift makes it easy for native applications and other swift platforms to connect to the unleash proxy. The proxy will evaluate a feature toggle for a given context and return a list of feature flags relevant for the provided context.

    The unleash-proxy-client-swift will then cache these toggles in a map in memory and refresh the configuration at a configurable interval, making queries against the toggle configuration extremely fast.

    Requirements​

    • MacOS: 12.15
    • iOS: 12

    Installation​

    Follow the following steps in order to install the unleash-proxy-client-swift:

    1. In your Xcode project go to File -> Swift Packages -> Add Package Dependency
    2. Supply the link to this repository
    3. Set the appropriate package constraints (typically up to next major version)
    4. Let Xcode find and install the necessary packages

    Once you're done, you should see SwiftEventBus and UnleashProxyClientSwift listed as dependencies in the file explorer of your project.

    Usage​

    In order to get started you need to import and instantiate the unleash client:

    iOS >= 13​

    import SwiftUI
    import UnleashProxyClientSwift

    // Setup Unleash in the context where it makes most sense

    var unleash = UnleashProxyClientSwift.UnleashClient(unleashUrl: "https://<unleash-instance>/api/frontend", clientKey: "<client-side-api-token>", refreshInterval: 15, appName: "test", context: ["userId": "c3b155b0-5ebe-4a20-8386-e0cab160051e"])

    unleash.start()

    iOS >= 12​

    import SwiftUI
    import UnleashProxyClientSwift

    // Setup Unleash in the context where it makes most sense

    var unleash = UnleashProxyClientSwift.UnleashClientBase(unleashUrl: "https://<unleash-instance>/api/frontend", clientKey: "<client-side-api-token>", refreshInterval: 15, appName: "test", context: ["userId": "c3b155b0-5ebe-4a20-8386-e0cab160051e"])

    unleash.start()

    In the example above we import the UnleashProxyClientSwift and instantiate the client. You need to provide the following parameters:

    • unleashUrl: the full url to either the Unleash front-end API OR an Unleash proxy [String]
    • clientKey: either an client-side API token if you use the front-end API (how) or a proxy client key if you use the proxy [String]
    • refreshInterval: the polling interval in seconds [Int]. Set to 0to only poll once and disable a periodic polling
    • appName: the application name identifier [String]
    • context: the context parameters except from appName and environment which should be specified explicitly in the init [[String: String]]

    Running unleash.start() will make the first request against the proxy and retrieve the feature toggle configuration, and set up the polling interval in the background.

    NOTE: While waiting to boot up the configuration may not be available, which means that asking for a feature toggle may result in a false if the configuration has not loaded. In the event that you need to be certain that the configuration is loaded we emit an event you can subscribe to, once the configuration is loaded. See more in the Events section.

    Once the configuration is loaded you can ask against the cache for a given feature toggle:

    if unleash.isEnabled(name: "ios") {
        // do something
    } else {
       // do something else
    }

    You can also set up variants and use them in a similar fashion:

    var variant = unleash.getVariant(name: "ios")
    if variant.enabled {
        // do something
    } else {
       // do something else
    }

    Available options​

    The Unleash SDK takes the following options:

    optionrequireddefaultdescription
    unleashUrlyesn/aThe Unleash Proxy URL to connect to. E.g.: https://examples.com/proxy
    clientKeyyesn/aThe Unleash Proxy Secret to be used
    appNamenounleash-swift-clientThe name of the application using this SDK. Will be used as part of the metrics sent to Unleash Proxy. Will also be part of the Unleash Context.
    environmentnodefaultThe name of the environment using this SDK. Will be used as part of the metrics sent to Unleash Proxy. Will also be part of the Unleash Context.
    refreshIntervalno15How often, in seconds, the SDK should check for updated toggle configuration. If set to 0 will disable checking for updates
    metricsIntervalno30How often, in seconds, the SDK should send usage metrics back to Unleash Proxy
    disableMetricsnofalseSet this option to true if you want to disable usage metrics
    contextno[:]The initial context parameters except from appName and `environment which are specified as top level fields

    Update context​

    In order to update the context you can use the following method:

    var context: [String: String] = [:]
    context["userId"] = "c3b155b0-5ebe-4a20-8386-e0cab160051e"
    unleash.updateContext(context: context)

    This will stop and start the polling interval in order to renew polling with new context values.

    You can use any of the predefined fields. If you need to support -custom properties pass them as the second argument:

    var context: [String: String] = [:]
    context["userId"] = "c3b155b0-5ebe-4a20-8386-e0cab160051e"
    var properties: [String: String] = [:]
    properties["customKey"] = "customValue";
    unleash.updateContext(context: context, properties: properties)

    Events​

    The proxy client emits events that you can subscribe to. The following events are available:

    • "ready"
    • "update"
    • "sent" (metrics sent)
    • "error" (metrics sending error)

    Usage them in the following manner:

    func handleReady() {
        // do this when unleash is ready
    }

    unleash.subscribe(name: "ready", callback: handleReady)

    func handleUpdate() {
        // do this when unleash is updated
    }

    unleash.subscribe(name: "update", callback: handleUpdate)

    The ready event is fired once the client has received it's first set of feature toggles and cached it in memory. Every subsequent event will be an update event that is triggered if there is a change in the feature toggle configuration.

    Releasing​

    Note: To release the package you'll need to have CocoaPods installed.

    First, you'll need to add a tag. Releasing the tag is enough for the Swift package manager, but it's polite to also ensure CocoaPods users can also consume the code.

    git tag -a 0.0.4 -m "v0.0.4"

    Please make sure that that tag is pushed to remote.

    The next few commands assume that you have CocoaPods installed and available on your shell.

    First, validate your session with cocoapods with the following command:

    pod trunk register <email> "Your name"

    The email that owns this package is the general unleash team email. Cocoapods will send a link to this email, click it to validate your shell session.

    Bump the version number of the package, you can find this in UnleashProxyClientSwift.podspec, we use SemVer for this project. Once that's committed and merged to main:

    Linting the podspec is always a good idea:

    pod spec lint UnleashProxyClientSwift.podspec

    Once that succeeds, you can do the actual release:

    pod trunk push UnleashProxyClientSwift.podspec --allow-warnings

    Testing​

    In order to test this package you can run the swift test command. To test thread safety, run swift test with:

    swift test --sanitize=thread

    This will give you warnings in the console when you have any data races.

    This content was generated on

    - +custom properties pass them as the second argument:

    var context: [String: String] = [:]
    context["userId"] = "c3b155b0-5ebe-4a20-8386-e0cab160051e"
    var properties: [String: String] = [:]
    properties["customKey"] = "customValue";
    unleash.updateContext(context: context, properties: properties)

    Events​

    The proxy client emits events that you can subscribe to. The following events are available:

    Usage them in the following manner:

    func handleReady() {
        // do this when unleash is ready
    }

    unleash.subscribe(name: "ready", callback: handleReady)

    func handleUpdate() {
        // do this when unleash is updated
    }

    unleash.subscribe(name: "update", callback: handleUpdate)

    The ready event is fired once the client has received it's first set of feature toggles and cached it in memory. Every subsequent event will be an update event that is triggered if there is a change in the feature toggle configuration.

    Releasing​

    Note: To release the package you'll need to have CocoaPods installed.

    First, you'll need to add a tag. Releasing the tag is enough for the Swift package manager, but it's polite to also ensure CocoaPods users can also consume the code.

    git tag -a 0.0.4 -m "v0.0.4"

    Please make sure that that tag is pushed to remote.

    The next few commands assume that you have CocoaPods installed and available on your shell.

    First, validate your session with cocoapods with the following command:

    pod trunk register <email> "Your name"

    The email that owns this package is the general unleash team email. Cocoapods will send a link to this email, click it to validate your shell session.

    Bump the version number of the package, you can find this in UnleashProxyClientSwift.podspec, we use SemVer for this project. Once that's committed and merged to main:

    Linting the podspec is always a good idea:

    pod spec lint UnleashProxyClientSwift.podspec

    Once that succeeds, you can do the actual release:

    pod trunk push UnleashProxyClientSwift.podspec --allow-warnings

    Testing​

    In order to test this package you can run the swift test command. To test thread safety, run swift test with:

    swift test --sanitize=thread

    This will give you warnings in the console when you have any data races.

    This content was generated on

    + \ No newline at end of file diff --git a/reference/sdks/java.html b/reference/sdks/java.html index bc0d2b1230..d14344aba5 100644 --- a/reference/sdks/java.html +++ b/reference/sdks/java.html @@ -20,7 +20,7 @@ - + @@ -54,8 +54,8 @@ Unleash do come with a FakeUnleash implementation for doing this.

    Some examples on how to use it below:

    // example 1: everything on
    FakeUnleash fakeUnleash = new FakeUnleash();
    fakeUnleash.enableAll();

    assertThat(fakeUnleash.isEnabled("unknown"), is(true));
    assertThat(fakeUnleash.isEnabled("unknown2"), is(true));

    // example 2
    FakeUnleash fakeUnleash = new FakeUnleash();
    fakeUnleash.enable("t1", "t2");

    assertThat(fakeUnleash.isEnabled("t1"), is(true));
    assertThat(fakeUnleash.isEnabled("t2"), is(true));
    assertThat(fakeUnleash.isEnabled("unknown"), is(false));

    // example 3: variants
    FakeUnleash fakeUnleash = new FakeUnleash();
    fakeUnleash.enable("t1", "t2");
    fakeUnleash.setVariant("t1", new Variant("a", (String) null, true));

    assertThat(fakeUnleash.getVariant("t1").getName(), is("a"));

    Se more in FakeUnleashTest.java

    Development​

    Build:

    mvn clean install

    Jacoco coverage reports:

    mvn jacoco:report

    The generated report will be available at target/site/jacoco/index.html

    Formatting​

    Releasing​

    Deployment​

    GPG signing​

    Example settings.xml​

    <settings>
        ...
        <profiles>
            ...
            <profile>
                <id>ossrh</id>
                <activation>
                    <activeByDefault>true</activeByDefault>
                </activation>
                <properties>
                    <gpg.executable>gpg</gpg.executable> <!-- Where to find gpg -->
                    <gpg.passphrase>[PASSPHRASE FOR YOUR GPG KEY]</gpg.passphrase>
                </properties>
            </profile>
        </profiles>
        ...
        <servers>
            ...
            <server>
                <id>sonatype-nexus-snapshots</id>
                <username>[YOUR_SONATYPE_JIRA_USERNAME]</username>
                <password>[YOUR_SONATYPE_JIRA_PASSWORD]</password>
            </server>
            <server>
                <id>ossrh</id>
                <username>[YOUR_SONATYPE_JIRA_USERNAME]</username>
                <password>[YOUR_SONATYPE_JIRA_PASSWORD]</password>
            </server>
            <server>
                <id>sonatype-nexus-staging</id>
                <username>[YOUR_SONATYPE_JIRA_USERNAME]</username>
                <password>[YOUR_SONATYPE_JIRA_PASSWORD]</password>
            </server>
        </servers>
    </settings>

    More information​

    Configuration options​

    The UnleashConfig$Builder class (created via UnleashConfig.builder()) exposes a set of builder methods to configure your Unleash client. The available options are listed below with a description of what they do. For the full signatures, take a look at the UnleashConfig class definition.

    Method nameDescriptionRequiredDefault value
    apiKeyThe api key to use for authenticating against the Unleash API.Yesnull
    appNameThe name of the application as shown in the Unleash UI. Registered applications are listed on the Applications page.Yesnull
    backupFileThe path to the file where local backups get stored.NoSynthesized from your system's java.io.tmpdir and your appName: "<java.io.tmpdir>/unleash-<appName>-repo.json"
    customHttpHeaderAdd a custom HTTP header to the list of HTTP headers that will the client sends to the Unleash API. Each method call will add a new header. Note: in most cases, you'll need to use this method to provide an API token.NoN/A
    customHttpHeadersProviderAdd a custom HTTP header provider. Useful for dynamic custom HTTP headers.Nonull
    disablePollingA boolean indicating whether the client should poll the unleash api for updates to toggles.
    disableMetricsA boolean indicating whether the client should disable sending usage metrics to the Unleash server.Nofalse
    enableProxyAuthenticationByJvmPropertiesEnable support for using JVM properties for HTTP proxy authentication.Nofalse
    environmentThe value to set for the Unleash context's environment property. Not the same as Unleash's environments.Nonull
    fallbackStrategyA strategy implementation that the client can use if it doesn't recognize the strategy type returned from the server.Nonull
    fetchTogglesIntervalHow often (in seconds) the client should check for toggle updates. Set to 0 if you want to only check once.No10
    instanceIdA unique(-ish) identifier for your instance. Typically a hostname, pod id or something similar. Unleash uses this to separate metrics from the client SDKs with the same appName.Yesnull
    namePrefixIf provided, the client will only fetch toggles whose name starts with the provided value.Nonull
    projectNameIf provided, the client will only fetch toggles from the specified project. (This can also be achieved with an API token).Nonull
    proxyA Proxy object. Use this to configure a third-party proxy that sits between your client and the Unleash server.Nonull
    scheduledExecutorA custom executor to control timing and running of tasks (such as fetching toggles, sending metrics).NoUnleashScheduledExecutorImpl
    sendMetricsIntervalHow often (in seconds) the client should send metrics to the Unleash server. Ignored if you disable metrics with the disableMetrics method.No60
    subscriberRegister a subscriber to Unleash client events.Nonull
    synchronousFetchOnInitialisationWhether the client should fetch toggle configuration synchronously (in a blocking manner) on initialisation.Nofalse
    toggleBootstrapProviderAdd a bootstrap provider (must implement the ToggleBootstrapProvider interface)No
    unleashAPIThe URL of the Unleash API.Yesnull
    unleashContextProviderAn Unleash context provider used to configure Unleash.Nonull
    unleashFeatureFetcherFactoryA factory providing a FeatureFetcher implementation.NoHttpFeatureFetcher::new
    unleashMetricsSenderFactoryA factory providing a MetricSender implementation.NoDefaultHttpMetricsSender::new

    When you have set all the desired options, initialize the configuration with the build method. You can then pass the configuration to the Unleash client constructor. -As an example:


    UnleashConfig config = UnleashConfig.builder()
                .appName("your app name")
                .instanceId("instance id")
                .unleashAPI("http://unleash.herokuapp.com/api/")
                .apiKey("API token")
                // ... more configuration options
                .build();

    Unleash unleash = new DefaultUnleash(config);

    Other information​

    This content was generated on

    - +As an example:


    UnleashConfig config = UnleashConfig.builder()
                .appName("your app name")
                .instanceId("instance id")
                .unleashAPI("http://unleash.herokuapp.com/api/")
                .apiKey("API token")
                // ... more configuration options
                .build();

    Unleash unleash = new DefaultUnleash(config);

    Other information​

    This content was generated on

    + \ No newline at end of file diff --git a/reference/sdks/javascript-browser.html b/reference/sdks/javascript-browser.html index 4eb0d9985c..3ad41cb0d8 100644 --- a/reference/sdks/javascript-browser.html +++ b/reference/sdks/javascript-browser.html @@ -20,7 +20,7 @@ - + @@ -33,8 +33,8 @@ This is a neat way to update a single page app when toggle state updates. 

    unleash.on('update', () => {
        const myToggle = unleash.isEnabled('proxy.demo');
        //do something useful
    });

    Available events:​

    PS! Please remember that you should always register your event listeners before your call unleash.start(). If you register them after you have started the SDK you risk loosing important events.

    SessionId - Important note!​

    You may provide a custom session id via the "context". If you do not provide a sessionId this SDK will create a random session id, which will also be stored in the provided storage (local storage). By always having a consistent sessionId available ensures that even "anonymous" users will get a consistent experience when feature toggles is evaluated, in combination with a gradual (percentage based) rollout.

    Stop the SDK​

    You can stop the Unleash client by calling the stop method. Once the client has been stopped, it will no longer check for updates or send metrics to the server.

    A stopped client can be restarted.

    unleash.stop()

    Custom store​

    This SDK can work with React Native storage @react-native-async-storage/async-storage or react-native-shared-preferences and many more to backup feature toggles locally. This is useful for bootstrapping the SDK the next time the user comes back to your application.

    You can provide your own storage implementation.

    Examples: 

    import SharedPreferences from 'react-native-shared-preferences';
    import { UnleashClient } from 'unleash-proxy-client';

    const unleash = new UnleashClient({
        url: 'https://eu.unleash-hosted.com/hosted/proxy',
        clientKey: 'your-proxy-key',
        appName: 'my-webapp',
        storageProvider: {
          save: (name: string, data: any) => SharedPreferences.setItem(name, data),
          get: (name: string) => SharedPreferences.getItem(name, (val) => val)
        },
    });
    import AsyncStorage from '@react-native-async-storage/async-storage';
    import { UnleashClient } from 'unleash-proxy-client';

    const PREFIX = 'unleash:repository';

    const unleash = new UnleashClient({
        url: 'https://eu.unleash-hosted.com/hosted/proxy',
        clientKey: 'your-proxy-key',
        appName: 'my-webapp',
        storageProvider: {
           save: (name: string, data: any) => {
            const repo = JSON.stringify(data);
            const key = `${PREFIX}:${name}`;
            return AsyncStorage.setItem(key, repo);
          },
          get: (name: string) => {
            const key = `${PREFIX}:${name}`;
            const data = await AsyncStorage.getItem(key);
            return data ? JSON.parse(data) : undefined;
          }
        },
    });

    How to use in node.js​

    This SDK can also be used in node.js applications (from v1.4.0). Please note that you will need to provide a valid "fetch" implementation. Only ECMAScript modules is exported from this package.

    import fetch from 'node-fetch';
    import { UnleashClient, InMemoryStorageProvider } from 'unleash-proxy-client';

    const unleash = new UnleashClient({
      url: 'https://app.unleash-hosted.com/demo/proxy',
      clientKey: 'proxy-123',
      appName: 'nodejs-proxy',
      storageProvider: new InMemoryStorageProvider(),
      fetch,
    });

    await unleash.start();
    const isEnabled = unleash.isEnabled('proxy.demo');
    console.log(isEnabled);

    index.mjs

    How to use the client via CDN.​

    <html>
    <head>
        <script src="https://unpkg.com/unleash-proxy-client@latest/build/main.min.js" type="text/javascript"></script>
        <script type="text/javascript">
            var config = {url: 'https://app.unleash-hosted.com/demo/proxy', clientKey: 'proxy-123', appName: 'web'};
            var client = new unleash.UnleashClient(config);
            client.updateContext({userId: '1233'})

            client.on('update', () => {
                console.log(client.isEnabled('proxy.demo'));
            });
            client.start();
        </script>
    </head>
    </html>

    Bootstrap​

    Now it is possible to bootstrap the SDK with your own feature toggle configuration when you don't want to make an API call.

    This is also useful if you require the toggles to be in a certain state immediately after initializing the SDK.

    How to use it ?​

    Add a bootstrap attribute when create a new UnleashClient.
    There's also a bootstrapOverride attribute which is by default is true.

    import { UnleashClient } from 'unleash-proxy-client';

    const unleash = new UnleashClient({
      url: 'https://app.unleash-hosted.com/demo/proxy',
      clientKey: 'proxy-123',
      appName: 'nodejs-proxy',
      bootstrap: [{
        "enabled": true,
        "name": "demoApp.step4",
        "variant": {
            "enabled": true,
            "name": "blue",
            "feature_enabled": true,
        }
      }],
      bootstrapOverride: false
    });

    NOTES: ⚠️ If bootstrapOverride is true (by default), any local cached data will be overridden with the bootstrap specified.
    -If bootstrapOverride is false any local cached data will not be overridden unless the local cache is empty.

    This content was generated on

    - +If bootstrapOverride is false any local cached data will not be overridden unless the local cache is empty.

    This content was generated on

    + \ No newline at end of file diff --git a/reference/sdks/next-js.html b/reference/sdks/next-js.html index 5b2e4cdf3e..3e61a7e0d0 100644 --- a/reference/sdks/next-js.html +++ b/reference/sdks/next-js.html @@ -20,7 +20,7 @@ - + @@ -37,8 +37,8 @@ You can find out more about direct Front-end API access in our documentation, including a guide on how to setup a client-side SDK key.

    Important: Hooks and provider are only available in @unleash/nextjs/client.

    import type { AppProps } from "next/app";
    import { FlagProvider } from "@unleash/nextjs/client";

    export default function App({ Component, pageProps }: AppProps) {
      return (
        <FlagProvider>
          <Component {...pageProps} />
        </FlagProvider>
      );
    }

    With <FlagProvider /> in place you can now use hooks like: useFlag, useVariant, or useFlagsStatus to block rendering until flags are ready.

    import { useFlag } from "@unleash/nextjs/client";

    const YourComponent = () => {
      const isEnabled = useFlag("nextjs-example");

      return <>{isEnabled ? "ENABLED" : "DISABLED"}</>;
    };

    Optionally, you can configure FlagProvider with the config prop. It will take priority over environment variables.

    <FlagProvider
      config={{
        url: "http://localhost:4242/api/frontend", // replaces NEXT_PUBLIC_UNLEASH_FRONTEND_API_URL
        clientKey: "<Frontend_API_token>", // replaces NEXT_PUBLIC_UNLEASH_FRONTEND_API_TOKEN
        appName: "nextjs", // replaces NEXT_PUBLIC_UNLEASH_APP_NAME

        refreshInterval: 15, // additional client configuration
        // see https://github.com/Unleash/unleash-proxy-client-js#available-options
      }}
    >

    If you only plan to use Unleash client-side React SDK now also works with Next.js. Check documentation there for more examples.

    D). Static Site Generation, optimized performance (SSG)​

    With same access as in the client-side example above you can resolve Unleash feature flags when building static pages.

    import {
      flagsClient,
      getDefinitions,
      evaluateFlags,
      getFrontendFlags,
      type IVariant,
    } from "@unleash/nextjs";
    import type { GetStaticProps, NextPage } from "next";

    type Data = {
      isEnabled: boolean;
      variant: IVariant;
    };

    const ExamplePage: NextPage<Data> = ({ isEnabled, variant }) => (
      <>
        Flag status: {isEnabled ? "ENABLED" : "DISABLED"}
        <br />
        Variant: {variant.name}
      </>
    );

    export const getStaticProps: GetStaticProps<Data> = async (_ctx) => {
      /* Using server-side SDK: */
      const definitions = await getDefinitions();
      const context = {}; // optional, see https://docs.getunleash.io/reference/unleash-context
      const { toggles } = evaluateFlags(definitions, context);

      /* Or with the proxy/front-end API */
      // const { toggles } = await getFrontendFlags({ context });

      const flags = flagsClient(toggles);

      return {
        props: {
          isEnabled: flags.isEnabled("nextjs-example"),
          variant: flags.getVariant("nextjs-example"),
        },
      };
    };

    export default ExamplePage;

    The same approach will work for ISR (Incremental Static Regeneration).

    Both getDefinitions() and getFrontendFlags() can take arguments overriding URL, token and other request parameters.

    E). Server Side Rendering (SSR)​

    import {
      flagsClient,
      evaluateFlags,
      getDefinitions,
      type IVariant,
    } from "@unleash/nextjs";
    import type { GetServerSideProps, NextPage } from "next";

    type Data = {
      isEnabled: boolean;
    };

    const ExamplePage: NextPage<Data> = ({ isEnabled }) => (
      <>Flag status: {isEnabled ? "ENABLED" : "DISABLED"}</>
    );

    export const getServerSideProps: GetServerSideProps<Data> = async (ctx) => {
      const sessionId =
        ctx.req.cookies["unleash-session-id"] ||
        `${Math.floor(Math.random() * 1_000_000_000)}`;
      ctx.res.setHeader("set-cookie", `unleash-session-id=${sessionId}; path=/;`);

      const context = {
        sessionId, // needed for stickiness
        // userId: "123" // etc
      };

      const { toggles } = await getFrontendFlags({ context }); // Use Proxy/Frontend API
      const flags = flagsClient(toggles);

      return {
        props: {
          isEnabled: flags.isEnabled("nextjs-example"),
        },
      };
    };

    export default ExamplePage;

    F). Bootstrapping / rehydration​

    You can bootstrap Unleash React SDK to have values loaded from the start. Initial value can be customized server-side.

    import App, { AppContext, type AppProps } from "next/app";
    import {
      FlagProvider,
      getFrontendFlags,
      type IMutableContext,
      type IToggle,
    } from "@unleash/nextjs";

    type Data = {
      toggles: IToggle[];
      context: IMutableContext;
    };

    export default function CustomApp({
      Component,
      pageProps,
      toggles,
      context,
    }: AppProps & Data) {
      return (
        <FlagProvider
          config={{
            bootstrap: toggles,
            context,
          }}
        >
          <Component {...pageProps} />
        </FlagProvider>
      );
    }

    CustomApp.getInitialProps = async (ctx: AppContext) => {
      const context = {
        userId: "123",
      };

      const { toggles } = await getFrontendFlags(); // use Unleash Proxy

      return {
        ...(await App.getInitialProps(ctx)),
        bootstrap: toggles,
        context, // pass context along so client can refetch correct values
      };
    };

    ⚗️ CLI (experimental)

    You can use unleash [action] [options] in your package.json scripts section, or with:

    npx @unleash/nextjs

    For the CLI to work, the following environment variables must be configured with appropriate values:

    The CLI will attempt to read environment values from any .env files if they're present. You can also set the variables directly when invoking the interface, as in the CLI usage example.

    Usage​

    Example​

    Try it now

    UNLEASH_SERVER_API_URL=https://app.unleash-hosted.com/demo/api \
    UNLEASH_SERVER_API_TOKEN=test-server:default.8a090f30679be7254af997864d66b86e44dcfc5291916adff72a0fb5 \
    npx @unleash/nextjs generate-types ./unleash.ts

    Known limitation

    This content was generated on

    - +It will also generate strictly typed versions of useFlag, useVariant, useFlags and flagsClient (unless --typesOnly is used).
  • -V Output the version number

    • Example​

    Try it now

    UNLEASH_SERVER_API_URL=https://app.unleash-hosted.com/demo/api \
    UNLEASH_SERVER_API_TOKEN=test-server:default.8a090f30679be7254af997864d66b86e44dcfc5291916adff72a0fb5 \
    npx @unleash/nextjs generate-types ./unleash.ts

    Known limitation

    This content was generated on

    + \ No newline at end of file diff --git a/reference/sdks/node.html b/reference/sdks/node.html index ee487ed03d..58fd54dd42 100644 --- a/reference/sdks/node.html +++ b/reference/sdks/node.html @@ -20,7 +20,7 @@ - + @@ -84,8 +84,8 @@ offline, from a browser environment or implement your own caching layer. See example.

    Unleash depends on a ready event of the repository you pass in. Be sure that you emit the event after you've initialized unleash.

    Design philosophy​

    This feature flag SDK is designed according to our design philosophy. You can -read more about that here.

    This content was generated on

    - +read more about that here.

    This content was generated on

    + \ No newline at end of file diff --git a/reference/sdks/php.html b/reference/sdks/php.html index c4ed117628..0acd9bada3 100644 --- a/reference/sdks/php.html +++ b/reference/sdks/php.html @@ -20,7 +20,7 @@ - + @@ -83,8 +83,8 @@ the code.

    <?php

    use Unleash\Client\UnleashBuilder;

    $unleash = UnleashBuilder::create()
        ->withAppName('Some App Name')
        ->withAppUrl('https://somewhere.com')
        ->withInstanceId('some-instance-id')
        ->withMetricsEnabled(false) // turn off metric sending
        ->withMetricsEnabled(true) // turn on metric sending
        ->withMetricsInterval(10_000) // interval in milliseconds (10 seconds)
        ->withMetricsCacheHandler(new Psr16Cache(new RedisAdapter())) // use custom cache handler for metrics, defaults to standard cache handler
        ->build();

    // the metric will be collected but not sent immediately
    $unleash->isEnabled('test');
    sleep(10);
    // now the metrics will get sent
    $unleash->isEnabled('test');

    Custom headers via middleware​

    While middlewares for http client are not natively supported by this SDK, you can pass your own http client which supports them.

    The most popular http client, guzzle, supports them out of the box and here's an example of how to pass custom headers automatically (for more information visit official guzzle documentation on middlewares):

    <?php

    use GuzzleHttp\Client;
    use GuzzleHttp\Handler\CurlHandler;
    use GuzzleHttp\HandlerStack;
    use GuzzleHttp\Middleware;
    use Psr\Http\Message\RequestInterface;
    use Unleash\Client\UnleashBuilder;

    // any callable is valid, it may be a function reference, anonymous function or an invokable class

    // example invokable class
    final class AddHeaderMiddleware
    {
        public function __construct(
            private readonly string $headerName,
            private readonly string $value,
        ) {
        }

        public function __invoke(RequestInterface $request): RequestInterface
        {
            return $request->withHeader($this->headerName, $this->value);
        }
    }

    // example anonymous function
    $addHeaderMiddleware = fn (string $headerName, string $headerValue)
        => fn(RequestInterface $request)
            => $request->withHeader($headerName, $headerValue);

    // create a handler stack that holds information about all middlewares
    $stack = HandlerStack::create(new CurlHandler());
    // mapRequest is a helper that simplifies modifying request
    $stack->push(Middleware::mapRequest(new AddHeaderMiddleware('X-My-Header', 'Some-Value')));
    // or with lambda
    $stack->push(Middleware::mapRequest($addHeaderMiddleware('X-My-Header2', 'Some-Value')));
    // assign the stack with middlewares as a handler
    $httpClient = new Client(['handler' => $stack]);

    $unleash = UnleashBuilder::create()
        ->withHttpClient($httpClient) // assign the custom http client
        ->withAppName('My-App')
        ->withInstanceId('My-Instance')
        ->withAppUrl('http://localhost:4242')
        ->build();

    // now every http request will have X-My-Header header with value Some-Value
    $unleash->isEnabled('some-feature');

    Constraints​

    Constraints are supported by this SDK and will be handled correctly by Unleash::isEnabled() if present.

    GitLab specifics​

    <?php

    use Unleash\Client\UnleashBuilder;

    $gitlabUnleash = UnleashBuilder::createForGitlab()
        ->withInstanceId('H9sU9yVHVAiWFiLsH2Mo') // generated in GitLab
        ->withAppUrl('https://git.example.com/api/v4/feature_flags/unleash/1')
        ->withGitlabEnvironment('Production')
        ->build();

    // the above is equivalent to
    $gitlabUnleash = UnleashBuilder::create()
        ->withInstanceId('H9sU9yVHVAiWFiLsH2Mo')
        ->withAppUrl('https://git.example.com/api/v4/feature_flags/unleash/1')
        ->withGitlabEnvironment('Production')
        ->withAutomaticRegistrationEnabled(false)
        ->withMetricsEnabled(false)
        ->build();

    Check out our guide for more information on how to build and scale feature flag systems

    This content was generated on

    - +communicates the intent better.
  • GitLab doesn't use registration system, you can set the SDK to disable automatic registration and save one http call.
  • GitLab doesn't read metrics, you can set the SDK to disable sending them and save some http calls.
    • <?php

    use Unleash\Client\UnleashBuilder;

    $gitlabUnleash = UnleashBuilder::createForGitlab()
        ->withInstanceId('H9sU9yVHVAiWFiLsH2Mo') // generated in GitLab
        ->withAppUrl('https://git.example.com/api/v4/feature_flags/unleash/1')
        ->withGitlabEnvironment('Production')
        ->build();

    // the above is equivalent to
    $gitlabUnleash = UnleashBuilder::create()
        ->withInstanceId('H9sU9yVHVAiWFiLsH2Mo')
        ->withAppUrl('https://git.example.com/api/v4/feature_flags/unleash/1')
        ->withGitlabEnvironment('Production')
        ->withAutomaticRegistrationEnabled(false)
        ->withMetricsEnabled(false)
        ->build();

    Check out our guide for more information on how to build and scale feature flag systems

    This content was generated on

    + \ No newline at end of file diff --git a/reference/sdks/python.html b/reference/sdks/python.html index 9d53521151..ef1a4b244c 100644 --- a/reference/sdks/python.html +++ b/reference/sdks/python.html @@ -20,7 +20,7 @@ - + @@ -28,8 +28,8 @@
    Skip to main content

    Python

    Generated content

    This document was generated from the README in the Python GitHub repository.

    tip

    To connect to Unleash, you'll need your Unleash API url (e.g. https://<your-unleash>/api) and a server-side API token (how do I create an API token?).

    unleash-client-python

    Coverage Status PyPI version PyPI - Python Version License: MIT

    This is the Python client for Unleash. It implements Client Specifications 1.0 and checks compliance based on spec in unleash/client-specifications

    What it supports:

    • Default activation strategies using 32-bit Murmurhash3
    • Custom strategies
    • Full client lifecycle:
      • Client registers with Unleash server
      • Client periodically fetches feature toggles and stores to on-disk cache
      • Client periodically sends metrics to Unleash Server
    • Tested on Linux (Ubuntu), OSX, and Windows

    Check out the project documentation and the changelog.

    Installation​

    Check out the package on Pypi!

    pip install UnleashClient

    For Flask Users​

    If you're looking into running Unleash from Flask, you might want to take a look at Flask-Unleash, the Unleash Flask extension. The extension builds upon this SDK to reduce the amount of boilerplate code you need to write to integrate with Flask. Of course, if you'd rather use this package directly, that will work too.

    Usage​

    Initialization​

    from UnleashClient import UnleashClient

    client = UnleashClient(
        url="https://unleash.herokuapp.com",
        app_name="my-python-app",
        custom_headers={'Authorization': '<API token>'})

    client.initialize_client()

    For more information about configuring UnleashClient, check out the project reference docs!

    Checking if a feature is enabled​

    A check of a simple toggle:

    client.is_enabled("my_toggle")

    To supply application context, use the second positional argument:

    app_context = {"userId": "test@email.com"}
    client.is_enabled("user_id_toggle", app_context)

    Fallback function and default values​

    You can specify a fallback function for cases where the client doesn't recognize the toggle by using the fallback_function keyword argument:

    def custom_fallback(feature_name: str, context: dict) -> bool:
        return True

    client.is_enabled("my_toggle", fallback_function=custom_fallback)

    You can also use the fallback_function argument to replace the obsolete default_value keyword argument by using a lambda that ignores its inputs. Whatever the lambda returns will be used as the default value.

    client.is_enabled("my_toggle", fallback_function=lambda feature_name, context: True)

    The fallback function must accept the feature name and context as positional arguments in that order.

    The client will evaluate the fallback function only if an exception occurs when calling the is_enabled() method. This happens when the client can't find the feature flag. The client may also throw other, general exceptions.

    For more information about usage, see the Usage documentation.

    Getting a variant​

    Checking for a variant:

    context = {'userId': '2'}  # Context must have userId, sessionId, or remoteAddr.  If none are present, distribution will be random.

    variant = client.get_variant("variant_toggle", context)

    print(variant)
    > {
    >    "name": "variant1",
    >    "payload": {
    >        "type": "string",
    >        "value": "val1"
    >        },
    >    "enabled": True
    > }

    For more information about variants, see the Variant documentation.

    Developing​

    For development, you'll need to setup the environment to run the tests. This repository is using -tox to run the test suite to test against multiple versions of Python. Running the tests is as simple as running this command in the makefile:

    tox -e py311

    This command will take care of downloading the client specifications and putting them in the correct place in the repository, and install all the dependencies you need.

    However, there are some caveats to this method. There is no easy way to run a single test, and running the entire test suite can be slow.

    Manual setup​

    First, make sure you have pip or pip3 installed.

    Then setup your viritual environment:

    Linux & Mac:

    python3 -m venv venv
    source venv/bin/activate

    Windows + cmd:

    python -m venv venv
    venv\Scripts\activate.bat

    Powershell:

    python -m venv venv
    venv\Scripts\activate.bat

    Once you've done your setup, run:

    pip install -r requirements.txt

    Run the get-spec script to download the client specifications tests:

    ./scripts/get-spec.sh

    Now you can run the tests by running pytest in the root directory.

    In order to run a single test, run the following command:

    pytest testfile.py::function_name

    # example: pytest tests/unit_tests/test_client.py::test_consistent_results

    Linting​

    In order to lint all the files you can run the following command:

    make fmt

    This content was generated on

    - +tox to run the test suite to test against multiple versions of Python. Running the tests is as simple as running this command in the makefile:

    tox -e py311

    This command will take care of downloading the client specifications and putting them in the correct place in the repository, and install all the dependencies you need.

    However, there are some caveats to this method. There is no easy way to run a single test, and running the entire test suite can be slow.

    Manual setup​

    First, make sure you have pip or pip3 installed.

    Then setup your viritual environment:

    Linux & Mac:

    python3 -m venv venv
    source venv/bin/activate

    Windows + cmd:

    python -m venv venv
    venv\Scripts\activate.bat

    Powershell:

    python -m venv venv
    venv\Scripts\activate.bat

    Once you've done your setup, run:

    pip install -r requirements.txt

    Run the get-spec script to download the client specifications tests:

    ./scripts/get-spec.sh

    Now you can run the tests by running pytest in the root directory.

    In order to run a single test, run the following command:

    pytest testfile.py::function_name

    # example: pytest tests/unit_tests/test_client.py::test_consistent_results

    Linting​

    In order to lint all the files you can run the following command:

    make fmt

    This content was generated on

    + \ No newline at end of file diff --git a/reference/sdks/react.html b/reference/sdks/react.html index d30acd6cb1..348a424780 100644 --- a/reference/sdks/react.html +++ b/reference/sdks/react.html @@ -20,7 +20,7 @@ - + @@ -30,8 +30,8 @@
    Skip to main content

    React

    Generated content

    This document was generated from the README in the React GitHub repository.

    tip

    To connect to Unleash from a client-side context, you'll need to use the Unleash front-end API (how do I create an API token?) or the Unleash proxy (how do I create client keys?).

    Installation

    npm install @unleash/proxy-client-react unleash-proxy-client
    # or
    yarn add @unleash/proxy-client-react unleash-proxy-client

    How to use

    Initialize the client​

    Prepare Unleash Proxy secret or Frontend API Access token.

    Import the provider like this in your entrypoint file (typically index.js/ts):

    import { createRoot } from 'react-dom/client';
    import { FlagProvider } from '@unleash/proxy-client-react';

    const config = {
      url: '<unleash-url>/api/frontend', // Your front-end API URL or the Unleash proxy's URL (https://<proxy-url>/proxy)
      clientKey: '<your-token>', // A client-side API token OR one of your proxy's designated client keys (previously known as proxy secrets)
      refreshInterval: 15, // How often (in seconds) the client should poll the proxy for updates
      appName: 'your-app-name', // The name of your application. It's only used for identifying your application
    };

    const root = createRoot(document.getElementById('root'));

    root.render(
      <React.StrictMode>
        <FlagProvider config={config}>
          <App />
        </FlagProvider>
      </React.StrictMode>
    );

    Connection options​

    To connect this SDK to your Unleash instance's front-end API, use the URL to your Unleash instance's front-end API (<unleash-url>/api/frontend) as the url parameter. For the clientKey parameter, use a FRONTEND token generated from your Unleash instance. Refer to the how to create API tokens guide for the necessary steps.

    To connect this SDK to the Unleash proxy, use the proxy's URL and a proxy client key. The configuration section of the Unleash proxy docs contains more info on how to configure client keys for your proxy.

    Check feature toggle status​

    To check if a feature is enabled:

    import { useFlag } from '@unleash/proxy-client-react';

    const TestComponent = () => {
      const enabled = useFlag('travel.landing');

      if (enabled) {
        return <SomeComponent />;
      }
      return <AnotherComponent />;
    };

    export default TestComponent;

    Check variants​

    To check variants:

    import { useVariant } from '@unleash/proxy-client-react';

    const TestComponent = () => {
      const variant = useVariant('travel.landing');

      if (variant.enabled && variant.name === 'SomeComponent') {
        return <SomeComponent />;
      } else if (variant.enabled && variant.name === 'AnotherComponent') {
        return <AnotherComponent />;
      }
      return <DefaultComponent />;
    };

    export default TestComponent;

    Defer rendering until flags fetched​

    useFlagsStatus retrieves the ready state and error events. Follow the following steps in order to delay rendering until the flags have been fetched.

    import { useFlagsStatus } from '@unleash/proxy-client-react';

    const MyApp = () => {
      const { flagsReady, flagsError } = useFlagsStatus();

      if (!flagsReady) {
        return <Loading />;
      }
      return <MyComponent error={flagsError} />;
    };

    Updating context​

    Initial context can be specified on a FlagProvider config.context property.

    <FlagProvider config={{ ...config, context: { userId: 123 }}>

    This code sample shows you how to update the unleash context dynamically:

    import { useUnleashContext, useFlag } from '@unleash/proxy-client-react';

    const MyComponent = ({ userId }) => {
      const variant = useFlag('my-toggle');
      const updateContext = useUnleashContext();

      useEffect(() => {
        // context is updated with userId
        updateContext({ userId });
      }, [userId]);

      // OR if you need to perform an action right after new context is applied
      useEffect(() => {
        async function run() {
          // Can wait for the new flags to pull in from the different context
          await updateContext({ userId });
          console.log('new flags loaded for', userId);
        }
        run();
      }, [userId]);
    };

    Advanced use cases

    Deferring client start​

    By default, the Unleash client will start polling the Proxy for toggles immediately when the FlagProvider component renders. You can prevent it by setting startClient prop to false. This is useful when you'd like to for example bootstrap the client and work offline.

    Deferring the client start gives you more fine-grained control over when to start fetching the feature toggle configuration. This could be handy in cases where you need to get some other context data from the server before fetching toggles, for instance.

    To start the client, use the client's start method. The below snippet of pseudocode will defer polling until the end of the asyncProcess function.

    const client = new UnleashClient({
      /* ... */
    });

    const MyAppComponent = () => {
      useEffect(() => {
        const asyncProcess = async () => {
          // do async work ...
          client.start();
        };
        asyncProcess();
      }, []);

      return (
        // Pass client as `unleashClient` and set `startClient` to `false`
        <FlagProvider unleashClient={client} startClient={false}>
          <App />
        </FlagProvider>
      );
    };

    Use unleash client directly​

    import { useUnleashContext, useUnleashClient } from '@unleash/proxy-client-react'

    const MyComponent = ({ userId }) => {
      const client = useUnleashClient();

      const login = () => {
        // login user
        if (client.isEnabled("new-onboarding")) {
          // Send user to new onboarding flow
        } else (
          // send user to old onboarding flow
        )
      }

      return <LoginForm login={login}/>
    }

    Usage with class components​

    Since this library uses hooks you have to implement a wrapper to use with class components. Beneath you can find an example of how to use this library with class components, using a custom wrapper:

    import React from 'react';
    import {
      useFlag,
      useUnleashClient,
      useUnleashContext,
      useVariant,
      useFlagsStatus,
    } from '@unleash/proxy-client-react';

    interface IUnleashClassFlagProvider {
      render: (props: any) => React.ReactNode;
      flagName: string;
    }

    export const UnleashClassFlagProvider = ({
      render,
      flagName,
    }: IUnleashClassFlagProvider) => {
      const enabled = useFlag(flagName);
      const variant = useVariant(flagName);
      const client = useUnleashClient();

      const updateContext = useUnleashContext();
      const { flagsReady, flagsError } = useFlagsStatus();

      const isEnabled = () => {
        return enabled;
      };

      const getVariant = () => {
        return variant;
      };

      const getClient = () => {
        return client;
      };

      const getUnleashContextSetter = () => {
        return updateContext;
      };

      const getFlagsStatus = () => {
        return { flagsReady, flagsError };
      };

      return (
        <>
          {render({
            isEnabled,
            getVariant,
            getClient,
            getUnleashContextSetter,
            getFlagsStatus,
          })}
        </>
      );
    };

    Wrap your components like so:

    <UnleashClassFlagProvider
      flagName="demoApp.step1"
      render={({ isEnabled, getClient }) => (
        <MyClassComponent isEnabled={isEnabled} getClient={getClient} />
      )}
    />

    React Native​

    IMPORTANT: This no longer comes included in the unleash-proxy-client-js library. You will need to install the storage adapter for your preferred storage solution.

    Because React Native doesn't run in a web browser, it doesn't have access to the localStorage API. Instead, you need to tell Unleash to use your specific storage provider. The most common storage provider for React Native is AsyncStorage. -To configure it, add the following property to your configuration object:

    const config = {
      storageProvider: {
        save: (name, data) => AsyncStorage.setItem(name, JSON.stringify(data)),
        get: async (name) => {
          const data = await AsyncStorage.getItem(name);
          return data ? JSON.parse(data) : undefined;
        },
      },
    };

    Migration guide

    Upgrade path from v1 -> v2​

    If you were previously using the built in Async storage used in the unleash-proxy-client-js, this no longer comes bundled with the library. You will need to install the storage adapter for your preferred storage solution. Otherwise there are no breaking changes.

    Upgrade path from v2 -> v3​

    Previously the unleash client was bundled as dependency directly in this library. It's now changed to a peer dependency and listed as an external.

    In v2 there was only one distribution based on the fact that webpack polyfilled the necessary features in v4. This is no longer the case in webpack v5. We now provide two distribution builds, one for the server and one for the client - and use the browser field in the npm package to hint module builders about which version to use. The default dist/index.js file points to the node version, while the web build is located at dist/index.browser.js

    Upgrading should be as easy as running yarn again with the new version, but we made the made bump regardless to be safe. Note: If you are not able to resolve the peer dependency on unleash-proxy-client you might need to run npm install unleash-proxy-client

    Upgrade path from v3 -> v4​

    startClient option has been simpilfied. Now it will also work if you don't pass custom client with it, and in SSR (when typeof window === 'undefined') it defaults to false.

    Note on v4.0.0:​

    The major release is driven by Node14 end of life and represents no other changes. From this version onwards we do not guarantee that this library will work server side with Node 14.

    Design philosophy​

    This feature flag SDK is designed according to our design philosophy. You can read more about that here.

    This content was generated on

    - +To configure it, add the following property to your configuration object:

    const config = {
      storageProvider: {
        save: (name, data) => AsyncStorage.setItem(name, JSON.stringify(data)),
        get: async (name) => {
          const data = await AsyncStorage.getItem(name);
          return data ? JSON.parse(data) : undefined;
        },
      },
    };

    Migration guide

    Upgrade path from v1 -> v2​

    If you were previously using the built in Async storage used in the unleash-proxy-client-js, this no longer comes bundled with the library. You will need to install the storage adapter for your preferred storage solution. Otherwise there are no breaking changes.

    Upgrade path from v2 -> v3​

    Previously the unleash client was bundled as dependency directly in this library. It's now changed to a peer dependency and listed as an external.

    In v2 there was only one distribution based on the fact that webpack polyfilled the necessary features in v4. This is no longer the case in webpack v5. We now provide two distribution builds, one for the server and one for the client - and use the browser field in the npm package to hint module builders about which version to use. The default dist/index.js file points to the node version, while the web build is located at dist/index.browser.js

    Upgrading should be as easy as running yarn again with the new version, but we made the made bump regardless to be safe. Note: If you are not able to resolve the peer dependency on unleash-proxy-client you might need to run npm install unleash-proxy-client

    Upgrade path from v3 -> v4​

    startClient option has been simpilfied. Now it will also work if you don't pass custom client with it, and in SSR (when typeof window === 'undefined') it defaults to false.

    Note on v4.0.0:​

    The major release is driven by Node14 end of life and represents no other changes. From this version onwards we do not guarantee that this library will work server side with Node 14.

    Design philosophy​

    This feature flag SDK is designed according to our design philosophy. You can read more about that here.

    This content was generated on

    + \ No newline at end of file diff --git a/reference/sdks/ruby.html b/reference/sdks/ruby.html index 0f9ce724b1..c950b81fd5 100644 --- a/reference/sdks/ruby.html +++ b/reference/sdks/ruby.html @@ -20,7 +20,7 @@ - + @@ -46,8 +46,8 @@ In order for strategy to work correctly it should support two methods name and is_enabled?

    class MyCustomStrategy
      def name
        'myCustomStrategy'
      end

      def is_enabled?(params = {}, context = nil)
        true
      end
    end

    Unleash.configure do |config|
      config.strategies.add(MyCustomStrategy.new)
    end

    Development​

    After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

    This SDK is also built against the Unleash Client Specification tests. -To run the Ruby SDK against this test suite, you'll need to have a copy on your machine, you can clone the repository directly using:

    git clone --depth 5 --branch v5.0.2 https://github.com/Unleash/client-specification.git client-specification

    After doing this, rake spec will also run the client specification tests.

    To install this gem onto your local machine, run bundle exec rake install.

    Releasing​

    Choose a new version number following Semantic Versioning semantics and then:

    Contributing​

    Bug reports and pull requests are welcome on GitHub at https://github.com/unleash/unleash-client-ruby.

    Be sure to run both bundle exec rspec and bundle exec rubocop in your branch before creating a pull request.

    Please include tests with any pull requests, to avoid regressions.

    Check out our guide for more information on how to build and scale feature flag systems

    This content was generated on

    - +To run the Ruby SDK against this test suite, you'll need to have a copy on your machine, you can clone the repository directly using:

    git clone --depth 5 --branch v5.0.2 https://github.com/Unleash/client-specification.git client-specification

    After doing this, rake spec will also run the client specification tests.

    To install this gem onto your local machine, run bundle exec rake install.

    Releasing​

    Choose a new version number following Semantic Versioning semantics and then:

    Contributing​

    Bug reports and pull requests are welcome on GitHub at https://github.com/unleash/unleash-client-ruby.

    Be sure to run both bundle exec rspec and bundle exec rubocop in your branch before creating a pull request.

    Please include tests with any pull requests, to avoid regressions.

    Check out our guide for more information on how to build and scale feature flag systems

    This content was generated on

    + \ No newline at end of file diff --git a/reference/sdks/rust.html b/reference/sdks/rust.html index 921ffc8678..84b3490d96 100644 --- a/reference/sdks/rust.html +++ b/reference/sdks/rust.html @@ -20,7 +20,7 @@ - + @@ -44,8 +44,8 @@ a new API token at http://localhost:4242/admin/api/create-token for user admin, type Client.

    Then run the test suite:

    UNLEASH_API_URL=http://127.0.0.1:4242/api \
      UNLEASH_APP_NAME=fred UNLEASH_INSTANCE_ID=test \
      UNLEASH_CLIENT_SECRET="<tokenvalue>" \
      cargo test --features functional  -- --nocapture

    or similar. The functional test suite looks for a manually setup set of features. E.g. log into the Unleash UI on port 4242 and create a feature called -default.

    This content was generated on

    - +default.

    This content was generated on

    + \ No newline at end of file diff --git a/reference/sdks/svelte.html b/reference/sdks/svelte.html index d0a5c535b3..341e795634 100644 --- a/reference/sdks/svelte.html +++ b/reference/sdks/svelte.html @@ -20,7 +20,7 @@ - + @@ -28,8 +28,8 @@
    Skip to main content

    Svelte

    Generated content

    This document was generated from the README in the Svelte GitHub repository.

    tip

    To connect to Unleash from a client-side context, you'll need to use the Unleash front-end API (how do I create an API token?) or the Unleash proxy (how do I create client keys?).

    Installation

    npm install @unleash/proxy-client-svelte
    # or
    yarn add @unleash/proxy-client-svelte

    How to use

    Initialize the client​

    Depending on your needs and specific use-case, prepare one of:

    And a respective frontend token (or, if you're using the Unleash Proxy, one of your proxy's designated client keys, previously known as proxy secrets).

    Import the provider like this in your entrypoint file (typically index.svelte):

    <script lang="ts">
        import { FlagProvider } from '@unleash/proxy-client-svelte';

        const config = {
            url: '<unleash-url>/api/frontend', // Your Front-end API, Unleash Edge or Unleash Proxy URL
            clientKey: '<your-token>', // Front-end API token (or proxy client key)
            refreshInterval: 15, // How often (in seconds) the client should poll the proxy for updates
            appName: 'your-app-name' // The name of your application. It's only used for identifying your application
        };
    </script>

    <FlagProvider {config}>
        <App />
    </FlagProvider>

    Connection options​

    To connect this SDK to your Unleash instance's front-end API, use the URL to your Unleash instance's front-end API (<unleash-url>/api/frontend) as the url parameter. For the clientKey parameter, use a FRONTEND token generated from your Unleash instance. Refer to the how to create API tokens guide for the necessary steps.

    To connect this SDK to the Unleash Edge, use the URL to your Unleash Edge instance as the url parameter. For the clientKey parameter, use a FRONTEND token generated from your Unleash Edge instance. Refer to the how to create API tokens guide for the necessary steps. Ensure that your Unleash Edge instance is correctly configured to have access to the feature toggles your FRONTEND token is requesting.

    To connect this SDK to the Unleash proxy, use the proxy's URL and a proxy client key. The configuration section of the Unleash proxy docs contains more info on how to configure client keys for your proxy.

    Check feature toggle status​

    To check if a feature is enabled:

    <script lang="ts">
        import { useFlag } from '@unleash/proxy-client-svelte';

        const enabled = useFlag('travel.landing');
    </script>

    {#if $enabled}
        <SomeComponent />
    {:else}
        <AnotherComponent />
    {/if}

    Check variants​

    To check variants:

    <script lang="ts">
        import { useVariant } from '@unleash/proxy-client-svelte';

        const variant = useVariant('travel.landing');
    </script>

    {#if variant.enabled && variant.name === 'SomeComponent'}
        <SomeComponent />
    {:else if variant.enabled && variant.name === 'AnotherComponent'}
        <AnotherComponent />
    {:else}
        <DefaultComponent />
    {/if}

    Defer rendering until flags fetched​

    useFlagsStatus retrieves the ready state and error events. -Follow the following steps in order to delay rendering until the flags have been fetched.

    <script lang="ts">
        import { useFlagsStatus } from '@unleash/proxy-client-svelte';

        const { flagsReady, flagsError } = useFlagsStatus();
    </script>

    {#if !$flagsReady}
        <Loading />
    {:else}
        <MyComponent error={flagsError} />
    {/if}

    Updating context​

    Initial context can be specified on a FlagProvider config.context property.

    <FlagProvider config={{ ...config, context: { userId: 123 }}>

    This code sample shows you how to update the unleash context dynamically:

    <script lang="ts">
        import { useUnleashContext, useFlag } from '@unleash/proxy-client-svelte';

        export let userId;

        const toggle = useFlag('my-toggle');
        const updateContext = useUnleashContext();

        $: {
            // context is updated with userId
            updateContext({ userId });
        }

        // OR if you need to perform an action right after new context is applied
        $: {
            async function run() {
                // Can wait for the new flags to pull in from the different context
                await updateContext({ userId });
                console.log('new flags loaded for', userId);
            }
            run();
        }
    </script>

    Advanced use cases

    Deferring client start​

    By default, the Unleash client will start polling for toggles immediately when the FlagProvider component renders. You can prevent it by setting startClient prop to false. This is useful when you'd like to for example bootstrap the client and work offline.

    Deferring the client start gives you more fine-grained control over when to start fetching the feature toggle configuration. This could be handy in cases where you need to get some other context data from the server before fetching toggles, for instance.

    To start the client, use the client's start method. The below snippet of pseudocode will defer polling until the end of the asyncProcess function.

    <script lang="ts">
        const client = new UnleashClient({
            /* ... */
        });

        onMount(async () => {
            // do async work ...
            client.start();
        });
    </script>

    <FlagProvider unleashClient={client} startClient={false}>
        <App />
    </FlagProvider>

    Use unleash client directly​

    <script lang="ts">
        import { useUnleashContext, useUnleashClient } from '@unleash/proxy-client-svelte';

        export let userId;

        const client = useUnleashClient();

        const login = () => {
            // login user
            if (client.isEnabled('new-onboarding')) {
                // Send user to new onboarding flow
            } else {
                // send user to old onboarding flow
            }
        };
    </script>

    <LoginForm {login} />

    This content was generated on

    - +Follow the following steps in order to delay rendering until the flags have been fetched.

    <script lang="ts">
        import { useFlagsStatus } from '@unleash/proxy-client-svelte';

        const { flagsReady, flagsError } = useFlagsStatus();
    </script>

    {#if !$flagsReady}
        <Loading />
    {:else}
        <MyComponent error={flagsError} />
    {/if}

    Updating context​

    Initial context can be specified on a FlagProvider config.context property.

    <FlagProvider config={{ ...config, context: { userId: 123 }}>

    This code sample shows you how to update the unleash context dynamically:

    <script lang="ts">
        import { useUnleashContext, useFlag } from '@unleash/proxy-client-svelte';

        export let userId;

        const toggle = useFlag('my-toggle');
        const updateContext = useUnleashContext();

        $: {
            // context is updated with userId
            updateContext({ userId });
        }

        // OR if you need to perform an action right after new context is applied
        $: {
            async function run() {
                // Can wait for the new flags to pull in from the different context
                await updateContext({ userId });
                console.log('new flags loaded for', userId);
            }
            run();
        }
    </script>

    Advanced use cases

    Deferring client start​

    By default, the Unleash client will start polling for toggles immediately when the FlagProvider component renders. You can prevent it by setting startClient prop to false. This is useful when you'd like to for example bootstrap the client and work offline.

    Deferring the client start gives you more fine-grained control over when to start fetching the feature toggle configuration. This could be handy in cases where you need to get some other context data from the server before fetching toggles, for instance.

    To start the client, use the client's start method. The below snippet of pseudocode will defer polling until the end of the asyncProcess function.

    <script lang="ts">
        const client = new UnleashClient({
            /* ... */
        });

        onMount(async () => {
            // do async work ...
            client.start();
        });
    </script>

    <FlagProvider unleashClient={client} startClient={false}>
        <App />
    </FlagProvider>

    Use unleash client directly​

    <script lang="ts">
        import { useUnleashContext, useUnleashClient } from '@unleash/proxy-client-svelte';

        export let userId;

        const client = useUnleashClient();

        const login = () => {
            // login user
            if (client.isEnabled('new-onboarding')) {
                // Send user to new onboarding flow
            } else {
                // send user to old onboarding flow
            }
        };
    </script>

    <LoginForm {login} />

    This content was generated on

    + \ No newline at end of file diff --git a/reference/sdks/vue.html b/reference/sdks/vue.html index eb1908af66..45edc8afe0 100644 --- a/reference/sdks/vue.html +++ b/reference/sdks/vue.html @@ -20,7 +20,7 @@ - + @@ -28,8 +28,8 @@
    Skip to main content

    Vue

    Generated content

    This document was generated from the README in the Vue GitHub repository.

    tip

    To connect to Unleash from a client-side context, you'll need to use the Unleash front-end API (how do I create an API token?) or the Unleash proxy (how do I create client keys?).

    proxy-client-vue

    PoC for a Vue SDK for Unleash based on the official proxy-client-react.

    Usage note​

    This library is meant to be used with Unleash Edge, the Unleash front-end API , or the Unleash proxy.

    It is not compatible with the Unleash client API.

    Installation​

    npm install @unleash/proxy-client-vue
    // or
    yarn add @unleash/proxy-client-vue

    Initialization​

    Using config:​

    import { createApp } from 'vue'
    import { plugin as unleashPlugin } from '@unleash/proxy-client-vue'
    // import the root component App from a single-file component.
    import App from './App.vue'

    const config = {
      url: 'https://HOSTNAME/proxy',
      clientKey: 'PROXYKEY',
      refreshInterval: 15,
      appName: 'your-app-name',
    }

    const app = createApp(App)
    app.use(unleashPlugin, { config })
    app.mount('#app')

    Or use the FlagProvider component like this in your entrypoint file (typically App.vue):

    import { FlagProvider } from '@unleash/proxy-client-vue'

    const config = {
      url: 'https://UNLEASH-INSTANCE/api/frontend',
      clientKey: 'CLIENT—SIDE—API—TOKEN',
      refreshInterval: 15,
      appName: 'your-app-name',
    }

    <template>
      <FlagProvider :config="config">
        <App />
      </FlagProvider>
    </template>

    Initializing your own client​

    import { createApp } from 'vue'
    import { plugin as unleashPlugin } from '@unleash/proxy-client-vue'
    // import the root component App from a single-file component.
    import App from './App.vue'

    const config = {
      url: 'https://HOSTNAME/proxy',
      clientKey: 'PROXYKEY',
      refreshInterval: 15,
      appName: 'your-app-name',
    }

    const client = new UnleashClient(config)

    const app = createApp(App)
    app.use(unleashPlugin, { unleashClient: client })
    app.mount('#app')

    Or, using FlagProvider:

    import { FlagProvider, UnleashClient } from '@unleash/proxy-client-vue'

    const config = {
      url: 'https://UNLEASH-INSTANCE/api/frontend',
      clientKey: 'CLIENT—SIDE—API—TOKEN',
      refreshInterval: 15,
      appName: 'your-app-name',
    }

    const client = new UnleashClient(config)

    <template>
      <FlagProvider :unleash-client="client">
        <App />
      </FlagProvider>
    </template>

    Deferring client start​

    By default, the Unleash client will start polling the Proxy for toggles immediately when the FlagProvider component renders. You can delay the polling by:

    • setting the startClient prop to false
    • passing a client instance to the FlagProvider
    <template>
      <FlagProvider :unleash-client="client" :start-client="false">
        <App />
      </FlagProvider>
    </template>

    Deferring the client start gives you more fine-grained control over when to start fetching the feature toggle configuration. This could be handy in cases where you need to get some other context data from the server before fetching toggles, for instance.

    To start the client, use the client's start method. The below snippet of pseudocode will defer polling until the end of the asyncProcess function.

    const client = new UnleashClient({
      /* ... */
    })

    onMounted(() => {
      const asyncProcess = async () => {
        // do async work ...
        client.start()
      }
      asyncProcess()
    })

    <template>
      <FlagProvider :unleash-client="client" :start-client="false">
        <App />
      </FlagProvider>
    </template>

    Usage​

    Check feature toggle status​

    To check if a feature is enabled:

    <script setup>
    import { useFlag } from '@unleash/proxy-client-vue'

    const enabled = useFlag('travel.landing')
    </script>

    <template>
      <SomeComponent v-if="enabled" />
      <AnotherComponent v-else />
    </template>

    Check variants​

    To check variants:

    <script setup>
    import { useVariant } from '@unleash/proxy-client-vue'

    const variant = useVariant('travel.landing')
    </script>

    <template>
      <SomeComponent v-if="variant.enabled && variant.name === 'SomeComponent'" />
      <AnotherComponent v-else-if="variant.enabled && variant.name === 'AnotherComponent" />
      <DefaultComponent v-else />
    </template>

    Defer rendering until flags fetched​

    useFlagsStatus retrieves the ready state and error events. -Follow the following steps in order to delay rendering until the flags have been fetched.

    import { useFlagsStatus } from '@unleash/proxy-client-vue'

    const { flagsReady, flagsError } = useFlagsStatus()

    <Loading v-if="!flagsReady" />
    <MyComponent v-else error={flagsError} />

    Updating context​

    Follow the following steps in order to update the unleash context:

    import { useUnleashContext, useFlag } from '@unleash/proxy-client-vue'

    const props = defineProps<{
      userId: string
    }>()

    const { userId } = toRefs(props)

    const updateContext = useUnleashContext()

    onMounted(() => {
      updateContext({ userId })
    })

    watch(userId, () => {
      async function run() {
        await updateContext({ userId: userId.value })
        console.log('new flags loaded for', userId.value)
      }
      run()
    })

    This content was generated on

    - +Follow the following steps in order to delay rendering until the flags have been fetched.

    import { useFlagsStatus } from '@unleash/proxy-client-vue'

    const { flagsReady, flagsError } = useFlagsStatus()

    <Loading v-if="!flagsReady" />
    <MyComponent v-else error={flagsError} />

    Updating context​

    Follow the following steps in order to update the unleash context:

    import { useUnleashContext, useFlag } from '@unleash/proxy-client-vue'

    const props = defineProps<{
      userId: string
    }>()

    const { userId } = toRefs(props)

    const updateContext = useUnleashContext()

    onMounted(() => {
      updateContext({ userId })
    })

    watch(userId, () => {
      async function run() {
        await updateContext({ userId: userId.value })
        console.log('new flags loaded for', userId.value)
      }
      run()
    })

    This content was generated on

    + \ No newline at end of file diff --git a/reference/segments.html b/reference/segments.html index 83b68bab80..8d1acaf271 100644 --- a/reference/segments.html +++ b/reference/segments.html @@ -20,7 +20,7 @@ - + @@ -29,7 +29,7 @@
    Skip to main content

    Segments

    Availability

    Segments are available to Unleash Pro and Unleash Enterprise users since Unleash 4.13 and was made available for Open Source from Unleash v5.5.

    A segment is a reusable collection of strategy constraints. Like with strategy constraints, you apply segments to feature flag activation strategies.

    You can apply the same segment to multiple activation strategies. If you update the segment, the changes will affect every strategy that uses that segment.

    Segments let you create user groups based on data available in the Unleash context. These groups can be as simple or as complex as you want to make them. You could, for example, use segments to target:

    • Users in a specific region
    • Users on a specific device type
    • Users who signed up before a specific point in time
    • ... Or any combination of the above.

    Because segments stay in sync across strategies, any changes will propagate to all the activation strategies that use them. This also makes them ideal for use cases such as activating or deactivating multiple feature flags at the same time. In other words, you can use segments to

    • release one or more new features at a specified time
    • create events with start and end times and guarantee that features will only be active during that period

    Segments can be global or scoped to a specific project. If a segment is scoped to a single project, it can only be used in that project and it adheres to that project's change request settings.

    Structure and evaluation​

    Segments are collections of strategy constraints. To satisfy a segment, all the constraints in the collection must be satisfied.

    If an activation strategy has a segment and additional constraints applied, the segment and the strategies must all be satisfied. Similarly, if an activation strategy has multiple segments, then they must must all be satisfied.

    Segment limits​

    In theory, you could create segments with a thousand constraints, each with a million values. But this wouldn't scale well, so there are limitations in place to stop you from doing this. Unleash enforces the following limits on use of segments:

    • If you're on a Pro plan

      A segment can have at most 250 values specified across all of its constraints. That means that if you add a constraint that uses 10 values, you will have 240 more values to use for any other constraints you add to the same segment.

    • If you're on an Enterprise plan

      A segment can have at most 1000 values specified across all of its constraints. That means that if you add a constraint that uses 70 values, you will have 930 more values to use for any other constraints you add to the same segment.

    By default, you can apply at most 5 segments to any one strategy. Separate strategies (even on the same feature) do not count towards the same total, so you can have two strategies with 5 segments each.

    You can configure segment limits with environment variables.

    A note on large segments​

    Segments are just constraints, so any limitations that apply to constraints also apply to segments.

    This means that if you want to add a hundred different user IDs to one of your constraints, you are most likely better off thinking about finding another way to solve this problem. That may be using a different abstraction or finding another pattern that you can use instead. Refer to the section on constraint limitations for a more thorough explanation or to the topic guide on using Unleash with large constraints for a more thorough .

    Creating, updating, and deleting segments​

    info

    Currently in development, Unleash will soon count segments as being in use when they are used in change requests.

    Segments can be created, edited, and deleted from the segments page in the admin UI or via the API (see the segments API documentation).

    A segment that is in use cannot be deleted. If you'd like to delete a segment that is in use, you must first remove the segment from all the activation strategies that are currently using it. If a segment is in use by an archived flag, you must either unarchive the flag and remove the segment or delete the flag entirely before the segment can be deleted.

    A segment that is in use in multiple projects can not be turned into a project-level segment. Further, a segment that is in use in project A cannot be turned into a project-level segment in project B.

    The Segments page, listing two existing segments: &quot;Mobile users&quot; and &quot;Users in the APAC region&quot;. The navigation menu with the Segments page link is opened and highlighted to provide navigation help.

    - + \ No newline at end of file diff --git a/reference/service-accounts.html b/reference/service-accounts.html index 3605c51b9b..23dc99ec99 100644 --- a/reference/service-accounts.html +++ b/reference/service-accounts.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Service Accounts

    Availability

    Service accounts is an enterprise feature available from Unleash 4.21 onwards.

    Service accounts are accounts that act as normal Unleash users and that respect the same set of permissions, but that don't represent real users. These accounts do not have a password and cannot log in to the Unleash UI. Instead, they are intended to be used to access the Unleash API programmatically, providing integrations an identity.

    Service account table

    Use service accounts to:

    • Provide a user-like identity to an integration or automation and manage it within Unleash
    • Give access to the Unleash API without giving access to the Unleash UI
    • Provide more fine-grained permissions than an admin token provides

    In order to create a service account, you can follow the how to create service accounts guide.

    Service account tokens​

    Service account tokens allow service accounts to use the Admin API as themselves with their own set of permissions, rather than using an admin token. See how to use the Admin API for more information.

    These tokens act just like personal access tokens for the service accounts, except that they are managed by Unleash admins.

    When using a service account token to modify resources, the event log will display the service account name for that operation.

    Service account tokens can be managed by editing the respective service account:

    Service account tokens

    - + \ No newline at end of file diff --git a/reference/sso.html b/reference/sso.html index d2423063f9..903cbe62b3 100644 --- a/reference/sso.html +++ b/reference/sso.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Single Sign-On

    The Single-Sign-On capability is only available for customers on the Enterprise subscription. Check out the Unleash plans for details.

    Unleash Enterprise supports SAML 2.0, OpenID Connect and Google Authentication. In addition, Unleash supports username/password authentication out of the box.

    Before you start​

    In order to configure Single-Sign-On you will need to log in to the Unleash instance with a user that have "Admin" role. If you are self-hosting Unleash then a default user will be automatically created the first time you start unleash:

    • username: admin
    • password: unleash4all (or admin if you started with Unleash v3).

    Guides​

    Unleash enterprise supports multiple authentication providers.

    - + \ No newline at end of file diff --git a/reference/stickiness.html b/reference/stickiness.html index 2bcc6b438a..9a7c7f6db5 100644 --- a/reference/stickiness.html +++ b/reference/stickiness.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Stickiness

    Stickiness is how Unleash guarantees that the same user gets the same features every time. Stickiness is useful in any scenario where you want to either show a feature to only a subset of users or give users a variant of a feature.

    Calculation​

    By default, Unleash calculates stickiness based on the user id and the group id. If the user id is unavailable, it falls back to using the session id instead. It hashes these values to a number between 0 and 100 using the MurmurHash hash function. This number is what determines whether a user will see a specific feature or variant. Because the process is deterministic, the same user will always get the same number.

    If both the user id and the session id is unavailable, the calculation returns a random value and stickiness is not guaranteed.

    Consistency​

    Because the number assigned to a user won't change, Unleash also guarantees that the a user will keep seeing the same features even if certain other parameters change.

    For instance: When using the gradual rollout activation strategy, any user whose number is less than or equal to the rollout percentage will see the feature. This means that the same users will keep seeing the feature even as you increase the percentage of your user base that sees the feature.

    Custom stickiness​

    info

    Custom stickiness is available starting from Unleash Enterprise v4.

    When using the gradual rollout strategy or feature toggle variants, you can use parameters other than the user id to calculate stickiness. More specifically, you can use any field, custom or otherwise, of the Unleash Context as long as you have enabled custom stickiness for these fields.

    SDK compatibility

    Custom stickiness is supported by all of our SDKs except for the Rust SDK. You can always refer to the SDK compatibility table for the full overview.

    Enabling custom stickiness​

    To enable custom stickiness on a field, navigate to the Create Context screen in the UI and find the field you want to enable. There's a "Custom stickiness" option at the bottom of the form. Enable this toggle and update the context field by pressing the "Update" button.

    The Create Context screen in the Unleash UI. There&#39;s a toggle at the bottom to control custom stickiness.

    Project default stickiness​

    Availability

    Project default stickiness was introduced in Unleash v5.

    Each project in Unleash can have its own default stickiness context field. Whenever you add a gradual rollout strategy or variants to a feature in that project, Unleash will use the configured context field as the initial value.

    Only context fields that have the custom stickiness option turned on can be used as default stickiness fields.

    If you don't specify a default custom stickiness, the project will use the "default" stickiness option, which works as described in the calculation section.

    You can configure project default stickiness when you create a project or by editing the project later.

    The Edit Project screen. There is a dropdown for setting the default stickiness

    - + \ No newline at end of file diff --git a/reference/strategy-constraints.html b/reference/strategy-constraints.html index de22ff2af2..2111475dc5 100644 --- a/reference/strategy-constraints.html +++ b/reference/strategy-constraints.html @@ -20,7 +20,7 @@ - + @@ -36,7 +36,7 @@ In that case the strategy will be evaluated from DATE_AFTER and until DATE_BEFORE.

    Date and time operators only support single values.

    Nametrue if currentTime is ...
    DATE_AFTERafter the provided date
    DATE_BEFOREbefore the provided date

    String operators​

    String operators differ from the other categories in two different ways:

    Nametrue if <context-field> ...Supports case-insensitivityAvailable since
    INis equal to any of the provided valuesNov3.3
    NOT_INis not equal to any of the provided valuesNov3.3
    STR_CONTAINScontains any of the provided stringsYesv4.9
    STR_ENDS_WITHends with any of the provided stringsYesv4.9
    STR_STARTS_WITHstarts with any of the provided stringsYesv4.9

    Versioning (SemVer) operators​

    The SemVer operators are used to compare version numbers such as application versions, dependency versions, etc.

    The SemVer input must follow a few rules:

    Versions with pre-release indicators (e.g. 4.8.0-rc.2) are considered less than versions without (e.g. 4.8.0) in accordance with the SemVer specification, item 11.

    You can read more about SemVer in the full SemVer specification.

    SemVer operators only support single values.

    Nametrue if <context-field> is ...
    SEMVER_EQequal to the provided value
    SEMVER_GTstrictly greater than the provided value
    SEMVER_LTstrictly less than the provided value

    Additionally, you can use negation to get less than or equal to and greater than or equal to functionality:

    EffectHowtrue if <context-field> is ...
    Greater than or equal toNegate SEMVER_LTgreater than or equal to the provided value
    Less than or equal toNegate SEMVER_GTless than or equal to the provided value

    "Not less than 2.0.0" is the same as "greater than or equal to 2.0.0". The same applies for less than or equal: "Not greater than 1.9.5." is the same as "less than or equal to 1.9.5".

    Interacting with strategy constraints in the client SDKs​

    note

    This section gives a brief overview over to use the client SDKs to interact with strategy constraints. The exact steps will vary depending on which client you are using, so make sure to consult the documentation for your specific client SDK.

    Strategy constraints require the Unleash Context to work. All official Unleash client SDKs support the option to pass dynamic context values to the isEnabled function (or the SDK's equivalent).

    If the strategy constraint uses a standard Unleash Context field, set the context field to the value you wish to give it.

    If the strategy constraint uses a custom context field, use the Unleash Context's properties field. Use the name of the custom context field as a key and set the value to your desired string.

    If you set a context field to a value that the SDKs cannot parse correctly for a chosen constraint operator, the strategy constraint will evaluate to false. In other words: if you have a strategy constraint operator that expects a number, such as NUM_GT, but you set the corresponding context field to a string value, then the expression will be false: "some string" is not greater than 5. This value can still be negated as explained in the section on negating values.

    Constraint limitations (or "how many user IDs can I add to a constraint")​

    tip

    Explore the content in this subsection in more depth in the topic guide on using Unleash with large constraints.

    When using a constraint operator that accepts a list of values, it might be tempting to add a large number of values to that list. However, we advise you not to do that: Unleash is not a database, and is not intended to store large amounts of data. Instead you should try and find a different way to achieve what you want.

    For instance, instead of adding hundreds of user ids to the constraint value list, think about what properties those users share. Are they beta testers? Are they premium members? Are they employees?

    Can you map their common feature into an Unleash context property instead and set the constraint on that? If they're beta testers, how about using a betaTester property? And likewise, for premium members, you could check to see if their membership is premium? And if they're employees, maybe you're better off checking whether their user ID ends with @yourcompany.tld?

    The reason why you should try and keep value lists small has to do with Unleash's evaluation model: Because Unleash's server-side SDKs fetch the full feature toggle configuration from Unleash, every value that you add to that constraint value list will increase the payload size. For small numbers, this isn't an issue, but as the list grows, so will the payload, and so will the time and processing power used by the SDK to evaluate the feature.

    Incompatibilities and undefined behavior​

    It's important that you use an up-to-date client SDK if you're using the advanced constraint operators introduced in Unleash 4.9. If your client SDK does not support the new operators, we cannot guarantee how it'll react. As a result, you may see different behavior across applications.

    If you use the new constraints with old SDKs, here's how it'll affect some of the SDKs (the list is not exhaustive):

    Please inspect the SDK compatibility table to see which version of your preferred SDK introduced support for this feature.

    After Unleash 4.9, we updated the Unleash client specification. Going forward, any constraint that a client does not recognize, must be evaluated as false

    [Deprecated]: Constrain on a specific environment​

    Before Unleash 4.3, using strategy constraints was the recommended way to have different toggle configurations per environment. Now that Unleash has environment support built in, we no longer recommend you use strategy constraints for this. Instead, see the environments documentation.

    1. userScore is not a default Unleash field, but can be added as a custom context field.↩
    - + \ No newline at end of file diff --git a/reference/strategy-variants.html b/reference/strategy-variants.html index cebf2c7581..a2948349a2 100644 --- a/reference/strategy-variants.html +++ b/reference/strategy-variants.html @@ -20,7 +20,7 @@ - + @@ -37,7 +37,7 @@ broad activation strategy with multiple percentage based variants.

    In the example below we configure fixed title for the internal users based on the clientId constraint. In the second strategy we split titles between all other users based on the 50%/50% split. strategy_variants example

    Client SDK Support​

    To make use of strategy variants, you need to use a compatible client. Client SDK with variant support:

    If you would like to give feedback on this feature, experience issues or have questions, please feel free to open an issue on GitHub.

    - + \ No newline at end of file diff --git a/reference/tags.html b/reference/tags.html index a18cc91309..c7d88fcf2a 100644 --- a/reference/tags.html +++ b/reference/tags.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Tags

    This feature was introduced in Unleash 3.11.0

    Do you want to filter your features to avoid having to see all features belonging to other teams than your own? Do you want to write a plugin that only gets notified about changes to features that your plugin knows how to handle?

    Say hello to Typed tags​

    Unleash supports tagging features with an arbitrary number of tags. This eases filtering the list of tags to only those features that are tagged with the tag you're interested in.

    How does it work?​

    Unleash will allow users to tag any feature with any number of tags. When viewing a feature, the UI will/may display all tags connected to that feature.

    When adding a new tag, a dropdown will show you which type of tag you're about to add. Our first type; simple are meant to be used for filtering features. Show only features that have a tag of MyTeam.

    Tag types​

    Types can be anything, and their purpose is to add some semantics to the tag itself.

    Some tag types will be defined by plugins (e.g. the slack plugin can define the Slack-type, to make it easy to specify which Slack channels to post updates for a specific feature toggle to).

    Other tags can be defined by the user to give semantic logic to the management of the UI. It could be that you want to use tag functionality to specify which products a feature toggle belongs to, or to which teams.

    - + \ No newline at end of file diff --git a/reference/technical-debt.html b/reference/technical-debt.html index 1b79d1ae3c..c606165ba2 100644 --- a/reference/technical-debt.html +++ b/reference/technical-debt.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Technical Debt

    At Unleash we care deeply about code quality. Technical debt creeps up over time and slowly builds to the point where it really starts to hurt. At that point it's too late. Feature toggles that have outlived their feature and are not cleaned up represent technical debt that you should remove from your code.

    Stale and potentially stale toggles​

    When a toggle is no longer useful, we say that it has become stale. A stale toggle is a toggle that has served its purpose and that you should remove from the code base. For a toggle to become stale, you have to explicitly mark it as such. You can mark a toggle as stale in the technical debt dashboard.

    Unleash also has a concept of potentially stale toggles. These are toggles that have lived longer than what Unleash expects them to based on their feature toggle type. However, Unleash can't know for sure whether a toggle is actually stale or not, so it's up to you to make the decision on whether to mark it as stale or to keep it as an active toggle.

    A toggle being (potentially) stale, does not affect how it performs in your application; it's only there to make it easier for you to manage your toggles.

    The technical debt dashboard​

    In order to assist with removing unused feature toggles, Unleash provides project health dashboards for each project. The health dashboard is listed as one of a project's tabs.

    Three UI elements describing the health rating of the project. The first card has info on the project, including its name. The second is the &quot;report card&quot;, containing the project&#39;s overall health rating, a toggle report, and potential actions. The last card is a list of all the project&#39;s toggles with data on when it was last seen, when it was created, when it expired, its status and a report.

    The dashboard includes a health report card, and a list of toggles that can be filtered on different parameters.

    Report card​

    The project&#39;s health report card. It lists the project&#39;s health rating and when it was last updated; a toggle report containing the number of active toggles in the project; and potential actions, in this case asking the user to review potentially stale toggles.

    The report card includes some statistics of your application. It lists the overall amount of your active toggles, the overall amount of stale toggles, and lastly, the toggles that Unleash believes should be stale. This calculation is performed on the basis of toggle types:

    • Release - Used to enable trunk-based development for teams practicing Continuous Delivery. Expected lifetime 40 days
    • Experiment - Used to perform multivariate or A/B testing. Expected lifetime 40 days
    • Operational - Used to control operational aspects of the system's behavior. Expected lifetime 7 days
    • Kill switch - Used to to gracefully degrade system functionality. (permanent)
    • Permission - Used to change the features or product experience that certain users receive. (permanent)

    If your toggle exceeds the expected lifetime of it's toggle type it will be marked as potentially stale.

    One thing to note is that the report card and corresponding list are showing stats related to the currently selected project. If you have more than one project, you will be provided with a project selector in order to swap between the projects.

    Health rating​

    Unleash calculates a project's health rating based on the project's total number of active toggles and how many of those active toggles are stale or potentially stale. When you archive a toggle, it no longer counts towards your project's health rating.

    The health rating updates once every hour, so there may be some lag if you have recently added, removed, or changed the status of a toggle.

    Toggle list​

    A table of the toggles in the current project with their health reports. The table has the following columns: name, last seen, created, expired, status, and report.

    The toggle list gives an overview over all of your toggles and their status. In this list you can sort the toggles by their name, last seen, created, expired, status and report. This will allow you to quickly get an overview over which toggles may be worth deprecating and removing from the code.

    - + \ No newline at end of file diff --git a/reference/unleash-context.html b/reference/unleash-context.html index 9e209cf875..6e11ec3f8d 100644 --- a/reference/unleash-context.html +++ b/reference/unleash-context.html @@ -20,7 +20,7 @@ - + @@ -29,7 +29,7 @@
    Skip to main content

    Unleash Context

    The Unleash Context contains information relating to the current feature toggle request. Unleash uses this context to evaluate activation strategies and strategy constraints and to calculate toggle stickiness. The Unleash Context is an important feature of all the Unleash client SDKs.

    Structure​

    You can group the Unleash Context fields into two separate groups based on how they work in the client SDKs: static and dynamic context fields.

    Static fields' values remain constant throughout an application's lifetime. You'll typically set these when you initialize the client SDK.

    Dynamic fields, however, can change with every request. You'll typically provide these when checking whether a toggle is enabled in your client.

    All fields are optional, but some strategies depend on certain fields being present. For instance, the UserIDs strategy requires that the userId field is present on the Context.

    The below table gives a brief overview over what the fields' intended usage is, their lifetime, and their type. Note that the exact type can vary between programming languages and implementations. Be sure to consult your specific client SDK for more information on its implementation of the Unleash Context.

    field nametypelifetimedescription
    appNamestringstaticthe name of the application
    environment1stringstaticthe environment the app is running in
    userIdstringdynamican identifier for the current user
    sessionIdstringdynamican identifier for the current session
    remoteAddressstringdynamicthe app's IP address
    propertiesMap<string, string>dynamica key-value store of any data you want
    currentTime2DateTime/stringdynamicA DateTime (or similar) data class instance or a string in an RFC3339-compatible format. Defaults to the current time if not set by the user.

    The properties field​

    The properties field is different from the others. You can use the properties field to provide arbitrary data to custom strategies or to strategy constraints. The properties field is also where you add values for custom context fields.

    A note on properties and constraints​

    Some SDK implementations of the Unleash Context allow for the values in the properties map to be of other types than a string type. Using non-string types as values may cause issues if you're using the property in a constraint. Because the Unleash Admin UI accepts any string as input for constraint checking, the SDKs must also assume that the value is a string.

    As an example: You've created a custom field called groupId. You know group IDs will always be numeric. You then create a constraint on a strategy that says the user must be in group 123456. If you were to set the property groupId to the number 123456 in the properties field on the SDK side, the constraint check would fail, because in most languages the number 123456 is not equal to the string 123456 (i.e. 123456 != "123456").

    Custom context fields​

    Availability

    Before Unleash 4.16, custom context fields were only available to Unleash Pro and Enterprise users. From 4.16 onwards, they're available to everyone. They were introduced in Unleash 3.2.28.

    Custom context fields allow you to extend the Unleash Context with more data that is applicable to your situation. Each context field definition consists of a name and an optional description. Additionally, you can choose to define a set of legal values, and you can choose whether or not the context field can be used in custom stickiness calculations for the gradual rollout strategy and for feature toggle variants.

    When interacting with custom context fields in code, they must be accessed via the Unleash Context's properties map, using the context field's name as the key.

    Creating and updating custom context fields​

    You can create as many custom context fields as you wish. Refer to "how to define custom context fields" for information on how you define your own custom context fields.

    You can update custom context fields after they have been created. You can change everything about the definition except for the name.

    By using the legal values option when creating a context field, you can create a set of valid options for a context field's values. If a context field has a defined set of legal values, the Unleash Admin UI will only allow users to enter one or more of the specified values. If a context field doesn't have any defined legal values, the user can enter whatever they want.

    Using a custom context field called region as an example: if you define the field's legal values as Africa, Asia, Europe, and North America, then you would only be allowed to use one or more of those four values when using the custom context field as a strategy constraint.

    A strategy constraint form with a constraint set to &quot;region&quot;. The &quot;values&quot; input is a dropdown menu containing the options &quot;Africa&quot;, &quot;Asia&quot;, &quot;Europe&quot;, and &quot;North America&quot;, as defined in the preceding paragraph.

    Custom stickiness​

    SDK compatibility

    Custom stickiness is supported by all of our SDKs except for the Rust SDK. You can always refer to the SDK compatibility table for the full overview.

    Any context field can be used to calculate custom stickiness. However, you need to explicitly tell Unleash that you want a field to be used for custom stickiness for it to be possible. You can enable this functionality either when you create the context field or at any later point. For steps on how to do this, see the How to define custom context fields guide.

    1. Check the strategy constraints: advanced support row of the compatibility table for an overview of which SDKs provide the currentTime property.↩
    2. If you're on Unleash 4.3 or higher, you'll probably want to use the environments feature instead of relying on the environment context field when working with environments.↩
    - + \ No newline at end of file diff --git a/reference/unleash-edge.html b/reference/unleash-edge.html index ab2fb803f5..bb4ddd77b6 100644 --- a/reference/unleash-edge.html +++ b/reference/unleash-edge.html @@ -20,7 +20,7 @@ - + @@ -42,8 +42,8 @@ However, tokens in <project>:<environment>.<secret> format will still filter by project.

    Metrics​

    ❗ Note: For Unleash to correctly register SDK usage metrics sent from Edge instances, your Unleash instance must be v4.22 or newer.

    Since Edge is designed to avoid overloading its upstream, Edge gathers and accumulates usage metrics from SDKs for a set interval (METRICS_INTERVAL_SECONDS) before posting a batch upstream. This reduces load on Unleash instances down to a single call every interval, instead of every single client posting to Unleash for updating metrics. Unleash instances running on versions older than 4.22 are not able to handle the batch format posted by Edge, which means you won't see any metrics from clients connected to an Edge instance until you're able to update to 4.22 or newer.

    Compatibility​

    Unleash Edge adheres to Semantic Versioning (SemVer) on the API and CLI layers. If you're using Unleash Edge as a library in your projects, be cautious, internal codebase changes, which might occur in any version release (including minor and patch versions), could potentially break your implementation.

    Performance​

    Unleash Edge will scale linearly with CPU. There are k6 benchmarks in the benchmark folder. We've already got some initial numbers from hey.

    Do note that the number of requests Edge can handle does depend on the total size of your toggle response. That is, Edge is faster if you only have 10 toggles with 1 strategy each, than it will be with 1000 toggles with multiple strategies on each. Benchmarks here were run with data fetched from the Unleash demo instance (roughly 100kB (350 features / 200 strategies)) as well as against a small dataset of 5 features with one strategy on each.

    Edge was started using -docker run --cpus="<cpu>" --memory=128M -p 3063:3063 -e UPSTREAM_URL=<upstream> -e TOKENS="<client token>" unleashorg/unleash-edge:edge -w <number of cpus rounded up to closest integer> edge

    Then we run hey against the proxy endpoint, evaluating toggles

    Large Dataset (350 features (100kB))​

    $ hey -z 10s -H "Authorization: <frontend token>" http://localhost:3063/api/frontend`
    CPUMemoryRPSEndpointp95Data transferred
    0.16.7 Mi600/api/frontend103ms76Mi
    16.7 Mi6900/api/frontend7.4ms866Mi
    49.525300/api/frontend2.4ms3.2Gi
    81540921/api/frontend1.6ms5.26Gi

    and against our client features endpoint.

    $ hey -z 10s -H "Authorization: <client token>" http://localhost:3063/api/client/features
    CPUMemory observedRPSEndpointp95Data transferred
    0.111 Mi309/api/client/features199ms300 Mi
    111 Mi3236/api/client/features16ms3 Gi
    411 Mi12815/api/client/features4.5ms14 Gi
    817 Mi23207/api/client/features2.7ms26 Gi

    Small Dataset (5 features (2kB))​

    $ hey -z 10s -H "Authorization: <frontend token>" http://localhost:3063/api/frontend`
    CPUMemoryRPSEndpointp95Data transferred
    0.14.3 Mi3673/api/frontend93ms9Mi
    16.7 Mi39000/api/frontend1.6ms80Mi
    46.9 Mi100020/api/frontend600μs252Mi
    812.5 Mi141090/api/frontend600μs324Mi

    and against our client features endpoint.

    $ hey -z 10s -H "Authorization: <client token>" http://localhost:3063/api/client/features
    CPUMemory observedRPSEndpointp95Data transferred
    0.14 Mi3298/api/client/features92ms64 Mi
    14 Mi32360/api/client/features2ms527Mi
    411 Mi95838/api/client/features600μs2.13 Gi
    817 Mi129381/api/client/features490μs2.87 Gi

    Why choose Unleash Edge over the Unleash Proxy?​

    Edge offers a superset of the same feature set as the Unleash Proxy and we've made sure it offers the same security and privacy features.

    However, there are a few notable differences between the Unleash Proxy and Unleash Edge:

    Debugging​

    You can adjust the RUST_LOG environment variable to see more verbose log output. For example, in order to get logs originating directly from Edge but not its dependencies, you can raise the default log level from error to warning and set Edge to debug, like this:

    RUST_LOG="warn,unleash-edge=debug" ./unleash-edge #<command>

    See more about available logging and log levels at https://docs.rs/env_logger/latest/env_logger/#enabling-logging

    Development​

    See our Contributors guide as well as our development-guide

    This content was generated on

    - +docker run --cpus="<cpu>" --memory=128M -p 3063:3063 -e UPSTREAM_URL=<upstream> -e TOKENS="<client token>" unleashorg/unleash-edge:edge -w <number of cpus rounded up to closest integer> edge

    Then we run hey against the proxy endpoint, evaluating toggles

    Large Dataset (350 features (100kB))​

    $ hey -z 10s -H "Authorization: <frontend token>" http://localhost:3063/api/frontend`
    CPUMemoryRPSEndpointp95Data transferred
    0.16.7 Mi600/api/frontend103ms76Mi
    16.7 Mi6900/api/frontend7.4ms866Mi
    49.525300/api/frontend2.4ms3.2Gi
    81540921/api/frontend1.6ms5.26Gi

    and against our client features endpoint.

    $ hey -z 10s -H "Authorization: <client token>" http://localhost:3063/api/client/features
    CPUMemory observedRPSEndpointp95Data transferred
    0.111 Mi309/api/client/features199ms300 Mi
    111 Mi3236/api/client/features16ms3 Gi
    411 Mi12815/api/client/features4.5ms14 Gi
    817 Mi23207/api/client/features2.7ms26 Gi

    Small Dataset (5 features (2kB))​

    $ hey -z 10s -H "Authorization: <frontend token>" http://localhost:3063/api/frontend`
    CPUMemoryRPSEndpointp95Data transferred
    0.14.3 Mi3673/api/frontend93ms9Mi
    16.7 Mi39000/api/frontend1.6ms80Mi
    46.9 Mi100020/api/frontend600μs252Mi
    812.5 Mi141090/api/frontend600μs324Mi

    and against our client features endpoint.

    $ hey -z 10s -H "Authorization: <client token>" http://localhost:3063/api/client/features
    CPUMemory observedRPSEndpointp95Data transferred
    0.14 Mi3298/api/client/features92ms64 Mi
    14 Mi32360/api/client/features2ms527Mi
    411 Mi95838/api/client/features600μs2.13 Gi
    817 Mi129381/api/client/features490μs2.87 Gi

    Why choose Unleash Edge over the Unleash Proxy?​

    Edge offers a superset of the same feature set as the Unleash Proxy and we've made sure it offers the same security and privacy features.

    However, there are a few notable differences between the Unleash Proxy and Unleash Edge:

    Debugging​

    You can adjust the RUST_LOG environment variable to see more verbose log output. For example, in order to get logs originating directly from Edge but not its dependencies, you can raise the default log level from error to warning and set Edge to debug, like this:

    RUST_LOG="warn,unleash-edge=debug" ./unleash-edge #<command>

    See more about available logging and log levels at https://docs.rs/env_logger/latest/env_logger/#enabling-logging

    Development​

    See our Contributors guide as well as our development-guide

    This content was generated on

    + \ No newline at end of file diff --git a/reference/unleash-proxy.html b/reference/unleash-proxy.html index 25fc955ec2..13a3d8e5e4 100644 --- a/reference/unleash-proxy.html +++ b/reference/unleash-proxy.html @@ -20,15 +20,15 @@ - +
    -
    Skip to main content

    Unleash Proxy

    Generated content

    This document was generated from the README in the Unleash Proxy GitHub repository.

    tip

    Looking for how to run the Unleash proxy? Check out the how to run the Unleash proxy guide!

    Build & Tests npm Docker Pulls

    The Unleash Proxy

    The Unleash proxy offers a way to use Unleash in client-side applications, such as single-page and native apps.

    Note: You might want to consider using Unleash Edge instead.

    The Unleash proxy sits between the Unleash API and your client-side SDK and does the evaluation of feature toggles for your client-side SDK. This way, you can keep your configuration private and secure, while still allowing your client-side apps to use Unleash's features.

    The proxy offers three important features:

    • Performance: The caches all features in memory and can run close to your end-users. A single instance can able to handle thousands of requests per second, and you can easily scale it by adding additional instances.
    • Security: The proxy evaluates the features for the user on the server-side and by default only exposes results for features that are enabled for the specific user. No feature toggle configuration is ever shared with the user.
    • Privacy: If you run the proxy yourself, Unleash will never get any data on your end-users: no user ids, no IPs, no nothing.
    Client-side apps connect to the Unleash proxy, which in turn connects to the Unleash API. The proxy itself uses the Unleash Node.js SDK to evaluate features. The SDK syncs with Unleash in the background. Local evaluation on the proxy provides privacy.

    A note on privacy and the proxy​

    Why would you not want to expose your Unleash configuration to your end-users?

    The way Unleash works, you can add all kinds of data to feature strategies and constraints. For instance, you might show a feature only to a specific subset of user IDs; or you might have a brand new and unannounced new feature with a revealing name.

    If you just sent the regular Unleash client payload to your client-side apps, all of this — the user IDs and the new feature names — would be exposed to your users.

    Single page apps work in the context of a specific user. The proxy allows you to only provide data that relates to that one user: The proxy will default to only returning the evaluated toggles that should be enabled for that specific user in that specific context.

    API​

    The Unleash proxy exposes a simple API for consumption by client-side SDKs.

    OpenAPI integration​

    ℹ️ Availability

    The OpenAPI integration is available in versions 0.9 and later of the Unleash proxy.

    The proxy can expose a runtime-generated OpenAPI JSON spec and a corresponding OpenAPI UI for its API. The OpenAPI UI page is an interactive page where you can discover and test the API endpoints the proxy exposes. The JSON spec can be used to generate an OpenAPI client with OpenAPI tooling such as the OpenAPI generator.

    To enable the JSON spec and UI, set ENABLE_OAS (environment variable) or enableOAS (in-code configuration variable) to true.

    The spec and UI can then be found at <base url>/docs/openapi.json and <base url>/docs/openapi respectively.

    You can refer to the how to enable the OpenAPI spec guide for more detailed information on how to configure it.

    GET /proxy​

    The primary proxy API operation. This endpoint accepts an Unleash context encoded as query parameters, and will return all toggles that are evaluated as true for the provided context.

    When sending GET requests to the Unleash proxy's /proxy endpoint, the request should contain the current Unleash context as query parameters. The proxy will return all enabled toggles for the provided context.

    Payload​

    The GET /proxy operation returns information about toggles enabled for the current user. The payload is a JSON object with a toggles property, which contains a list of toggles.

    {
      "toggles": [
        {
          "name": "demo",
          "enabled": true,
          "variant": {
            "name": "disabled",
            "enabled": false
          }
        },
        {
          "name": "demoApp.step1",
          "enabled": true,
          "variant": {
            "name": "disabled",
            "enabled": false
          }
        }
      ]
    }

    Toggle data​

    The data for a toggle without variants looks like this:

    {
      "name": "basic-toggle",
      "enabled": true,
      "variant": {
        "name": "disabled",
        "enabled": false
      }
    }
    • name: the name of the feature.
    • enabled: whether the toggle is enabled or not. Will always be true.
    • variant: describes whether the toggle has variants and, if it does, what variant is active for this user. If a toggle doesn't have any variants, it will always be {"name": "disabled", "enabled": false}.

    ℹ️ The "disabled" variant

    Unleash uses a fallback variant called "disabled" to indicate that a toggle has no variants. However, you are free to create a variant called "disabled" yourself. In that case you can tell them apart by checking the variant's enabled property: if the toggle has no variants, enabled will be false. If the toggle is the "disabled" variant that you created, it will have enabled set to true.

    If a toggle has variants, then the variant object can also contain an optional payload property. The payload will contain data about the variant's payload: what type it is, and what the content is. To learn more about variants and their payloads, check the feature toggle variants documentation.

    Variant toggles without payloads look will have their name listed and the enabled property set to true:

    {
      "name": "toggle-with-variants",
      "enabled": true,
      "variant": {
        "name": "simple",
        "enabled": true
      }
    }

    If the variant has a payload, the optional payload property will list the payload's type and it's content in a stringified form:

    {
      "name": "toggle-with-variants",
      "enabled": true,
      "variant": {
        "name": "with-payload-string",
        "payload": {
          "type": "string",
          "value": "this string is the variant's payload"
        },
        "enabled": true
      }
    }

    For the variant property:

    • name: is the name of the variant, as shown in the Admin UI.
    • enabled: indicates whether the variant is enabled or not. If the toggle has variants, this is always true.
    • payload (optional): Only present if the variant has a payload. Describes the payload's type and content.

    If the variant has a payload, the payload object contains:

    • type: the type of the variant's payload
    • value: the value of the variant's payload

    The value will always be the payload's content as a string, escaped as necessary. For instance, a variant with a JSON payload would look like this:

    {
      "name": "toggle-with-variants",
      "enabled": true,
      "variant": {
        "name": "with-payload-json",
        "payload": {
          "type": "json",
          "value": "{\"description\": \"this is data delivered as a json string\"}"
        },
        "enabled": true
      }
    }

    POST /proxy​

    The proxy also offers a POST API used to evaluate toggles This can be used to evaluate a list of know toggle names or to retrieve all enabled toggles for a given context.

    Evaluate list of known toggles​

    This method will allow you to send a list of toggle names together with an Unleash Context and evaluate them accordingly. It will return enablement of all provided toggles.

    URL: POST https://proxy-host.server/proxy

    Content Type: application/json

    Body:

    {
      "toggles": ["demoApp.step1"],
      "context": {
        "appName": "someApp",
        "sessionId": "233312AFF22"
      }
    }

    Result:

    HTTP/1.1 200 OK
    Access-Control-Allow-Origin: *
    Access-Control-Expose-Headers: ETag
    Cache-control: public, max-age=2
    Connection: keep-alive
    Content-Length: 122
    Content-Type: application/json; charset=utf-8
    Date: Wed, 30 Nov 2022 14:46:48 GMT
    ETag: W/"7a-RMKUyY0BWIhjahpVPWnNdXyDw6I"
    Keep-Alive: timeout=5
    Vary: Accept-Encoding

    {
        "toggles": [
            {
                "enabled": false,
                "impressionData": true,
                "name": "demoApp.step1",
                "variant": {
                    "enabled": false,
                    "name": "disabled"
                }
            }
        ]
    }

    Evaluate all enabled toggles​

    This method will allow you to get all enabled toggles for a given context.

    URL: POST https://proxy-host.server/proxy

    Content Type: application/json

    Body:

    {
      "context": {
        "appName": "someApp",
        "sessionId": "233312AFF22"
      }
    }

    Result:

    HTTP/1.1 200 OK
    Access-Control-Allow-Origin: *
    Access-Control-Expose-Headers: ETag
    Cache-control: public, max-age=2
    Connection: keep-alive
    Content-Length: 465
    Content-Type: application/json; charset=utf-8
    Date: Wed, 30 Nov 2022 14:48:55 GMT
    ETag: W/"1d1-dm6tkvMpkx42mZmojNSNKmHid1M"
    Keep-Alive: timeout=5
    Vary: Accept-Encoding

    {
        "toggles": [
            {
                "enabled": true,
                "impressionData": false,
                "name": "demoApp.step2",
                "variant": {
                    "enabled": true,
                    "name": "userWithId",
                    "payload": {
                        "type": "string",
                        "value": "90732934"
                    }
                }
            },
            {
                "enabled": true,
                "impressionData": false,
                "name": "demoApp.step3",
                "variant": {
                    "enabled": true,
                    "name": "C",
                    "payload": {
                        "type": "string",
                        "value": "hello"
                    }
                }
            },
            {
                "enabled": true,
                "impressionData": true,
                "name": "demoApp.step4",
                "variant": {
                    "enabled": true,
                    "name": "Orange",
                    "payload": {
                        "type": "string",
                        "value": "orange"
                    }
                }
            }
        ]
    }


    GET /proxy/all Return enabled and disabled toggles:​

    By default, the proxy only returns enabled toggles. However, in certain use cases, you might want it to return all toggles, regardless of whether they're enabled or disabled. The /proxy/all endpoint does this.

    Because returning all toggles regardless of their state is a potential security vulnerability, the endpoint has to be explicitly enabled. To enable it, set the enableAllEndpoint configuration option or the ENABLE_ALL_ENDPOINT environment variable to true.

    The response payload follows the same format as the GET /proxy response payload.

    GET /proxy/health: Health endpoint​

    The proxy will try to synchronize with the Unleash API at startup, until it has successfully done that the proxy will return HTTP 503 - Not Ready for all request. You can use the health endpoint to validate that the proxy is ready to receive requests:

    curl http://localhost:3000/proxy/health -I

    If the proxy is ready, the response should look a little something like this:

    HTTP/1.1 200 OK
    Access-Control-Allow-Origin: *
    Access-Control-Expose-Headers: ETag
    Content-Type: text/html; charset=utf-8
    Content-Length: 2
    ETag: W/"2-eoX0dku9ba8cNUXvu/DyeabcC+s"
    Date: Fri, 04 Jun 2021 10:38:27 GMT
    Connection: keep-alive
    Keep-Alive: timeout=5

    Configuration options​

    The Proxy has a large number of configuration options that you can use to adjust it to your specific use case. The following table lists all the available options.

    ℹ️ Required configuration

    You must configure these three variables for the proxy to start successfully:

    • unleashUrl / UNLEASH_URL

    • unleashApiToken / UNLEASH_API_TOKEN

    • clientKeys / UNLEASH_PROXY_CLIENT_KEYS

    OptionEnvironment VariableDefault valueRequiredDescription
    unleashUrlUNLEASH_URLn/ayesAPI Url to the Unleash instance to connect to
    unleashApiTokenUNLEASH_API_TOKENn/ayesAPI token (client) needed to connect to Unleash API.
    clientKeysUNLEASH_PROXY_CLIENT_KEYSn/ayesList of client keys that the proxy should accept. When querying the proxy, Proxy SDKs must set the request's client keys header to one of these values. The default client keys header is Authorization.
    proxySecretsUNLEASH_PROXY_SECRETSn/anoDeprecated alias for clientKeys. Please use clientKeys instead.
    n/aPORT or PROXY_PORT3000noThe port where the proxy should listen.
    proxyBasePathPROXY_BASE_PATH""noThe base path to run the proxy from. "/proxy" will be added at the end. For instance, if proxyBasePath is "base/path", the proxy will run at /base/path/proxy.
    unleashAppNameUNLEASH_APP_NAME"unleash-proxy"noApp name to used when registering with Unleash
    unleashInstanceIdUNLEASH_INSTANCE_IDgeneratednoUnleash instance id to used when registering with Unleash
    refreshIntervalUNLEASH_FETCH_INTERVAL5000noHow often the proxy should query Unleash for updates, defined in ms.
    metricsIntervalUNLEASH_METRICS_INTERVAL30000noHow often the proxy should send usage metrics back to Unleash, defined in ms.
    metricsJitterUNLEASH_METRICS_JITTER0noAdds jitter to the metrics interval to avoid multiple instances sending metrics at the same time, defined in ms.
    environmentUNLEASH_ENVIRONMENTundefinednoIf set this will be the environment used by the proxy in the Unleash Context. It will not be possible for proxy SDKs to override the environment if set.
    projectNameUNLEASH_PROJECT_NAMEundefinednoThe projectName (id) to fetch feature toggles for. The proxy will only return know about feature toggles that belongs to the project, if specified.
    loggern/aSimpleLoggernoRegister a custom logger.
    useJsonLoggerJSON_LOGGERfalsenoSets the default logger to log as one-line JSON. This has no effect if a custom logger is provided.
    logLevelLOG_LEVEL "warn"noUsed to set logLevel. Supported options: "debug", "info", "warn", "error" and "fatal"
    customStrategiesUNLEASH_CUSTOM_STRATEGIES_FILE[]noUse this option to inject implementation of custom activation strategies. If you are using UNLEASH_CUSTOM_STRATEGIES_FILE you need to provide a valid path to a javascript file which exports an array of custom activation strategies and the SDK will automatically load these
    trustProxyTRUST_PROXY falsenoBy enabling the trustProxy option, Unleash Proxy will have knowledge that it's sitting behind a proxy and that the X-Forwarded-* header fields may be trusted, which otherwise may be easily spoofed. The proxy will automatically enrich the ip address in the Unleash Context. Can either be true/false (Trust all proxies), trust only given IP/CIDR (e.g. '127.0.0.1') as a string. May be a list of comma separated values (e.g. '127.0.0.1,192.168.1.1/24'
    namePrefixUNLEASH_NAME_PREFIXundefinednoUsed to filter features by using prefix when requesting backend values.
    tagsUNLEASH_TAGSundefinednoUsed to filter features by using tags set for features. Format should be tagName:tagValue,tagName2:tagValue2
    clientKeysHeaderNameCLIENT_KEY_HEADER_NAME"authorization"noThe name of the HTTP header to use for client keys. Incoming requests must set the value of this header to one of the Proxy's clientKeys to be authorized successfully.
    storageProvidern/aundefinednoRegister a custom storage provider. Refer to the section on custom storage providers in the Node.js SDK's readme for more information.
    enableOASENABLE_OASfalsenoSet to true to expose the proxy's OpenAPI spec at /docs/openapi.json and an interactive OpenAPI UI at /docs/openapi. Read more in the OpenAPI section.
    enableAllEndpointENABLE_ALL_ENDPOINTfalsenoSet to true to expose the /proxy/all endpoint. Refer to the section on returning all toggles for more info.
    corsn/an/anoPass custom options for CORS module
    cors.allowedHeadersCORS_ALLOWED_HEADERSn/anoHeaders to allow for CORS
    cors.credentialsCORS_CREDENTIALSfalsenoAllow credentials in CORS requests
    cors.exposedHeadersCORS_EXPOSED_HEADERS"ETag"noHeaders to expose for CORS
    cors.maxAgeCORS_MAX_AGE172800noMaximum number of seconds to cache CORS results
    cors.methodsCORS_METHODS"GET, POST"noMethods to allow for CORS
    cors.optionsSuccessStatusCORS_OPTIONS_SUCCESS_STATUS204noIf the Options call passes CORS, which http status to return
    cors.originCORS_ORIGIN*noOrigin URL or list of comma separated list of URLs to whitelist for CORS
    cors.preflightContinueCORS_PREFLIGHT_CONTINUEfalseno
    httpOptions.rejectUnauthorizedHTTP_OPTIONS_REJECT_UNAUTHORIZEDtruenoIf true, unleash-proxy will automatically reject connections to unleash server with invalid certificates

    Experimental configuration options​

    Some functionality is under validation and introduced as experimental. This allows us to test new functionality early and quickly. Experimental options can change or be removed at any point in the future and are explicitly not part of the proxy's semantic versioning.

    OptionEnvironment VariableDefault valueRequiredDescription
    expBootstrapn/an/anoWhere the Proxy can bootstrap configuration from. See Node.js SDK for details.
    expBootstrap.urlEXP_BOOTSTRAP_URLn/anoUrl where the Proxy can bootstrap configuration from. See Node.js SDK for details.
    expBootstrap.urlHeaders.AuthorizationEXP_BOOTSTRAP_AUTHORIZATIONn/anoAuthorization header value to be used when bootstrapping
    expServerSideSdkConfig.tokensEXP_SERVER_SIDE_SDK_CONFIG_TOKENSn/anoAPI tokens that can be used by Server SDKs (and proxies) to read feature toggle configuration from this Proxy instance.
    OptionEnvironment VariableDefault valueRequiredDescription
    expBootstrapn/an/anoWhere the Proxy can bootstrap configuration from. See Node.js SDK for details.
    expBootstrap.urlEXP_BOOTSTRAP_URLn/anoUrl where the Proxy can bootstrap configuration from. See Node.js SDK for details.
    expBootstrap.urlHeaders.AuthorizationEXP_BOOTSTRAP_AUTHORIZATIONn/anoAuthorization header value to be used when bootstrapping
    expServerSideSdkConfig.tokensEXP_SERVER_SIDE_SDK_CONFIG_TOKENSn/anoAPI tokens that can be used by Server SDKs (and proxies) to read feature toggle configuration from this Proxy instance.
    expCustomEnrichersEXP_CUSTOM_ENRICHERS_FILE[]noUse this option to inject implementation of custom context enrichers. If you are using EXP_CUSTOM_ENRICHERS_FILE you need to provide a valid path to a javascript file which exports an array of custom context enrichers and the SDK will automatically load these

    Internal SDK capabilities​

    The proxy uses the Node.js SDK internally. When you start the proxy it initializes a client for you using any configuration option you provided on startup. You can also provide your own client.

    The client that the proxy uses supports all the SDK features that the Node.js SDK supports, as listed in the Unleash server-side compatibility overview. The proxy has supported advanced strategy constraints since version 0.8. Because the proxy uses the Node SDK internally,

    Run The Unleash Proxy​

    The Unleash proxy is a small stateless HTTP application you run. The only requirement is that it needs to be able to talk with the Unleash API (either Unleash OSS or Unleash Hosted).

    Run with Docker​

    The easies way to run Unleash is via Docker. We have published a docker image on docker hub.

    Step 1: Pull

    docker pull unleashorg/unleash-proxy

    Step 2: Start

    docker run \
       -e UNLEASH_PROXY_CLIENT_KEYS=some-secret \
       -e UNLEASH_URL=https://app.unleash-hosted.com/demo/api/ \
       -e UNLEASH_API_TOKEN=56907a2fa53c1d16101d509a10b78e36190b0f918d9f122d \
       -p 3000:3000 \
       unleashorg/unleash-proxy

    You should see the following output:

    Unleash-proxy is listening on port 3000!

    Step 3: verify

    In order to verify the proxy you can use curl and see that you get a few evaluated feature toggles back:

    curl http://localhost:3000/proxy -H "Authorization: some-secret"

    Expected output would be something like:

    {
      "toggles": [
        {
          "name": "demo",
          "enabled": true,
          "variant": {
            "name": "disabled",
            "enabled": false
          }
        },
        {
          "name": "demoApp.step1",
          "enabled": true,
          "variant": {
            "name": "disabled",
            "enabled": false
          }
        }
      ]
    }

    Health endpoint

    The proxy will try to synchronize with the Unleash API at startup, until it has successfully done that the proxy will return HTTP 503 - Not Read? for all request. You can use the health endpoint to validate that the proxy is ready to recieve requests:

    curl http://localhost:3000/proxy/health -I
    HTTP/1.1 200 OK
    Access-Control-Allow-Origin: *
    Access-Control-Expose-Headers: ETag
    Content-Type: text/html; charset=utf-8
    Content-Length: 2
    ETag: W/"2-eoX0dku9ba8cNUXvu/DyeabcC+s"
    Date: Fri, 04 Jun 2021 10:38:27 GMT
    Connection: keep-alive
    Keep-Alive: timeout=5

    Run with Node.js:​

    STEP 1: Install dependency

    npm install @unleash/proxy

    STEP 2: use in your code

    const port = 3000;

    const { createApp } = require('@unleash/proxy');

    const app = createApp({
      unleashUrl: 'https://app.unleash-hosted.com/demo/api/',
      unleashApiToken: '56907a2fa53c1d16101d509a10b78e36190b0f918d9f122d',
      clientKeys: ['proxy-secret', 'another-proxy-secret', 's1'],
      refreshInterval: 1000,
      // logLevel: 'info',
      // projectName: 'order-team',
      // environment: 'development',
    });

    app.listen(port, () =>
      // eslint-disable-next-line no-console
      console.log(`Unleash Proxy listening on http://localhost:${port}/proxy`),
    );

    How to connect to the Proxy?​

    Unleash offers several different client-side SDKs for a number of use cases, and the community has created even more. These SDKs connect to the proxy and integrate with well with their designated language/framework. They also sync with the proxy at periodic intervals and post usage metrics back to Unleash via the proxy.

    For applications where there is no appropriate client-side SDK or where you simply want to avoid the dependency, you could also get away with using a simple HTTP-client if you just want to get the list of active features.

    The proxy is also ideal fit for serverless functions such as AWS Lambda. In that scenario the proxy can run on a small container near the serverless function, preferably in the same VPC, giving the lambda extremely fast access to feature flags, at a predictable cost.

    Custom activation strategies​

    ℹ️ Limitations for hosted proxies

    Custom activation strategies can not be used with the Unleash-hosted proxy available to Pro and Enterprise customers.

    The Unleash Proxy can load custom activation strategies for client-side SDKs. For a step-by-step guide, refer to the how to use custom strategies guide.

    To load custom strategies, use either of these two options:

    • the customStrategies option: use this if you're running the Unleash Proxy via Node directly.
    • the UNLEASH_CUSTOM_STRATEGIES_FILE environment variable: use this if you're running the proxy as a container.

    Both options take a list of file paths to JavaScript files that export custom strategy implementations.

    Custom activation strategy files format​

    Each strategy file must export a list of instantiated strategies. A file can export as many strategies as you'd like.

    Here's an example file that exports two custom strategies:

    const { Strategy } = require('unleash-client');

    class MyCustomStrategy extends Strategy {
      // ... strategy implementation
    }

    class MyOtherCustomStrategy extends Strategy {
      // ... strategy implementation
    }

    // export strategies
    module.exports = [new MyCustomStrategy(), new MyOtherCustomStrategy()];

    Refer the custom activation strategy documentation for more details on how to implement a custom activation strategy.

    This content was generated on

    - +
    Skip to main content

    Unleash Proxy

    Generated content

    This document was generated from the README in the Unleash Proxy GitHub repository.

    tip

    Looking for how to run the Unleash proxy? Check out the how to run the Unleash proxy guide!

    Build & Tests npm Docker Pulls

    The Unleash Proxy

    The Unleash proxy offers a way to use Unleash in client-side applications, such as single-page and native apps.

    Note: You might want to consider using Unleash Edge instead.

    The Unleash proxy sits between the Unleash API and your client-side SDK and does the evaluation of feature toggles for your client-side SDK. This way, you can keep your configuration private and secure, while still allowing your client-side apps to use Unleash's features.

    The proxy offers three important features:

    • Performance: The caches all features in memory and can run close to your end-users. A single instance can able to handle thousands of requests per second, and you can easily scale it by adding additional instances.
    • Security: The proxy evaluates the features for the user on the server-side and by default only exposes results for features that are enabled for the specific user. No feature toggle configuration is ever shared with the user.
    • Privacy: If you run the proxy yourself, Unleash will never get any data on your end-users: no user ids, no IPs, no nothing.
    Client-side apps connect to the Unleash proxy, which in turn connects to the Unleash API. The proxy itself uses the Unleash Node.js SDK to evaluate features. The SDK syncs with Unleash in the background. Local evaluation on the proxy provides privacy.

    A note on privacy and the proxy​

    Why would you not want to expose your Unleash configuration to your end-users?

    The way Unleash works, you can add all kinds of data to feature strategies and constraints. For instance, you might show a feature only to a specific subset of user IDs; or you might have a brand new and unannounced new feature with a revealing name.

    If you just sent the regular Unleash client payload to your client-side apps, all of this — the user IDs and the new feature names — would be exposed to your users.

    Single page apps work in the context of a specific user. The proxy allows you to only provide data that relates to that one user: The proxy will default to only returning the evaluated toggles that should be enabled for that specific user in that specific context.

    API​

    The Unleash proxy exposes a simple API for consumption by client-side SDKs.

    OpenAPI integration​

    ℹ️ Availability

    The OpenAPI integration is available in versions 0.9 and later of the Unleash proxy.

    The proxy can expose a runtime-generated OpenAPI JSON spec and a corresponding OpenAPI UI for its API. The OpenAPI UI page is an interactive page where you can discover and test the API endpoints the proxy exposes. The JSON spec can be used to generate an OpenAPI client with OpenAPI tooling such as the OpenAPI generator.

    To enable the JSON spec and UI, set ENABLE_OAS (environment variable) or enableOAS (in-code configuration variable) to true.

    The spec and UI can then be found at <base url>/docs/openapi.json and <base url>/docs/openapi respectively.

    You can refer to the how to enable the OpenAPI spec guide for more detailed information on how to configure it.

    GET /proxy​

    The primary proxy API operation. This endpoint accepts an Unleash context encoded as query parameters, and will return all toggles that are evaluated as true for the provided context.

    When sending GET requests to the Unleash proxy's /proxy endpoint, the request should contain the current Unleash context as query parameters. The proxy will return all enabled toggles for the provided context.

    Payload​

    The GET /proxy operation returns information about toggles enabled for the current user. The payload is a JSON object with a toggles property, which contains a list of toggles.

    {
      "toggles": [
        {
          "name": "demo",
          "enabled": true,
          "variant": {
            "name": "disabled",
            "enabled": false
          }
        },
        {
          "name": "demoApp.step1",
          "enabled": true,
          "variant": {
            "name": "disabled",
            "enabled": false
          }
        }
      ]
    }

    Toggle data​

    The data for a toggle without variants looks like this:

    {
      "name": "basic-toggle",
      "enabled": true,
      "variant": {
        "name": "disabled",
        "enabled": false
      }
    }
    • name: the name of the feature.
    • enabled: whether the toggle is enabled or not. Will always be true.
    • variant: describes whether the toggle has variants and, if it does, what variant is active for this user. If a toggle doesn't have any variants, it will always be {"name": "disabled", "enabled": false}.

    ℹ️ The "disabled" variant

    Unleash uses a fallback variant called "disabled" to indicate that a toggle has no variants. However, you are free to create a variant called "disabled" yourself. In that case you can tell them apart by checking the variant's enabled property: if the toggle has no variants, enabled will be false. If the toggle is the "disabled" variant that you created, it will have enabled set to true.

    If a toggle has variants, then the variant object can also contain an optional payload property. The payload will contain data about the variant's payload: what type it is, and what the content is. To learn more about variants and their payloads, check the feature toggle variants documentation.

    Variant toggles without payloads look will have their name listed and the enabled property set to true:

    {
      "name": "toggle-with-variants",
      "enabled": true,
      "variant": {
        "name": "simple",
        "enabled": true
      }
    }

    If the variant has a payload, the optional payload property will list the payload's type and it's content in a stringified form:

    {
      "name": "toggle-with-variants",
      "enabled": true,
      "variant": {
        "name": "with-payload-string",
        "payload": {
          "type": "string",
          "value": "this string is the variant's payload"
        },
        "enabled": true
      }
    }

    For the variant property:

    • name: is the name of the variant, as shown in the Admin UI.
    • enabled: indicates whether the variant is enabled or not. If the toggle has variants, this is always true.
    • payload (optional): Only present if the variant has a payload. Describes the payload's type and content.

    If the variant has a payload, the payload object contains:

    • type: the type of the variant's payload
    • value: the value of the variant's payload

    The value will always be the payload's content as a string, escaped as necessary. For instance, a variant with a JSON payload would look like this:

    {
      "name": "toggle-with-variants",
      "enabled": true,
      "variant": {
        "name": "with-payload-json",
        "payload": {
          "type": "json",
          "value": "{\"description\": \"this is data delivered as a json string\"}"
        },
        "enabled": true
      }
    }

    POST /proxy​

    The proxy also offers a POST API used to evaluate toggles This can be used to evaluate a list of know toggle names or to retrieve all enabled toggles for a given context.

    Evaluate list of known toggles​

    This method will allow you to send a list of toggle names together with an Unleash Context and evaluate them accordingly. It will return enablement of all provided toggles.

    URL: POST https://proxy-host.server/proxy

    Content Type: application/json

    Body:

    {
      "toggles": ["demoApp.step1"],
      "context": {
        "appName": "someApp",
        "sessionId": "233312AFF22"
      }
    }

    Result:

    HTTP/1.1 200 OK
    Access-Control-Allow-Origin: *
    Access-Control-Expose-Headers: ETag
    Cache-control: public, max-age=2
    Connection: keep-alive
    Content-Length: 122
    Content-Type: application/json; charset=utf-8
    Date: Wed, 30 Nov 2022 14:46:48 GMT
    ETag: W/"7a-RMKUyY0BWIhjahpVPWnNdXyDw6I"
    Keep-Alive: timeout=5
    Vary: Accept-Encoding

    {
        "toggles": [
            {
                "enabled": false,
                "impressionData": true,
                "name": "demoApp.step1",
                "variant": {
                    "enabled": false,
                    "name": "disabled"
                }
            }
        ]
    }

    Evaluate all enabled toggles​

    This method will allow you to get all enabled toggles for a given context.

    URL: POST https://proxy-host.server/proxy

    Content Type: application/json

    Body:

    {
      "context": {
        "appName": "someApp",
        "sessionId": "233312AFF22"
      }
    }

    Result:

    HTTP/1.1 200 OK
    Access-Control-Allow-Origin: *
    Access-Control-Expose-Headers: ETag
    Cache-control: public, max-age=2
    Connection: keep-alive
    Content-Length: 465
    Content-Type: application/json; charset=utf-8
    Date: Wed, 30 Nov 2022 14:48:55 GMT
    ETag: W/"1d1-dm6tkvMpkx42mZmojNSNKmHid1M"
    Keep-Alive: timeout=5
    Vary: Accept-Encoding

    {
        "toggles": [
            {
                "enabled": true,
                "impressionData": false,
                "name": "demoApp.step2",
                "variant": {
                    "enabled": true,
                    "name": "userWithId",
                    "payload": {
                        "type": "string",
                        "value": "90732934"
                    }
                }
            },
            {
                "enabled": true,
                "impressionData": false,
                "name": "demoApp.step3",
                "variant": {
                    "enabled": true,
                    "name": "C",
                    "payload": {
                        "type": "string",
                        "value": "hello"
                    }
                }
            },
            {
                "enabled": true,
                "impressionData": true,
                "name": "demoApp.step4",
                "variant": {
                    "enabled": true,
                    "name": "Orange",
                    "payload": {
                        "type": "string",
                        "value": "orange"
                    }
                }
            }
        ]
    }


    GET /proxy/all Return enabled and disabled toggles:​

    By default, the proxy only returns enabled toggles. However, in certain use cases, you might want it to return all toggles, regardless of whether they're enabled or disabled. The /proxy/all endpoint does this.

    Because returning all toggles regardless of their state is a potential security vulnerability, the endpoint has to be explicitly enabled. To enable it, set the enableAllEndpoint configuration option or the ENABLE_ALL_ENDPOINT environment variable to true.

    The response payload follows the same format as the GET /proxy response payload.

    GET /proxy/health: Health endpoint​

    The proxy will try to synchronize with the Unleash API at startup, until it has successfully done that the proxy will return HTTP 503 - Not Ready for all request. You can use the health endpoint to validate that the proxy is ready to receive requests:

    curl http://localhost:3000/proxy/health -I

    If the proxy is ready, the response should look a little something like this:

    HTTP/1.1 200 OK
    Access-Control-Allow-Origin: *
    Access-Control-Expose-Headers: ETag
    Content-Type: text/html; charset=utf-8
    Content-Length: 2
    ETag: W/"2-eoX0dku9ba8cNUXvu/DyeabcC+s"
    Date: Fri, 04 Jun 2021 10:38:27 GMT
    Connection: keep-alive
    Keep-Alive: timeout=5

    Configuration options​

    The Proxy has a large number of configuration options that you can use to adjust it to your specific use case. The following table lists all the available options.

    ℹ️ Required configuration

    You must configure these three variables for the proxy to start successfully:

    • unleashUrl / UNLEASH_URL

    • unleashApiToken / UNLEASH_API_TOKEN

    • clientKeys / UNLEASH_PROXY_CLIENT_KEYS

    OptionEnvironment VariableDefault valueRequiredDescription
    unleashUrlUNLEASH_URLn/ayesAPI Url to the Unleash instance to connect to
    unleashApiTokenUNLEASH_API_TOKENn/ayesAPI token (client) needed to connect to Unleash API.
    clientKeysUNLEASH_PROXY_CLIENT_KEYSn/ayesList of client keys that the proxy should accept. When querying the proxy, Proxy SDKs must set the request's client keys header to one of these values. The default client keys header is Authorization.
    proxySecretsUNLEASH_PROXY_SECRETSn/anoDeprecated alias for clientKeys. Please use clientKeys instead.
    n/aPORT or PROXY_PORT3000noThe port where the proxy should listen.
    proxyBasePathPROXY_BASE_PATH""noThe base path to run the proxy from. "/proxy" will be added at the end. For instance, if proxyBasePath is "base/path", the proxy will run at /base/path/proxy.
    unleashAppNameUNLEASH_APP_NAME"unleash-proxy"noApp name to used when registering with Unleash
    unleashInstanceIdUNLEASH_INSTANCE_IDgeneratednoUnleash instance id to used when registering with Unleash
    refreshIntervalUNLEASH_FETCH_INTERVAL5000noHow often the proxy should query Unleash for updates, defined in ms.
    metricsIntervalUNLEASH_METRICS_INTERVAL30000noHow often the proxy should send usage metrics back to Unleash, defined in ms.
    metricsJitterUNLEASH_METRICS_JITTER0noAdds jitter to the metrics interval to avoid multiple instances sending metrics at the same time, defined in ms.
    environmentUNLEASH_ENVIRONMENTundefinednoIf set this will be the environment used by the proxy in the Unleash Context. It will not be possible for proxy SDKs to override the environment if set.
    projectNameUNLEASH_PROJECT_NAMEundefinednoThe projectName (id) to fetch feature toggles for. The proxy will only return know about feature toggles that belongs to the project, if specified.
    loggern/aSimpleLoggernoRegister a custom logger.
    useJsonLoggerJSON_LOGGERfalsenoSets the default logger to log as one-line JSON. This has no effect if a custom logger is provided.
    logLevelLOG_LEVEL "warn"noUsed to set logLevel. Supported options: "debug", "info", "warn", "error" and "fatal"
    customStrategiesUNLEASH_CUSTOM_STRATEGIES_FILE[]noUse this option to inject implementation of custom activation strategies. If you are using UNLEASH_CUSTOM_STRATEGIES_FILE you need to provide a valid path to a javascript file which exports an array of custom activation strategies and the SDK will automatically load these
    trustProxyTRUST_PROXY falsenoBy enabling the trustProxy option, Unleash Proxy will have knowledge that it's sitting behind a proxy and that the X-Forwarded-* header fields may be trusted, which otherwise may be easily spoofed. The proxy will automatically enrich the ip address in the Unleash Context. Can either be true/false (Trust all proxies), trust only given IP/CIDR (e.g. '127.0.0.1') as a string. May be a list of comma separated values (e.g. '127.0.0.1,192.168.1.1/24'
    namePrefixUNLEASH_NAME_PREFIXundefinednoUsed to filter features by using prefix when requesting backend values.
    tagsUNLEASH_TAGSundefinednoUsed to filter features by using tags set for features. Format should be tagName:tagValue,tagName2:tagValue2
    clientKeysHeaderNameCLIENT_KEY_HEADER_NAME"authorization"noThe name of the HTTP header to use for client keys. Incoming requests must set the value of this header to one of the Proxy's clientKeys to be authorized successfully.
    storageProvidern/aundefinednoRegister a custom storage provider. Refer to the section on custom storage providers in the Node.js SDK's readme for more information.
    enableOASENABLE_OASfalsenoSet to true to expose the proxy's OpenAPI spec at /docs/openapi.json and an interactive OpenAPI UI at /docs/openapi. Read more in the OpenAPI section.
    enableAllEndpointENABLE_ALL_ENDPOINTfalsenoSet to true to expose the /proxy/all endpoint. Refer to the section on returning all toggles for more info.
    corsn/an/anoPass custom options for CORS module
    cors.allowedHeadersCORS_ALLOWED_HEADERSn/anoHeaders to allow for CORS
    cors.credentialsCORS_CREDENTIALSfalsenoAllow credentials in CORS requests
    cors.exposedHeadersCORS_EXPOSED_HEADERS"ETag"noHeaders to expose for CORS
    cors.maxAgeCORS_MAX_AGE172800noMaximum number of seconds to cache CORS results
    cors.methodsCORS_METHODS"GET, POST"noMethods to allow for CORS
    cors.optionsSuccessStatusCORS_OPTIONS_SUCCESS_STATUS204noIf the Options call passes CORS, which http status to return
    cors.originCORS_ORIGIN*noOrigin URL or list of comma separated list of URLs to whitelist for CORS
    cors.preflightContinueCORS_PREFLIGHT_CONTINUEfalseno
    httpOptions.rejectUnauthorizedHTTP_OPTIONS_REJECT_UNAUTHORIZEDtruenoIf true, unleash-proxy will automatically reject connections to unleash server with invalid certificates

    Experimental configuration options​

    Some functionality is under validation and introduced as experimental. This allows us to test new functionality early and quickly. Experimental options can change or be removed at any point in the future and are explicitly not part of the proxy's semantic versioning.

    OptionEnvironment VariableDefault valueRequiredDescription
    expBootstrapn/an/anoWhere the Proxy can bootstrap configuration from. See Node.js SDK for details.
    expBootstrap.urlEXP_BOOTSTRAP_URLn/anoUrl where the Proxy can bootstrap configuration from. See Node.js SDK for details.
    expBootstrap.urlHeaders.AuthorizationEXP_BOOTSTRAP_AUTHORIZATIONn/anoAuthorization header value to be used when bootstrapping
    expServerSideSdkConfig.tokensEXP_SERVER_SIDE_SDK_CONFIG_TOKENSn/anoAPI tokens that can be used by Server SDKs (and proxies) to read feature toggle configuration from this Proxy instance.
    OptionEnvironment VariableDefault valueRequiredDescription
    expBootstrapn/an/anoWhere the Proxy can bootstrap configuration from. See Node.js SDK for details.
    expBootstrap.urlEXP_BOOTSTRAP_URLn/anoUrl where the Proxy can bootstrap configuration from. See Node.js SDK for details.
    expBootstrap.urlHeaders.AuthorizationEXP_BOOTSTRAP_AUTHORIZATIONn/anoAuthorization header value to be used when bootstrapping
    expServerSideSdkConfig.tokensEXP_SERVER_SIDE_SDK_CONFIG_TOKENSn/anoAPI tokens that can be used by Server SDKs (and proxies) to read feature toggle configuration from this Proxy instance.
    expCustomEnrichersEXP_CUSTOM_ENRICHERS_FILE[]noUse this option to inject implementation of custom context enrichers. If you are using EXP_CUSTOM_ENRICHERS_FILE you need to provide a valid path to a javascript file which exports an array of custom context enrichers and the SDK will automatically load these

    Internal SDK capabilities​

    The proxy uses the Node.js SDK internally. When you start the proxy it initializes a client for you using any configuration option you provided on startup. You can also provide your own client.

    The client that the proxy uses supports all the SDK features that the Node.js SDK supports, as listed in the Unleash server-side compatibility overview. The proxy has supported advanced strategy constraints since version 0.8. Because the proxy uses the Node SDK internally,

    Run The Unleash Proxy​

    The Unleash proxy is a small stateless HTTP application you run. The only requirement is that it needs to be able to talk with the Unleash API (either Unleash OSS or Unleash Hosted).

    Run with Docker​

    The easies way to run Unleash is via Docker. We have published a docker image on docker hub.

    Step 1: Pull

    docker pull unleashorg/unleash-proxy

    Step 2: Start

    docker run \
       -e UNLEASH_PROXY_CLIENT_KEYS=some-secret \
       -e UNLEASH_URL=https://app.unleash-hosted.com/demo/api/ \
       -e UNLEASH_API_TOKEN=56907a2fa53c1d16101d509a10b78e36190b0f918d9f122d \
       -p 3000:3000 \
       unleashorg/unleash-proxy

    You should see the following output:

    Unleash-proxy is listening on port 3000!

    Step 3: verify

    In order to verify the proxy you can use curl and see that you get a few evaluated feature toggles back:

    curl http://localhost:3000/proxy -H "Authorization: some-secret"

    Expected output would be something like:

    {
      "toggles": [
        {
          "name": "demo",
          "enabled": true,
          "variant": {
            "name": "disabled",
            "enabled": false
          }
        },
        {
          "name": "demoApp.step1",
          "enabled": true,
          "variant": {
            "name": "disabled",
            "enabled": false
          }
        }
      ]
    }

    Health endpoint

    The proxy will try to synchronize with the Unleash API at startup, until it has successfully done that the proxy will return HTTP 503 - Not Read? for all request. You can use the health endpoint to validate that the proxy is ready to recieve requests:

    curl http://localhost:3000/proxy/health -I
    HTTP/1.1 200 OK
    Access-Control-Allow-Origin: *
    Access-Control-Expose-Headers: ETag
    Content-Type: text/html; charset=utf-8
    Content-Length: 2
    ETag: W/"2-eoX0dku9ba8cNUXvu/DyeabcC+s"
    Date: Fri, 04 Jun 2021 10:38:27 GMT
    Connection: keep-alive
    Keep-Alive: timeout=5

    Run with Node.js:​

    STEP 1: Install dependency

    npm install @unleash/proxy

    STEP 2: use in your code

    const port = 3000;

    const { createApp } = require('@unleash/proxy');

    const app = createApp({
      unleashUrl: 'https://app.unleash-hosted.com/demo/api/',
      unleashApiToken: '56907a2fa53c1d16101d509a10b78e36190b0f918d9f122d',
      clientKeys: ['proxy-secret', 'another-proxy-secret', 's1'],
      refreshInterval: 1000,
      // logLevel: 'info',
      // projectName: 'order-team',
      // environment: 'development',
    });

    app.listen(port, () =>
      // eslint-disable-next-line no-console
      console.log(`Unleash Proxy listening on http://localhost:${port}/proxy`),
    );

    How to connect to the Proxy?​

    Unleash offers several different client-side SDKs for a number of use cases, and the community has created even more. These SDKs connect to the proxy and integrate with well with their designated language/framework. They also sync with the proxy at periodic intervals and post usage metrics back to Unleash via the proxy.

    For applications where there is no appropriate client-side SDK or where you simply want to avoid the dependency, you could also get away with using a simple HTTP-client if you just want to get the list of active features.

    The proxy is also ideal fit for serverless functions such as AWS Lambda. In that scenario the proxy can run on a small container near the serverless function, preferably in the same VPC, giving the lambda extremely fast access to feature flags, at a predictable cost.

    Custom activation strategies​

    ℹ️ Limitations for hosted proxies

    Custom activation strategies can not be used with the Unleash-hosted proxy available to Pro and Enterprise customers.

    The Unleash Proxy can load custom activation strategies for client-side SDKs. For a step-by-step guide, refer to the how to use custom strategies guide.

    To load custom strategies, use either of these two options:

    • the customStrategies option: use this if you're running the Unleash Proxy via Node directly.
    • the UNLEASH_CUSTOM_STRATEGIES_FILE environment variable: use this if you're running the proxy as a container.

    Both options take a list of file paths to JavaScript files that export custom strategy implementations.

    Custom activation strategy files format​

    Each strategy file must export a list of instantiated strategies. A file can export as many strategies as you'd like.

    Here's an example file that exports two custom strategies:

    const { Strategy } = require('unleash-client');

    class MyCustomStrategy extends Strategy {
      // ... strategy implementation
    }

    class MyOtherCustomStrategy extends Strategy {
      // ... strategy implementation
    }

    // export strategies
    module.exports = [new MyCustomStrategy(), new MyOtherCustomStrategy()];

    Refer the custom activation strategy documentation for more details on how to implement a custom activation strategy.

    This content was generated on

    + \ No newline at end of file diff --git a/reference/whats-new-v4.html b/reference/whats-new-v4.html index 78a593aa7a..da86dfaf99 100644 --- a/reference/whats-new-v4.html +++ b/reference/whats-new-v4.html @@ -20,7 +20,7 @@ - + @@ -29,7 +29,7 @@
    Skip to main content

    What's new in v4?

    Version 4 of Unleash brings a lot of improvements to Unleash. In this document we will highlight some of the things that has been added.

    Upgrade with ease​

    Unleash can either be hosted by us or self-hosted. If you have a managed Unleash Enterprise instance you are automatically upgraded to version 4. If you manage Unleash yourself (either Open-Source or Enterprise Self-hosted) we recommend reading the migration guide.

    PS! The first time you access Unleash v4 from a self-hosted instance you will need to login with the default admin user:

    • username: admin
    • password: unleash4all

    (We recommend changing the password of the default user from the admin section.)

    Role-Based Access Control​

    With Role-Based Access Control you can now assign groups to users in order to control access. You can control access to root resources in addition to controlling access to projects. Please be aware that all existing users will become "Owner" of all existing projects as part of the migration from v3 to v4.

    Read more

    New Integrations​

    Integrations make it easy to integrate Unleash with other systems. In version 4 we bring two new integrations to Unleash:

    Improved UX​

    Unleash v4 includes a new implementation of the frontend based on Material-ui. This will make it much easier for us to improve the Unleash Admin UI and our ambition is to make it intuitive to use even for non-developers. The improved UX is made available in Unleash Open-Source and Unleash Enterprise.

    New SSO Option​

    In version 4 we added support for OpenID Connect as part of the Unleash Enterprise offering. OpenID Connect is a simple identity layer on top of the OAuth 2.0 protocol. It allows Clients to verify the identity of the End-User based on the authentication performed by an Authorization Server, as well as to obtain basic profile information about the End-User in an interoperable and REST-like manner.

    User Management​

    In version 4 we improved the User Management and made it available for Unleash Open-Source and Unleash Enterprise. Starting in v4 all users accessing Unleash needs to exist in Unleash in order to gain access (because they need to have the proper permission from RBAC.)

    Read more

    API access​

    In version 4 we improved the API Access and made it available for Unleash Open-Source and Unleash Enterprise. Starting from Unleash v4 we require all SDKs to use an access token in order to connect to Unleash.

    Read more

    Custom stickiness​

    In Unleash Enterprise v4 you can configure stickiness when you are doing a gradual rollout with the "gradual rollout" strategy (previously known as "flexible rollout") or together with feature toggle variants. This means that you can now have consistent behavior based on any field available on the Unleash context.

    - + \ No newline at end of file diff --git a/search.html b/search.html index fea3a467b6..37ee9d7bc0 100644 --- a/search.html +++ b/search.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Search the documentation

    - + \ No newline at end of file diff --git a/topics.html b/topics.html index e644fd21ec..c19cb7121c 100644 --- a/topics.html +++ b/topics.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Feature Flag Best Practices

    Principles and recommendations for best practices of using feature flags.

    - + \ No newline at end of file diff --git a/topics/a-b-testing.html b/topics/a-b-testing.html index 3bef8879c4..283ad0084f 100644 --- a/topics/a-b-testing.html +++ b/topics/a-b-testing.html @@ -20,7 +20,7 @@ - + @@ -32,7 +32,7 @@ It allows you to capture events whenever a feature toggle is checked in your applications. The event contains all the information about the toggle and the current context, so you can pass everything onto your third-party analytics provider, such as Google Analytics or Posthog. This makes Unleash even more useful as an A/B testing tool and makes it much easier to correlate events and variants with feature toggles and Unleash context.

    Summary​

    A/B testing allows you to run experiments on your users and improve your product by using real, proven metrics. It's used by some of the world's most popular businesses and can help you get ahead of competitors (and stay on top). We at Unleash want to help you, so we've baked in some tools to let you do A/B testing right out the gate to make it as smooth as possible to get started.

    So what are you waiting for? Find out what you want to improve next and get testing!

    - + \ No newline at end of file diff --git a/topics/feature-flag-migration/business-case-feature-flag-migration.html b/topics/feature-flag-migration/business-case-feature-flag-migration.html index 8432ec055d..d7fef2b92c 100644 --- a/topics/feature-flag-migration/business-case-feature-flag-migration.html +++ b/topics/feature-flag-migration/business-case-feature-flag-migration.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Make the business case for feature flag migration

    Once you have scoped your migration, you need to make a business case. Even the most well planned migrations take effort, meaning time, money, and energy dedicated to a project. If you don’t have the proper buy-in, you risk being under-resourced or worse, being unable to complete the migration at all.

    When building a business case, you want to be clear on what pain the feature flag migration is solving and the happy end state once the migration is complete.

    To structure your thinking, ask yourself:

    • What practices related to feature deployments, debugging and rollbacks are overburdening teams today and driving down productivity?
    • What specific deficiencies are there in the current platform
    • What business outcomes are you looking to drive?
    • After the migration, what does "better" look like?

    Use our Feature Flag Migration template to fill in details about your business case.

    - + \ No newline at end of file diff --git a/topics/feature-flag-migration/feature-flag-migration-best-practices.html b/topics/feature-flag-migration/feature-flag-migration-best-practices.html index bf2e037a8e..0defb6370d 100644 --- a/topics/feature-flag-migration/feature-flag-migration-best-practices.html +++ b/topics/feature-flag-migration/feature-flag-migration-best-practices.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Best Practices for Migrating from a Homegrown Feature Management Solution

    Many large organizations have an existing feature management solution that they have outgrown and plan to migrate to a feature flag service.

    This guide outlines Best Practices for feature flag migrations. Approaching the migration from your current feature flag solution to Unleash the right way will save you time, money, and a lot of headaches.

    Based on our work with organizations having millions of flags and thousands of users, there are five phases of a feature flag migration:

    1. Defining the scope of the feature flag migration
    2. Make the business case for feature flag migration
    3. Planning Feature Flag Migration
    4. Migration Execution
    5. Onboarding users

    This guide provides a summary of each topic as well as a detailed Feature Flag Migration template that you can use to plan your migration.

    - + \ No newline at end of file diff --git a/topics/feature-flag-migration/feature-flag-migration-scope.html b/topics/feature-flag-migration/feature-flag-migration-scope.html index 829be0209b..f2be720048 100644 --- a/topics/feature-flag-migration/feature-flag-migration-scope.html +++ b/topics/feature-flag-migration/feature-flag-migration-scope.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Defining the scope of the feature flag migration

    Scoping a feature flag migration properly is the most significant task you can do to ensure the success of your project.

    Based on experiences working with dozens of large enterprises migrating homegrown systems to Unleash, we recommend two best practices when scoping your feature flag migration.

    1- Separate the migration of old flags from the existing system from new flags created in Unleash.​

    The older the system, the more existing flags there are. It might take weeks or months to hunt down the developer responsible for an old flag in an obscure part of the code base. In the meantime, hundreds of developers are trying to create new flags today. By separating these concerns, you can get to the "happy end state" for your development team faster, and burn down your flag migrations over time.

    So you should end up with two separate tracks as part of your project scope.

    1. Build the new platform around the "better" target state - ideal use cases and ways of working that enable greater levels of developer efficiency

    In parallel, the second track:

    1. Clean up stale feature flags in the current platform. You should decide strategically on what should be migrated and what should be cleaned up. Many old flags can simply be deleted rather than migrated.

    2- Do not make end-to-end app modernization a dependency of your feature flag migration​

    Organizations who adopt feature flags see improvements in all key operational metrics for DevOps: Lead time to changes, mean-time-to-recovery, deployment frequency, and change failure rate. So it is natural as part of a feature flag migration to also improve other parts of the software development lifecycle. From the perspective of feature flag migration, this is a mistake.

    Making feature flag migration dependent on breaking down mission-critical monolithic applications into microservices, for example, will slow down your feature flag migration.

    Rather, enable feature flags for all codebases, independent of your state of modernization. Even monolithic applications can benefit from feature flags in some instances. When this monolith is broken down, the accrued benefits will be even greater, and you will ship your new feature management system a lot faster.

    Use our Feature Flag Migration template to fill in details about your project scope.

    - + \ No newline at end of file diff --git a/topics/feature-flag-migration/how-to-execute-feature-flag-migration.html b/topics/feature-flag-migration/how-to-execute-feature-flag-migration.html index bbf94f22ba..edc7d70da4 100644 --- a/topics/feature-flag-migration/how-to-execute-feature-flag-migration.html +++ b/topics/feature-flag-migration/how-to-execute-feature-flag-migration.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Migration Execution

    Now that we have completed the planning, below are some of our Best Practices for carrying out the migration based on our experience.

    First, it can help to break the migration down into an order of activities, for example:

    • Minimum Viable Product (MVP) launch
      • Platform implemented, passed security/change management requirements, and available for developer use
      • Rollout to the highest priority groups of users
      • Matching use cases of the legacy platform
      • Legacy system fallback available
    • Medium-term
      • Rollout to additional groups; adoption of further, less critical use cases
      • Sunset of legacy system
    • Longer term
      • Adoption of new use cases

    For each activity, plan for the Level of Effort (LoE), or the number of hours/days the task will take the assigned resource or group to fulfill.

    Next up is risk handling. Are there any perceived risks to the timelines that could be addressed upfront?

    • Have the teams involved with the migration committed to set hours for working the migration tasks upfront, have had migration project success criteria and their tasks communicated to them, and Q&A fulfilled?
    • How long are various sign-offs by any relevant groups expected to take?
      • E.g. Change Advisory Board, Security Controls, hardening checks, etc
      • Plan to exceed each team’s documentation requirements to ensure fewer Requests for Information

    Every step of the way, it can help to conduct reviews and look-backs at each rollout stage as well as what lies ahead.

    Use our Feature Flag Migration template to fill in details about your project plan execution.

    - + \ No newline at end of file diff --git a/topics/feature-flag-migration/onbording-users-to-feature-flag-service.html b/topics/feature-flag-migration/onbording-users-to-feature-flag-service.html index f60ac16602..5a82f90068 100644 --- a/topics/feature-flag-migration/onbording-users-to-feature-flag-service.html +++ b/topics/feature-flag-migration/onbording-users-to-feature-flag-service.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Onboarding users

    Finally, after the migration has been completed and everyone has celebrated, you need to onboard team members onto the platform.

    Unleash Customer Success is here to help, whether your developers are seasoned feature flag management experts or new to the concepts - we will deliver tailored, white-glove training to accommodate use cases and developer skill levels.

    In addition, for those who prefer a self-paced approach, a wealth of content is available on our YouTube channel, website, and documentation portal to get your teams going quickly.

    - + \ No newline at end of file diff --git a/topics/feature-flag-migration/planning-feature-flag-migration.html b/topics/feature-flag-migration/planning-feature-flag-migration.html index a011e0a2fd..2b21ad0306 100644 --- a/topics/feature-flag-migration/planning-feature-flag-migration.html +++ b/topics/feature-flag-migration/planning-feature-flag-migration.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Planning Feature Flag Migration

    When planning your feature flag migration, it is essential to focus on four key areas:

    • Use cases
    • Core feature flag setup
    • Key stakeholders
    • System architecture

    Use Cases​

    A key requirement is to understand how feature flags will be used so that you can set up the proper data model, user permissions, and system architecture.

    Below are some of the most common use cases for feature flags. Start by selecting those that are in scope for your initial rollout. It is common to start with some, but not all, of these and roll out the remaining in the future.

    Use cases for feature flags:

    • Operational or Permission flags (also known as "Kill Switches")
    • Gradual rollouts
    • Canary releases
    • A/B testing / Experimentation

    Core Feature Flag setup

    This planning phase is all about understanding the anatomy of the existing feature flag setup so it can be moved to Unleash.

    Key questions include:

    • How many flags are there?
    • How many are active?
    • Do the inactive flags need to be migrated, or can they be removed entirely, simplifying migration?

    Once you have an understanding of what needs to be migrated, you should plan for how flags will be organized in the future. Picking the right organizing principle is critical for access controls. Unleash supports Application, Project, Environment, and Role-based access, so pick the option that makes the most logical sense for your organization.

    Our experience tells us that organizing flags by the development teams that work on them is the best approach. For example:

    • By application or microservice
      • E.g. Shopping Cart, Website, Mobile app
    • By Projects
      • E.g. Logistics, Finance
    • By organization hierarchy
      • E.g. Frontend, backend, platform teams

    Key stakeholders​

    When planning your migration, it is important to understand who will be managing the feature flag system and who will be using the feature flag system on a day-to-day basis. Additionally, you need to know who will be responsible for key migration tasks.

    From our experience, looping all key stakeholders into the project early on means that all eventualities can be planned for in advance, reducing the risk of project implementation delays due to unforeseen sign-off requirements. Decision makers can help assign and gather resources needed for the migration, as well as advise on the correct business processes that need to be followed at the various project stages.

    System Architecture

    You will also need to plan how you set up Unleash itself as part of your migration planning process. Unleash is extremely flexible with lots of hosting and security configuration options to align with the unique requirements of large enterprises.

    How is our current feature flag architecture set up?​

    This part is key to understanding how Unleash needs to be implemented. This plays a part in resource planning for both personnel and infrastructure cost allocation. For instance

    • What languages and frameworks are our front end and backend using?
    • Where are our applications hosted?
    • Where are end users of the application based geographically?

    Security and organizational policy requirements​

    You will also want to pay attention to Security & Organisational Policy requirements.

    For example, do you need to keep sensitive context inside your firewall perimeter?

    Often the answer to this question defines whether you will run Unleash in a hosted, or self-hosted fashion.

    Many customers prefer a hosted solution if their security policy will allow it because it reduces overhead on SRE teams and infrastructure. Unleash offers a single-tenant hosted solution, so even security-conscious customers can sometimes opt for a hosted solution.

    If that is not an option, Unleash instances need to be managed by customer SRE / DevOps teams. If this is the direction you are going, you should plan for it in this phase of the project.

    Other areas of system architecture to investigate during the planning phase are:

    • Data protection
      • Do we have to comply with HIPPA, SOC-2, ISO 27001, GDPR, etc?
    • How do we authenticate and manage user access & RBAC/roles?
    • Do we have any Change Management policies we need to adhere to?
    • Do we consume feature flag data, such as events, in any other systems downstream?
      • For example, Jira Cloud for issue management, Datadog for real-time telemetry, Slack or Microsoft Teams for notifications or Google Analytics for user interactions.

    Use our Feature Flag Migration template to fill in details about your project planning.

    - + \ No newline at end of file diff --git a/topics/feature-flags/availability-over-consistency.html b/topics/feature-flags/availability-over-consistency.html index 25d2b9ec88..54aeaa9fe3 100644 --- a/topics/feature-flags/availability-over-consistency.html +++ b/topics/feature-flags/availability-over-consistency.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    6. Design for failure. Favor availability over consistency.

    Your feature flag system should not be able to take down your main application under any circumstance, including network disruptions. Follow these patterns to achieve fault tolerance for your feature flag system.

    Zero dependencies: Your application's availability should have zero dependencies on the availability of your feature flag system. Robust feature flag systems avoid relying on real-time flag evaluations because the unavailability of the feature flag system will cause application downtime, outages, degraded performance, or even a complete failure of your application.

    Graceful degradation: If the system goes down, it should not disrupt the user experience or cause unexpected behavior. Feature flagging should gracefully degrade in the absence of the Feature Flag Control service, ensuring that users can continue to use the application without disruption.

    Resilient Architecture Patterns:

    • Bootstrapping SDKs with Data: Feature flagging SDKs used within your application should be designed to work with locally cached data, even when the network connection to the Feature Flag Control service is unavailable. The SDKs can bootstrap with the last known feature flag configuration or default values to ensure uninterrupted functionality.

    • Local Cache: Maintaining a local cache of feature flag configuration helps reduce network round trips and dependency on external services. The local cache can be periodically synchronized with the central Feature Flag Control service when it's available. This approach minimizes the impact of network failures or service downtime on your application.

    • Evaluate Locally: Whenever possible, the SDKs or application components should be able to evaluate feature flags locally without relying on external services. This ensures that feature flag evaluations continue even when the feature flagging service is temporarily unavailable.

    • Availability Over Consistency: As the CAP theorem teaches us, in distributed systems, prioritizing availability over strict consistency can be a crucial design choice. This means that, in the face of network partitions or downtime of external services, your application should favor maintaining its availability rather than enforcing perfectly consistent feature flag configuration caches. Eventually consistent systems can tolerate temporary inconsistencies in flag evaluations without compromising availability. In CAP theorem parlance, a feature flagging system should aim for AP over CP.

    By implementing these resilient architecture patterns, your feature flagging system can continue to function effectively even in the presence of downtime or network disruptions in the feature flagging service. This ensures that your main application remains stable, available, and resilient to potential issues in the feature flagging infrastructure, ultimately leading to a better user experience and improved reliability.

    - + \ No newline at end of file diff --git a/topics/feature-flags/democratize-feature-flag-access.html b/topics/feature-flags/democratize-feature-flag-access.html index 6ccfd8b326..51b4f72af5 100644 --- a/topics/feature-flags/democratize-feature-flag-access.html +++ b/topics/feature-flags/democratize-feature-flag-access.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    9. Choose open by default. Democratize feature flag access.

    Allowing engineers, product owners, and even technical support to have open access to a feature flagging system is essential for effective development, debugging, and decision-making. These groups should have access to the system, along with access to the codebase and visibility into configuration changes:

    1. Debugging and Issue Resolution:

      • Code Access: Engineers should have access to the codebase where feature flags are implemented. This access enables them to quickly diagnose and fix issues related to feature flags when they arise. Without code access, debugging becomes cumbersome, and troubleshooting becomes slower, potentially leading to extended downtimes or performance problems.

    2. Visibility into Configuration:

      • Configuration Transparency: Engineers, product owners, and even technical support should be able to view the feature toggle configuration. This transparency provides insights into which features are currently active, what conditions trigger them, and how they impact the application's behavior. It helps understand the system's state and behavior, which is crucial for making informed decisions.

      • Change History: Access to a history of changes made to feature flags, including who made the changes and when, is invaluable. This audit trail allows teams to track changes to the system's behavior over time. It aids in accountability and can be instrumental in troubleshooting when unexpected behavior arises after a change.

      • Correlating Changes with Metrics: Engineers and product owners often need to correlate feature flag changes with production application metrics. This correlation helps them understand how feature flags affect user behavior, performance, and system health. It's essential for making data-driven decisions about feature rollouts, optimizations, or rollbacks.

    3. Collaboration:

      • Efficient Communication: Open access fosters efficient communication between engineers and the rest of the organization. When it's open by default, everyone can see the feature flagging system and its changes, and have more productive discussions about feature releases, experiments, and their impact on the user experience.

    4. Empowering Product Decisions:

      • Product Owner Involvement: Product owners play a critical role in defining feature flags' behavior and rollout strategies based on user needs and business goals. Allowing them to access the feature flagging system empowers them to make real-time decisions about feature releases, rollbacks, or adjustments without depending solely on engineering resources.

    5. Security and Compliance:

      • Security Audits: Users of a feature flag system should be part of corporate access control groups such as SSO. Sometimes, additional controls are necessary, such as feature flag approvals using the four-eyes principle.

    Access control and visibility into feature flag changes are essential for security and compliance purposes. It helps track and audit who has made changes to the system, which can be crucial in maintaining data integrity and adhering to regulatory requirements.

    - + \ No newline at end of file diff --git a/topics/feature-flags/enable-traceability.html b/topics/feature-flags/enable-traceability.html index 3b29b41c73..62906308ca 100644 --- a/topics/feature-flags/enable-traceability.html +++ b/topics/feature-flags/enable-traceability.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    11. Enable traceability. Make it easy to understand flag evaluation.

    Developer experience is a critical factor to consider when implementing a feature flag solution. A positive developer experience enhances the efficiency of the development process and contributes to the overall success and effectiveness of feature flagging. One crucial aspect of developer experience is ensuring the testability of the SDK and providing tools for developers to understand how and why feature flags are evaluated. This is important because:

    1. Ease of Testing and Debugging:

      • Faster Development Cycles: A feature flagging solution with a testable SDK allows developers to quickly test and iterate on new features. They can easily turn flags on or off, simulate different conditions, and observe the results without needing extensive code changes or redeployments.

      • Rapid Issue Resolution: When issues or unexpected behavior arise, a testable SDK enables developers to pinpoint the problem more efficiently. They can examine the flag configurations, log feature flag decisions, and troubleshoot issues more precisely.

    2. Visibility into Flag Behaviour:

      • Understanding User Experience: Developers need tools to see and understand how feature flags affect the user experience. This visibility helps them gauge the impact of flag changes and make informed decisions about when to roll out features to different user segments. Debugging a feature flag with multiple inputs simultaneously makes it easy for developers to compare the results and quickly figure out how a feature flag evaluates in different scenarios with multiple input values.

      • Enhanced Collaboration: Feature flagging often involves cross-functional teams, including developers, product managers, and QA testers. Providing tools with a clear view of flag behavior fosters effective collaboration and communication among team members.

    3. Transparency and Confidence:

      • Confidence in Flag Decisions: A transparent feature flagging solution empowers developers to make data-driven decisions. They can see why a particular flag evaluates to a certain value, which is crucial for making informed choices about feature rollouts and experimentation.

      • Reduced Risk: When developers clearly understand of why flags evaluate the way they do, they are less likely to make unintentional mistakes that could lead to unexpected issues in production.

    4. Effective Monitoring and Metrics:

      • Tracking Performance: A testable SDK should provide developers with the ability to monitor the performance of feature flags in real time. This includes tracking metrics related to flag evaluations, user engagement, and the impact of flag changes.

      • Data-Driven Decisions: Developers can use this data to evaluate the success of new features, conduct A/B tests, and make informed decisions about optimizations.

      • Usage metrics: A feature flag system should provide insight on an aggregated level about the usage of feature flags. This is helpful for developers so that they can easily assess that everything works as expected.

    5. Documentation and Training:

      • Onboarding and Training: The entire feature flag solution, including API, UI, and the SDKs, requires clear and comprehensive documentation, along with easy-to-understand examples, in order to simplify the onboarding process for new developers. It also supports the ongoing training of new team members, ensuring that everyone can effectively use the feature flagging solution.
    - + \ No newline at end of file diff --git a/topics/feature-flags/evaluate-flags-close-to-user.html b/topics/feature-flags/evaluate-flags-close-to-user.html index bd65c21727..fa8583d2c5 100644 --- a/topics/feature-flags/evaluate-flags-close-to-user.html +++ b/topics/feature-flags/evaluate-flags-close-to-user.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    3. Evaluate flags as close to the user as possible. Reduce latency.

    Feature flags should be evaluated as close to your users as possible, and the evaluation should always happen server side as discussed in Principle 2. In addition to security and privacy benefits, performing evaluation as close as possible to your users has multiple benefits:

    1. Performance Efficiency:

      a. Reduced Latency: Network roundtrips introduce latency, which can slow down your application's response time. Local evaluation eliminates the need for these roundtrips, resulting in faster feature flag decisions. Users will experience a more responsive application, which can be critical for maintaining a positive user experience.

      b. Offline Functionality: Applications often need to function offline or in low-connectivity environments. Local evaluation ensures that feature flags can still be used and decisions can be made without relying on a network connection. This is especially important for mobile apps or services in remote locations.

    2. Cost Savings:

      a. Reduced Bandwidth Costs: Local evaluation reduces the amount of data transferred between your application and the feature flag service. This can lead to significant cost savings, particularly if you have a large user base or high traffic volume.

    3. Offline Development and Testing:

      a. Development and Testing: Local evaluation is crucial for local development and testing environments where a network connection to the feature flag service might not be readily available. Developers can work on feature flag-related code without needing constant access to the service, streamlining the development process.

    4. Resilience:

      a. Service Outages: If the feature flag service experiences downtime or outages, local evaluation allows your application to continue functioning without interruptions. This is important for maintaining service reliability and ensuring your application remains available even when the service is down.

    In summary, this principle emphasizes the importance of optimizing performance while protecting end-user privacy by evaluating feature flags as close to the end user as possible. Done right, this also leads to a highly available feature flag system that scales with your applications.

    - + \ No newline at end of file diff --git a/topics/feature-flags/feature-flag-best-practices.html b/topics/feature-flags/feature-flag-best-practices.html index 16e595ecf8..55d158bb0c 100644 --- a/topics/feature-flags/feature-flag-best-practices.html +++ b/topics/feature-flags/feature-flag-best-practices.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    11 Principles for building and scaling feature flag systems

    Feature flags, sometimes called feature toggles or feature switches, are a software development technique that allows engineering teams to decouple the release of new functionality from software deployments. With feature flags, developers can turn specific features or code segments on or off at runtime, without the need for a code deployment or rollback. Organizations who adopt feature flags see improvements in all key operational metrics for DevOps: Lead time to changes, mean-time-to-recovery, deployment frequency, and change failure rate.

    There are 11 principles for building a large-scale feature flag system. These principles have their roots in distributed systems architecture and pay particular attention to security, privacy, and scale that is required by most enterprise systems. If you follow these principles, your feature flag system is less likely to break under load and will be easier to evolve and maintain.

    These principles are:

    1. Enable run-time control. Control flags dynamically, not using config files.
    2. Never expose PII. Follow the principle of least privilege.
    3. Evaluate flags as close to the user as possible. Reduce latency.
    4. Scale Horizontally. Decouple reading and writing flags.
    5. Limit payloads. Feature flag payload should be as small as possible.
    6. Design for failure. Favor availability over consistency.
    7. Make feature flags short-lived. Do not confuse flags with application configuration.
    8. Use unique names across all applications. Enforce naming conventions.
    9. Choose open by default. Democratize feature flag access.
    10. Do no harm. Prioritize consistent user experience.
    11. Enable traceability. Make it easy to understand flag evaluation

    Background​

    Feature flags have become a central part of the DevOps toolbox along with Git, CI/CD and microservices. You can write modern software without all of these things, but it sure is a lot harder, and a lot less fun.

    And just like the wrong Git repo design can cause interminable headaches, getting the details wrong when first building a feature flag system can be very costly.

    This set of principles for building a large-scale feature management platform is the result of thousands of hours of work building and scaling Unleash, an open-source feature management solution used by thousands of organizations.

    Before Unleash was a community and a company, it was an internal project, started by one dev, for one company. As the community behind Unleash grew, patterns and anti-patterns of large-scale feature flag systems emerged. Our community quickly discovered that these are important principles for anyone who wanted to avoid spending weekends debugging the production system that is supposed to make debugging in production easier.

    “Large scale” means the ability to support millions of flags served to end-users with minimal latency or impact on application uptime or performance. That is the type of system most large enterprises are building today and the type of feature flag system that this guide focuses on.

    Our motivation for writing these principles is to share what we’ve learned building a large-scale feature flag solution with other architects and engineers solving similar challenges. Unleash is open-source, and so are these principles. Have something to contribute? Open a PR or discussion on our Github.

    - + \ No newline at end of file diff --git a/topics/feature-flags/limit-payloads.html b/topics/feature-flags/limit-payloads.html index 18494c0ac5..4aa2f5db7b 100644 --- a/topics/feature-flags/limit-payloads.html +++ b/topics/feature-flags/limit-payloads.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    5. Limit payloads. Feature flag payload should be as small as possible.

    Minimizing the size of feature flag payloads is a critical aspect of maintaining the efficiency and performance of a feature flag system. The configuration of your feature flags can vary in size depending on the complexity of your targeting rules. For instance, if you have a targeting engine that determines whether a feature flag should be active or inactive based on individual user IDs, you might be tempted to include all these user IDs within the configuration payload. While this approach may work fine for a small user base, it can become unwieldy when dealing with a large number of users.

    If you find yourself facing this challenge, your instinct might be to store this extensive user information directly in the feature flagging system. However, this can also run into scaling problems. A more efficient approach is to categorize these users into logical groupings at a different layer and then use these group identifiers when you evaluate flags within your feature flagging system. For example, you can group users based on their subscription plan or geographical location. Find a suitable parameter for grouping users, and employ those group parameters as targeting rules in your feature flagging solution.

    Imposing limitations on payloads is crucial for scaling a feature flag system:

    1. Reduced Network Load:

      • Large payloads, especially for feature flag evaluations, can lead to increased network traffic between the application and the feature flagging service. This can overwhelm the network and cause bottlenecks, leading to slow response times and degraded system performance. Limiting payloads helps reduce the amount of data transferred over the network, alleviating this burden. Even small numbers become large when multiplied by millions.

    2. Faster Evaluation:

      • Smaller payloads reduce latency which means quicker transmission and evaluation. Speed is essential when evaluating feature flags, especially for real-time decisions that impact user experiences. Limiting payloads ensures evaluations occur faster, allowing your application to respond promptly to feature flag changes.

    3. Improved Memory Efficiency:

      • Feature flagging systems often store flag configurations in memory for quick access during runtime. Larger payloads consume more memory, potentially causing memory exhaustion and system crashes. By limiting payloads, you ensure that the system remains memory-efficient, reducing the risk of resource-related issues.

    4. Scalability:

      • Scalability is a critical concern for modern applications, especially those experiencing rapid growth. Feature flagging solutions need to scale horizontally to accommodate increased workloads. Smaller payloads require fewer resources for processing, making it easier to scale your system horizontally.

    5. Lower Infrastructure Costs:

      • When payloads are limited, the infrastructure required to support the feature flagging system can be smaller and less costly. This saves on infrastructure expenses and simplifies the management and maintenance of the system.

    1. Reliability:

      • A feature flagging system that consistently delivers small, manageable payloads is more likely to be reliable. It reduces the risk of network failures, timeouts, and other issues when handling large data transfers. Reliability is paramount for mission-critical applications.

    2. Ease of Monitoring and Debugging:

      • Smaller payloads are easier to monitor and debug. When issues arise, it's simpler to trace problems and identify their root causes when dealing with smaller, more manageable data sets.
    - + \ No newline at end of file diff --git a/topics/feature-flags/never-expose-pii.html b/topics/feature-flags/never-expose-pii.html index 46bb56ab50..da3298a6b8 100644 --- a/topics/feature-flags/never-expose-pii.html +++ b/topics/feature-flags/never-expose-pii.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    2. Never expose PII. Follow the principle of least privilege.

    To keep things simple, you may be tempted to evaluate the feature flags in your Feature Flag Control Service. Don’t. Your Feature Flag Control Service should only handle the configuration for your feature flags and pass this configuration down to SDKs connecting from your applications.

    The primary rationale behind this practice is that feature flags often require contextual data for accurate evaluation. This may include user IDs, email addresses, or geographical locations that influence whether a flag should be toggled on or off. Safeguarding this sensitive information from external exposure is paramount. This information may include Personally Identifiable Information (PII), which must remain confined within the boundaries of your application, following the data security principle of least privilege (PoLP).

    feature-flag-server-side-evaluation

    For client-side applications where the code resides on the user's machine, such as in the browser or on mobile devices, you’ll want to take a different approach. You can’t evaluate on the client side because it raises significant security concerns by exposing potentially sensitive information such as API keys, flag data, and flag configurations. Placing these critical elements on the client side increases the risk of unauthorized access, tampering, or data breaches.

    Instead of performing client-side evaluation, a more secure and maintainable approach is to conduct feature flag evaluation within a self-hosted environment. Doing so can safeguard sensitive elements like API keys and flag configurations from potential client-side exposure. This strategy involves a server-side evaluation of feature flags, where the server makes decisions based on user and application parameters and then securely passes down the evaluated results to the frontend without any configuration leaking.

    feature-flag-architecture-client-side

    Here’s how you can architect your solution to minimize PII or configuration leakage:

    1. Server-Side Components:

    In Principle 1, we proposed a set of architectural principles and components to set up a Feature Flag Control Service. The same architecture patterns apply here, with additional suggestions for achieving local evaluation. Refer to Principle 1 for patterns to set up a feature flagging service.

    Feature Flag Evaluation Service: If you need to use feature flags on the client side, where code is delivered to users' devices, you’ll need an evaluation server that can evaluate feature flags and pass evaluated results down to the SDK in the client application.

    1. SDKs:

    SDKs will make it more comfortable to work with feature flags. Depending on the context of your infrastructure, you need different types of SDKs to talk to your feature flagging service. For the server side, you’ll need SDKs that can talk directly to the feature flagging service and fetch the configuration.

    The server-side SDKs should implement logic to evaluate feature flags based on the configuration received from the Feature Flag Control Service and the application-specific context. Local evaluation ensures that decisions are made quickly without relying on network roundtrips.

    For client-side feature flags, you’ll need a different type of SDK. These SDKs will send the context to the Feature Flag Evaluation Service and receive the evaluated results. These results should be stored in memory and used when doing a feature flag lookup in the client-side application. By keeping the evaluated results for a specific context in memory in the client-side application, you avoid network roundtrips every time your application needs to check the status of a feature flag. It achieves the same level of performance as a server-side SDK, but the content stored in memory is different and limited to evaluated results on the client.

    The benefits of this approach include:

    Privacy Protection:

    a. Data Minimization: By evaluating feature flags in this way, you minimize the amount of data that needs to be sent to the Feature Flag Control Service. This can be crucial for protecting user privacy, as less user-specific data is transmitted over the network.

    b. Reduced Data Exposure: Sensitive information about your users or application's behavior is less likely to be exposed to potential security threats. Data breaches or leaks can be mitigated by limiting the transmission of sensitive data.

    - + \ No newline at end of file diff --git a/topics/feature-flags/prioritize-ux.html b/topics/feature-flags/prioritize-ux.html index aba379ba36..075d85a34b 100644 --- a/topics/feature-flags/prioritize-ux.html +++ b/topics/feature-flags/prioritize-ux.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    10. Do no harm. Prioritize consistent user experience.

    Feature flagging solutions are indispensable tools in modern software development, enabling teams to manage feature releases and experiment with new functionality. However, one aspect that is absolutely non-negotiable in any feature flag solution is the need to ensure a consistent user experience. This isn't a luxury; it's a fundamental requirement. Feature flagging solutions must prioritize consistency and guarantee the same user experience every time, especially with percentage-based gradual rollouts.

    Why Consistency is Paramount:

    1. User Trust: Consistency breeds trust. When users interact with an application, they form expectations about how it behaves. Any sudden deviations can erode trust and lead to a sense of unreliability.

    2. Reduced Friction: Consistency reduces friction. Users shouldn't have to relearn how to use an app every time they open it. A consistent experience reduces the cognitive load on users, enabling them to engage effortlessly.

    3. Quality Assurance: Maintaining a consistent experience makes quality assurance more manageable. It's easier to test and monitor when you have a reliable benchmark for the user experience.

    4. Support and Feedback: Inconsistent experiences lead to confused users, increased support requests, and muddied user feedback. Consistency ensures that user issues are easier to identify and address.

    5. Brand Integrity: A consistent experience reflects positively on your brand. It demonstrates professionalism and commitment to user satisfaction, enhancing your brand's reputation.

    Strategies for Consistency in Percentage-Based Gradual Rollouts:

    1. User Hashing: Assign users to consistent groups using a secure hashing algorithm based on unique identifiers like user IDs or emails. This ensures that the same user consistently falls into the same group.

    2. Segmentation Control: Provide controls within the feature flagging tool to allow developers to segment users logically. For instance, segment by location, subscription type, or any relevant criteria to ensure similar user experiences.

    3. Fallback Mechanisms: Include fallback mechanisms in your architecture. If a user encounters issues or inconsistencies, the system can automatically switch them to a stable version or feature state.

    4. Logging and Monitoring: Implement robust logging and monitoring. Continuously track which users are in which groups and what version of the feature they are experiencing. Monitor for anomalies or deviations and consider building automated processes to disable features that may be misbehaving.

    5. Transparent Communication: Clearly communicate the gradual rollout to users. Use in-app notifications, tooltips, or changelogs to inform users about changes, ensuring they know what to expect.

    In summary, consistency is a cornerstone of effective feature flagging solutions. When designing an architecture for percentage-based gradual rollouts, prioritize mechanisms that guarantee the same user gets the same experience every time. This isn't just about good software practice; it's about respecting your users and upholding their trust in your application. By implementing these strategies, you can create a feature flagging solution that empowers your development process and delights your users with a dependable and consistent experience.

    - + \ No newline at end of file diff --git a/topics/feature-flags/runtime-control.html b/topics/feature-flags/runtime-control.html index 44a15aa966..c4ab468415 100644 --- a/topics/feature-flags/runtime-control.html +++ b/topics/feature-flags/runtime-control.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    1. Enable run-time control. Control flags dynamically, not using config files.

    A scalable feature management system evaluates flags at runtime. Flags are dynamic, not static. If you need to restart your application to turn on a flag, you are using configuration, not feature flags.

    A large-scale feature flag system that enables runtime control should have at minimum the following components:

    1. Feature Flag Control Service: Use a centralized feature flag service that acts as the control plane for your feature flags. This service will handle flag configuration. The scope of this service should reflect the boundaries of your organization.

    Independent business units or product lines should potentially have their own instances, while business units or product lines that work closely together should most likely use the same instance in order to facilitate collaboration. This will always be a contextual decision based on your organization and how you organize the work, but keep in mind that you’d like to keep the management of the flags as simple as possible to avoid the complexity of cross-instance synchronization of feature flag configuration.

    2. Database or Data Store: Use a robust and scalable database or data store to store feature flag configurations. Popular choices include SQL or NoSQL databases or key-value stores. Ensure that this store is highly available and reliable.

    3. API Layer: Develop an API layer that exposes endpoints for your application to interact with the Feature Flag Control Service. This API should allow your application to request feature flag configurations.

    4. Feature Flag SDK: Build or integrate a feature flag SDK into your application. This SDK should provide an easy-to-use interface for fetching flag configurations and evaluating feature flags at runtime. When evaluating feature flags in your application, the call to the SDK should query the local cache, and the SDK should ask the central service for updates in the background.

    Build SDK bindings for each relevant language in your organization. Make sure that the SDKs uphold a standard contract governed by a set of feature flag client specifications that documents what functionality each SDK should support.

    feature-flag-scalable-architecture

    5. Continuously Updated: Implement update mechanisms in your application so that changes to feature flag configurations are reflected without requiring application restarts or redeployments. The SDK should handle subscriptions or polling to the feature flag service for updates.

    - + \ No newline at end of file diff --git a/topics/feature-flags/scale-horizontally.html b/topics/feature-flags/scale-horizontally.html index b479d050fe..bd1e74aae8 100644 --- a/topics/feature-flags/scale-horizontally.html +++ b/topics/feature-flags/scale-horizontally.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    4. Scale Horizontally. Decouple reading and writing flags.

    Separating the reading and writing of feature flags into distinct APIs is a critical architectural decision for building a scalable and efficient feature flag system, particularly when considering horizontal scaling. This separation provides several benefits:

    feature-flag-horizontal-scaling

    1. Horizontal Scaling:

      • By separating read and write APIs, you can horizontally scale each component independently. This enables you to add more servers or containers to handle increased traffic for reading feature flags, writing updates, or both, depending on the demand.

    2. Caching Efficiency:

      • Feature flag systems often rely on caching to improve response times for flag evaluations. Separating read and write APIs allows you to optimize caching strategies independently. For example, you can cache read operations more aggressively to minimize latency during flag evaluations while still ensuring that write operations maintain consistency across the system.

    3. Granular Access Control:

      • Separation of read and write APIs simplifies access control and permissions management. You can apply different security measures and access controls to the two APIs. This helps ensure that only authorized users or systems can modify feature flags, reducing the risk of accidental or unauthorized changes.

    4. Better Monitoring and Troubleshooting:

      • Monitoring and troubleshooting become more straightforward when read and write operations are separated. It's easier to track and analyze the performance of each API independently. When issues arise, you can isolate the source of the problem more quickly and apply targeted fixes or optimizations.

    5. Flexibility and Maintenance:

      • Separation of concerns makes your system more flexible and maintainable. Changes or updates to one API won't directly impact the other, reducing the risk of unintended consequences. This separation allows development teams to work on each API separately, facilitating parallel development and deployment cycles.

    6. Load Balancing:

      • Load balancing strategies can be tailored to the specific needs of the read and write APIs. You can distribute traffic and resources accordingly to optimize performance and ensure that neither API becomes a bottleneck under heavy loads.
    - + \ No newline at end of file diff --git a/topics/feature-flags/short-lived-feature-flags.html b/topics/feature-flags/short-lived-feature-flags.html index 26a3fe886d..c6e6c9140c 100644 --- a/topics/feature-flags/short-lived-feature-flags.html +++ b/topics/feature-flags/short-lived-feature-flags.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    7. Make feature flags short-lived. Do not confuse flags with application configuration.

    Feature flags have a lifecycle shorter than an application lifecycle. The most common use case for feature flags is to protect new functionality. That means that when the roll-out of new functionality is complete, the feature flag should be removed from the code and archived. If there were old code paths that the new functionality replaces, those should also be cleaned up and removed.

    Feature flags should not be used for static application configuration. Application configuration is expected to be consistent, long-lived, and read when launching an application. Using feature flags to configure an application can lead to inconsistencies between different instances of the same application. Feature flags, on the other hand, are designed to be short-lived, dynamic, and changed at runtime. They are expected to be read and updated at runtime and favor availability over consistency.

    To succeed with feature flags in a large organization, you should:

    • Use flag expiration dates: By setting expiration dates for your feature flags, you make it easier to keep track of old feature flags that are no longer needed. A proper feature flag solution will inform you about potentially expired flags.

    • Treat feature flags like technical debt.: You must plan to clean up old feature branches in sprint or project planning, the same way you plan to clean up technical debt in your code. Feature flags add complexity to your code. You’ll need to know what code paths the feature flag enables, and while the feature flag lives, the context of it needs to be maintained and known within the organization. If you don’t clean up feature flags, eventually, you may lose the context surrounding it if enough time passes and/or personnel changes happen. As time passes, you will find it hard to remove flags, or to operate them effectively.

    • Archive old flags: Feature flags that are no longer in use should be archived after their usage has been removed from the codebase. The archive serves as an important audit log of feature flags that are no longer in use, and allows you to revive them if you need to install an older version of your application.

    There are valid exceptions to short-lived feature flags. In general, you should try to limit the amount of long-lived feature flags. Some examples include:

    • Kill-switches - these work like an inverted feature flag and are used to gracefully disable part of a system with known weak spots.
    • Internal flags used to enable additional debugging, tracing, and metrics at runtime, which are too costly to run all the time. These can be enabled by software engineers while debugging issues.
    - + \ No newline at end of file diff --git a/topics/feature-flags/unique-names.html b/topics/feature-flags/unique-names.html index 3be989f7eb..b3a7cdb67a 100644 --- a/topics/feature-flags/unique-names.html +++ b/topics/feature-flags/unique-names.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    8. Use unique names across all applications. Enforce naming conventions.

    All flags served by the same Feature Flag Control service should have unique names across the entire cluster to avoid inconsistencies and errors.

    • Avoid zombies: Uniqueness should be controlled using a global list of feature flag names. This prevents the reuse of old flag names to protect new features. Using old names can lead to accidental exposure of old features, still protected with the same feature flag name.
    • Naming convention enforcement: Ideally, unique names are enforced at creation time. In a large organization, it is impossible for all developers to know all flags used. Enforcing a naming convention makes naming easier, ensures consistency, and provides an easy way to check for uniqueness.

    Unique naming has the following advantages:

    • Flexibility over time: Large enterprise systems are not static. Over time, monoliths are split into microservices, microservices are merged into larger microservices, and applications change responsibility. This means that the way flags are grouped will change over time, and a unique name for the entire organization ensures that you keep the option to reorganize your flags to match the changing needs of your organization.
    • Prevent conflicts: If two applications use the same Feature Flag name it can be impossible to know which flag is controlling which applications. This can lead to accidentally flipping the wrong flag, even if they are separated into different namespaces (projects, workspaces etc).
    • Easier to manage: It's easier to know what a flag is used for and where it is being used when it has a unique name. E.g. It will be easier to search across multiple code bases to find references for a feature flag when it has a unique identifier across the entire organization.
    • Enables collaboration: When a feature flag has a unique name in the organization, it simplifies collaboration across teams, products and applications. It ensures that we all talk about the same feature.
    - + \ No newline at end of file diff --git a/understanding-unleash.html b/understanding-unleash.html index faf6ca3658..460951ff68 100644 --- a/understanding-unleash.html +++ b/understanding-unleash.html @@ -20,15 +20,15 @@ - +
    -
    Skip to main content

    Understanding Unleash

    Documentation on how Unleash works, high-level architecture and important concepts.

    📄️ Unleash introductory overview

    One of the most important aspects of the architecture to understand is that feature toggles are evaluated in a client SDKs which runs as part of your application. This makes toggle evaluations super-fast (we're talking nano-seconds), scalable and resilient against network disturbances. In order to achieve this Unleash compromises a small update-delay when you change your toggle configurations until it is fully propagated to your application (in terms of seconds and is configurable).

    - +
    Skip to main content

    Understanding Unleash

    Documentation on how Unleash works, high-level architecture and important concepts.

    📄️ Unleash introductory overview

    One of the most important aspects of the architecture to understand is that feature toggles are evaluated in client SDKs which runs as part of your application. This makes toggle evaluations super-fast (we're talking nano-seconds), scalable and resilient against network disturbances. In order to achieve this Unleash incurs a small update-delay when you change your toggle configurations until it is fully propagated to your application (in terms of seconds and is configurable).

    + \ No newline at end of file diff --git a/understanding-unleash/data-collection.html b/understanding-unleash/data-collection.html index c8b9d7e270..2db79f5d5d 100644 --- a/understanding-unleash/data-collection.html +++ b/understanding-unleash/data-collection.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Data collection

    info

    At Unleash, we prioritize the privacy and security of our users' data. This document provides an overview of the data collected when running Unleash. We explain the purpose of data collection and provide instructions on managing data collection settings.

    What data is collected​

    When running Unleash, we collect the following data:

    Version and Instance ID: A unique identifier and version for your Unleash instance. This ID allows us to track usage statistics and measure the adoption of Unleash across different installations and helps us ensure that you're using the latest version with the most up-to-date features and security enhancements.

    Feature Usage Data: Starting from Unleash 5.3, we collect additional data related to feature usage in Unleash.

    This includes the following data points:

    • The number of active feature toggles in use
    • The total number of users in the system
    • The total number of projects in the system
    • The number of custom context fields defined and in use
    • The number of user groups defined in the system
    • The number of custom roles defined in the system
    • The number of environments defined in the system
    • The number of segments in active use by feature toggles
    • The number of custom strategies defined and in use
    • The number of feature exports/imports made

    Please note that all collected data is anonymous, and we only collect usage counts. This data helps us understand how features are used in Unleash, enabling us to prioritize important features and make informed decisions about deprecating features that are no longer relevant to our users.

    Please note that we do not collect personally identifiable information (PII) through Unleash.

    Managing data collection settings​

    We understand that privacy preferences may vary among our users. While the data collected by Unleash is limited and anonymous, we provide options to manage data collection settings:

    Disabling All Telemetry: If you have previously disabled the version telemetry by setting the environment variable CHECK_VERSION to anything other than "true", "t" or "1" both the version telemetry and the feature telemetry will be disabled. This respects your choice to opt out of all telemetry data if you had previously disabled it.

    Turning Off Feature Telemetry: To disable the collection of the new telemetry data while still allowing the version telemetry, set the environment variable SEND_TELEMETRY to anything other than "true", "t" or "1" before starting Unleash. This will ensure that the new telemetry data is not sent, but the version information is still sent.

    We respect your privacy choices, and we will continue to honor your decision regarding telemetry. If you have any questions or concerns about managing data collection settings or privacy, please reach out to our support team for assistance.

    - + \ No newline at end of file diff --git a/understanding-unleash/managing-constraints.html b/understanding-unleash/managing-constraints.html index 69a9fdc426..8e4b48dfd2 100644 --- a/understanding-unleash/managing-constraints.html +++ b/understanding-unleash/managing-constraints.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Managing constraints

    info

    In this explanatory guide, we will discuss how best to deal with large and complex constraints, such as when you want to constrain a feature to a list of 150 user IDs.

    Unleash offers several ways to limit feature exposure to a specified audience, such as the User IDs strategy, strategy constraints, and segments. Each of these options make it easy to add some sort of user identifier to the list of users who should get access to a feature.

    Because of their availability and ease of use with smaller lists, it can be tempting to just keep adding identifiers to those lists. However, once you start approaching a hundred elements, we recommend that you find another way to manage these IDs. In fact, it's probably better to stop well before you get that far.

    The rest of this document explains why this is generally a bad idea and how we suggest you solve your problems instead. However, as always there are exceptional cases where this is the solution.

    How large is too large? How complex is too complex? It depends. However, smaller and simpler is generally better.

    The cost of data​

    First, let's talk a bit about Unleash's architecture: Your Unleash instance is where you define all your features, their strategies, and constraints (and a lot more). However, the Unleash instance itself does not do any of the feature evaluation1. That responsibility is delegated to the Unleash SDKs (or Edge / the Unleash proxy).

    For the SDKs (Edge/proxy included) to evaluate a feature, it needs to know everything about that feature in a specific environment. This includes all strategies and their constraints. This means that the Unleash instance must transmit all information about this feature (and all other features) as a response to an API call.

    As the number of elements in a constraint list (such as number of unique user IDs) grows, so does the size of the HTTP response from the Unleash instance. More data to transmit, means more bandwidth used and longer response times. More data to parse (on the SDK side) means more time spent processing and more data to store and look up on the client.

    To fetch feature configuration, Unleash SDKs run a polling loop in the background. With normal-sized configurations this isn't an issue, but as you add more and more complex constraints, this can eventually overload your network and slow down your SDK. And the more SDKs that connect to your Unleash instance, the worse the problem gets.

    In other words: it's not good.

    Rethinking your options​

    Okay, so putting all these IDs in Unleash isn't good. But how do you manage features for these 124 special cases you have?

    The first thing to think about would be whether you can group these special cases in some way. Maybe you already have an Unleash context field that covers the same amount of users. In that case, you can constrain on that instead. If you don't have a context field that matches these users, then you might need to create one.

    Further, if you have a lot of special cases and require complex constraint logic to model it correctly, this probably reflects some logic that is specific to your domain. It's also likely that this same logic is used elsewhere in your system external to Unleash. Modeling this logic in multiple places can quickly lead to breakage, and we recommend having a single source of truth for cases like this.

    Say, for instance that you have a VIP program where only your top 100 customers get access, and you want to use Unleash to manage access to these exclusive features. In that case, you probably have that list of 100 customers stored outside of Unleash (and if you don't, you definitely should: Unleash is not a data store). To solve this without using a constraint with 100 customer IDs, you could add a cusomerType field to the Unleash context, and only expose the features to users whose customerType is VIP.

    The external storage trick​

    Continuing the customerType example above, how would you resolve a user's customerType in your application?

    If you have customers, then you need to store those customers' data somewhere. This is usually in a database. In some cases, you might already have all the information you need available when you first get the customer information (when they log in). If that's the case, you should be able to take the necessary info and populate the Unleash context with it directly.

    But what if it's more ephemeral or what if it's not available together with the customer data directly? Maybe it's something that changes dynamically?

    An option is to set up an external data store that handles this information specifically. As an example, consider a Redis instance that has a list of VIP customers. You could have an application connect to it and receive the latest state of VIP customers whenever you check a feature with Unleash. For an example of this, check out the Unleash and Redis example.

    Why doesn't Unleash support complex constraint setups out the box?​

    The Unleash SDKs are designed to fast and unobtrusive. This means that resolving a large set of constraints at runtime results in one of two problems: either the SDK needs to resolve very large amounts of data, which can put pressure on your network or it needs to make a potentially slow network call to resolve the segment. Both of these are undesirable for the health of your application.

    1. Well, except for in the case of the front-end API. But even then, the size of the data to transmit matters.↩
    - + \ No newline at end of file diff --git a/understanding-unleash/proxy-hosting.html b/understanding-unleash/proxy-hosting.html index e1022cc88a..0a3063ba90 100644 --- a/understanding-unleash/proxy-hosting.html +++ b/understanding-unleash/proxy-hosting.html @@ -20,7 +20,7 @@ - + @@ -33,7 +33,7 @@ Client API: For backend SDKs, Edge returns entire toggle payload for scope of token (project/environment)

    Start Edge & populate toggle cache

    docker run -p 3063:3063 -e TOKENS='CLIENT_API_TOKEN' -e UPSTREAM_URL='UPSTREAM_URL' unleashorg/unleash-edge:v8.1 edge

    The following can be used to pass new tokens to Edge for different project/environment scopes:

    curl --location --request GET 'http://0.0.0.0:3063/api/client/features' \ --header 'Content-Type: application/json' \ --header 'Authorization: NEW_TOKEN' \ --data-raw ''

    On SDKs​

    You host everything​

    Availability

    This setup is only available open-source and Enterprise customers.

    An architecture diagram of using the proxy in a single-region, self-hosted setup.

    You host everything yourself. Everything runs where and how you configure it to.

    To configure Edge and the SDKs, follow steps in the previous section on Unleash hosts the API, you host Edge

    As you might expect, doing everything yourself is going to give you the most flexibility, but it's also going to be the most work. If you're already hosting Unleash yourself, though, this shouldn't be any more difficult than the previous section.

    As described in the section on tradeoffs between self-hosted and Unleash-hosted setups, running Edge yourself gives you a number of benefits.

    Multi-region​

    An architecture diagram of using the proxy in a multi-region, self-hosted setup.

    You can also use Edge for a multi-region setup. You can run Edge in a different region to the API and still connect to the API. Because Edge runs closer to your applications it still provides you benefits in terms of quicker response times. Everything should be configured as described in the you host everything section or the Unleash hosts the API, you host Edge section. You can add as many Edge instances in as many extra regions as you want.

    Legacy: Unleash hosts the API, you host the Proxy​

    Recommendation

    This approach is no longer recommended. You should use Unleash Edge instead of the Unleash proxy. If you are an existing Proxy user, see our Edge migration guide for a guide on how to migrate. Please take note of the section covering features Edge does not currently support in the same linked document before planning a migration.

    Availability

    This setup is only available to Pro and Enterprise customers.

    An architecture diagram of using the proxy in a setup where Unleash hosts the API and you host the proxy.

    You host the proxy yourself. It runs in a standalone container alongside your other applications in your cloud or hosting setup. Unleash manages the Unleash API, the admin UI, and the backing database in our AWS setup: the API and the UI run together in a Kubernetes deployment and connect to an Amazon RDS database.

    You'll need to configure the proxy and the proxy client SDKs.

    For the proxy, configure:

    For the proxy client SDK, configure:

    This setup requires a little more setup on your part than the Unleash-hosted proxy does, but it offers all the benefits described in the section on tradeoffs between self-hosted and Unleash-hosted setups.

    - + \ No newline at end of file diff --git a/understanding-unleash/the-anatomy-of-unleash.html b/understanding-unleash/the-anatomy-of-unleash.html index b665d589c2..02d7782d05 100644 --- a/understanding-unleash/the-anatomy-of-unleash.html +++ b/understanding-unleash/the-anatomy-of-unleash.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    The Anatomy of Unleash

    This guide's purpose is to give you a conceptual overview of how Unleash works. It covers the various components that exist within an Unleash system and how they interact with each other and with external applications. The diagrams are intended to help you understand the fundamental building blocks, such as projects, environments, variants and, of course, feature toggles.

    The end of this guide presents a short use case, explaining how you might configure Unleash to start working with feature toggles.

    The root level​

    Some things in Unleash are configured and defined on the root level. These options apply across the entire Unleash instance. The most important root configuration options for day-to-day operations are:

    Projects​

    Projects contain feature toggles and their configurations, and a set of active environments.

    All Unleash instances must have at least one project at any given time. New instances get a project called “Default”.

    Pro and Enterprise customers can create, rename, and delete projects as they wish (as long as there is always at least one project). Open-source users, on the other hand, only get access to the Default project.

    A square labeled 'project' containing another square, labeled 'environment'.
    Unleash projects contain one or more environments.

    Environments and project environments​

    Feature toggles can be activated or deactivated independently in different environments. For instance, a feature toggle can be active in the development environment, and deactivated in the production environment. Even if their configuration is otherwise identical, deactivated feature toggles will never be considered enabled.

    Environments in Unleash let you change how a feature toggle works in your application’s different environments. For instance, while you are developing a feature, it’s likely that you’ll want it to be available in your development environment, but not in your production environment: environments let you do that. You might also want to enable a feature for only some users in your development environment, but no users in your production environment: environments let you do that.

    Environments exist on two different levels within Unleash. The set of all available environments is defined on the root level. Additionally, each project can choose which of these root environments should be available on the project level. The set of environments available to any given project is always a subset of the set of all available environments at the root level.

    Each project must always have at least one active environment.

    Enterprise users can create and remove environments. Open-source and Pro customers get access to two environments: development and production.

    Environments are adjacent to feature toggles in Unleash: neither one contains the other, but they come together to let you define activation strategies.

    You can use different activation strategies and constraints in different environments. For instance, you can show a feature only to select user IDs in development, but roll it out to 25% of your user base in production.
    Environments and API keys

    When connecting an SDK to Unleash, it's the API key that decides which environment to fetch features for. For legacy reasons, all Unleash SDKs accept a configuration option called environment, but this does not affect the environment at all. It is an Unleash context field and a holdover from before Unleash had native environments.

    Features (feature toggles)​

    Feature toggles are at the heart of Unleash’s functionality. Feature toggles belong to projects and live next to project environments. In and of itself, a feature toggle doesn’t do anything. You must assign activation strategies to it for it to start taking effect.

    When creating a feature toggle, you must assign a unique (across your Unleash instance) name, a feature toggle type, a project it belongs to, and an optional description. Everything except for the name can be changed later.

    A hierarchy showing a project containing an environment containing a feature toggle configuration.
    Feature toggle states are evaluated independently in each environment.

    Activation strategies​

    A hierarchy displaying an environment containing a feature toggle configuration with an activation strategy.
    Activation strategies are applied to feature toggles on a per-environment basis and decide whether a feature is enabled or not.

    Activation strategies (or just strategies for short) are the part of feature toggles that tell Unleash who should get a feature. An activation strategy is assigned to one feature toggle in one environment.

    When you check a feature toggle in an application, the following decides the result:

    1. Is the toggle active in the current environment? If not, it will be disabled.
    2. If the toggle is active in the current environment, the toggle’s strategies decide the result. As long as at least one of a toggle’s strategies resolve to true for the current context (user or application), then the toggle will be considered enabled. In other words, if you have a hundred strategies and ninety-nine of them resolve to false, but one of them resolves to true, then the toggle is enabled.

    Activation strategies tie feature toggles and environments together. When you assign an activation strategy to a feature toggle, you do so in one environment at a time. You can assign the same strategy to the same toggle in different environments, but they will be different instances of the same strategy, and do not stay in sync. Unleash also lets you copy strategies from one environment to another.

    Unleash comes with a number of strategies built in (refer the activation strategies documentation for more information on those). You can also create your own custom activation strategies if you need them. All strategies can be further augmented by strategy constraints.

    Feature toggles exist across environments and can have different activation strategies in each environment.
    Feature toggle activation strategies can be copied between environments. You can also create new strategies in each environment.

    Strategy constraints​

    Strategy constraints (or just constraints) help you fine-tune your strategies. They are an extra layer of prerequisites that help you narrow the audience of a strategy down. Strategy constraints are applied to activation strategies.

    For example, if you wanted to roll a feature out to 50% of users with a specific email domain (such as “@mycompany.com”), then strategy constraints would let you target only users with that email domain.

    Constraints can also be used for more general purposes, such as timing feature releases or releasing features in specific regions.

    An activation strategy can have as many constraints as you want. When an activation strategy has multiple constraints, then every constraint must be satisfied for the strategy to be evaluated. So if you have two constraints: one that says users must have an “@mycompany.com” email address and one that says users must have signed up for a beta program, then the strategy would only be evaluated for users with @mycompany.com emails that have signed up for the program.

    Strategies and constraints

    Feature toggle strategies are permissive: As long as one strategy resolves to true, the feature is considered enabled. On the other hand, constrains are restrictive: for a given strategy, all constraints must be met for it to resolve to true.

    We can exemplify this difference with the logical operators AND and OR:

    • For a feature toggle, if Strategy1 OR Strategy2 OR .. OR StrategyN is true, then the feature is enabled.
    • For a strategy, it can be evaluated if and only if Constraint1 AND Constraint2 AND .. AND ConstraintN are met.

    Note that even if all the constraints are met, the strategy itself might not resolve to true: that will depend on the strategy and the provided context.

    You can define constraints on whatever properties you want in your Unleash context.

    Constraints are applied to individual strategies and do not stay in sync with each other. When you need to have the same constraints applied to multiple strategies and need those constraints to stay in sync, use segments.

    A hierarchy drawing showing a constraint applied to an activation strategy.
    Constraints can be applied to strategies, allowing you to narrow a feature's audience.

    Segments​

    Segments add extra functionality on top of strategy constraints. A segment is a reusable collection of strategy constraints with a name and an optional description. When you apply a segment to a strategy, the strategy will be evaluated as if all of the segment's constraints were applied to it.

    Segments let you apply a set of constraints to multiple strategies and keep the constraints in sync between those strategies. Whenever you apply a segment to a strategy, you essentially create a reference to that segment. This means that whenever you change the segment by adding, removing, or changing constraints, this change propagates to all the strategies that reference this segment.

    You can apply multiple segments to a strategy. Much like with constraints, every segment needs every constraint to be satisfied for the strategy to be evaluated. If you also have other constraints on the strategy, then those must also be satisfied.

    Segments are only available to Pro and Enterprise users.

    Segments are reusable lists of constraints that can be applied to a strategy instead of or in addition to constraints.

    Variants and feature toggle payloads​

    By default, a feature toggle in Unleash only tells you whether a feature is enabled or disabled, but you can also add more information to your toggles by using feature toggle variants. Variants also allow you to run A/B testing experiments.

    Feature toggles are designed to let you decide which users get access to a feature. Variants are designed to let you decide which version of the feature a user gets access to. For instance, if user A is part of your beta testing program and gets access to a new beta feature, then you can use variants to decide whether they should get the red version or the green version of the feature.

    When you create new variants for a feature, they must be given a name and a weighting indicating how many users should see this particular variant of the feature. They can also be given a payload.

    You can use the variant payload to attach arbitrary data to a variant. Variants can have different kinds of payloads.

    A feature toggle can have as many variants as you want.

    Variants and environments​

    Prior to 4.21, variants were independent of environments. In other words: if you're on 4.19 or lower, you’ll always have the exact same variants with the exact same weightings and the exact same payloads in all environments.

    Before Unleash 4.21, feature toggle variants were the same for all environments.

    As of version 4.21, a feature can have different variants in different environments. For instance, a development environment might have no variants, while a production environment has 2 variants. Payloads, weightings and anything else can also differ between environments.

    From Unleash 4.21 on, a feature toggle can have different in each environment.

    Use case: changing website colors​

    Using the concepts we have looked at in the previous sections, let’s create a hypothetical case and see how Unleash would solve it.

    Problem statement: You have an existing website with a red color scheme, but you’re feeling a bit adventurous and would like to try and see if changing it to a blue color scheme would be better.

    Current state: You have an existing website that gets server-side rendered and you have a newly created instance of Unleash.

    Configuring Unleash for development​

    Assuming you have a brand new Unleash instance, you already have the “Default” project and the “Development” and “Production” environments available. That’s going to be all you need for now.

    First things first, in the Default project, you create a new feature toggle, called “new-color-scheme” (toggle names have to be URL-friendly, so no spaces allowed!).

    Because you’d like to see the new color scheme while you’re developing it, you assign a “standard” strategy to the new-color-scheme toggle in the development environment and turn it on.

    In your application​

    You configure an Unleash SDK for your server to communicate with Unleash. When rendering the page, you check the state of the new-color-scheme feature and render a different stylesheet based on the results.

    In pseudocode (loosely based on the Node.js SDK), that might look like this:

    if (unleash.isEnabled(“new-color-scheme”)) {
      // load stylesheet with new color scheme
    } else {
      // load stylesheet with old color scheme
    }

    And with that, the new color scheme is now live in your development environment. Because there aren’t any strategies defined in the production environment yet, the feature is not active, and everything is as it was.

    Rolling out the feature to users​

    When you’re happy with the new color scheme, you decide to start rolling it out to users. But you want it to go out to only a small number of users at first, so that you can get some feedback while rolling out.

    You decide to add a gradual rollout strategy to the new-color-scheme feature in the production environment. Because you want to start small, you set the rollout percentage to 5%.

    As soon as you enable the production environment, the feature gets rolled out to 5% of your users (assuming you’ve deployed the code to production).

    Adding variants​

    While you were developing the new color scheme, you also dabbled a bit with other colors in addition to blue: green and purple might be nice too! So you decide to create two extra color schemes that you’re happy with. But you’d like to hear what your users think too, so you need to roll it out to them somehow.

    You decide to use feature toggle variants to differentiate between the different themes, creating three variants: blue, green, and purple. You want each of them to roll out to the same number of users, so you leave them equally weighted.


    const theme = unleash.getVariant(“new-color-scheme”).name;

    if (theme === “green”) {
      // load stylesheet with green color scheme
    } else if (theme === “blue”) {
      // load stylesheet with blue color scheme
    } else if (theme === “purple”) {
      // load stylesheet with purple color scheme
    } else {
      // load stylesheet with old color scheme
    }

    Now users that are included in the gradual rollout will get one of the three themes. Users that aren’t included get the old theme.

    - + \ No newline at end of file diff --git a/understanding-unleash/unleash-overview.html b/understanding-unleash/unleash-overview.html index b5fb9b62da..1cce19a4e5 100644 --- a/understanding-unleash/unleash-overview.html +++ b/understanding-unleash/unleash-overview.html @@ -3,7 +3,7 @@ -Unleash introductory overview | Unleash +Unleash introductory overview | Unleash @@ -20,15 +20,15 @@ - +
    -
    Skip to main content

    Unleash introductory overview

    One of the most important aspects of the architecture to understand is that feature toggles are evaluated in a client SDKs which runs as part of your application. This makes toggle evaluations super-fast (we're talking nano-seconds), scalable and resilient against network disturbances. In order to achieve this Unleash compromises a small update-delay when you change your toggle configurations until it is fully propagated to your application (in terms of seconds and is configurable).

    If you want more details you can read about our unique architecture.

    Unleash Server​

    Before you can connect your application to Unleash you need a Unleash server. You have a few options available:

    1. Unleash Open-Source
    2. Unleash Enterprise

    System Overview​

    A visual overview of an Unleash system as described in the following paragraph.

    • The Unleash API - The Unleash instance. This is where you create feature toggles, configure activation strategies, and parameters, etc. The service holding all feature toggles and their configurations. Configurations declare which activation strategies to use and which parameters they should get.
    • The Unleash admin UI - The bundled web interface for interacting with the Unleash instance. Manage toggles, define strategies, look at metrics, and much more. Use the UI to create feature toggles, manage project access roles, create API tokens, and more.
    • Unleash 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
    • The Unleash Edge - The Unleash Edge sits between front-end and native applications and the Unleash API, 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.

    To be super fast (we're talking nano-seconds), the client SDK caches all feature toggles and their current configuration in memory. The activation strategies are also implemented in the SDK. This makes it really fast to check if a toggle is on or off because it is just a simple function operating on local state, without the need to poll data from the database.

    - +
    Skip to main content

    Unleash introductory overview

    One of the most important aspects of the architecture to understand is that feature toggles are evaluated in client SDKs which runs as part of your application. This makes toggle evaluations super-fast (we're talking nano-seconds), scalable and resilient against network disturbances. In order to achieve this Unleash incurs a small update-delay when you change your toggle configurations until it is fully propagated to your application (in terms of seconds and is configurable).

    If you want more details you can read about our unique architecture.

    Unleash Server​

    Before you can connect your application to Unleash you need a Unleash server. You have a few options available:

    1. Unleash Open-Source
    2. Unleash Enterprise

    System Overview​

    A visual overview of an Unleash system as described in the following paragraph.

    • The Unleash API - The Unleash instance. This is where you create feature toggles, configure activation strategies, and parameters, etc. The service holding all feature toggles and their configurations. Configurations declare which activation strategies to use and which parameters they should get.
    • The Unleash admin UI - The bundled web interface for interacting with the Unleash instance. Manage toggles, define strategies, look at metrics, and much more. Use the UI to create feature toggles, manage project access roles, create API tokens, and more.
    • Unleash 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
    • The Unleash Edge - The Unleash Edge sits between front-end and native applications and the Unleash API, 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.

    To be super fast (we're talking nano-seconds), the client SDK caches all feature toggles and their current configuration in memory. The activation strategies are also implemented in the SDK. This makes it really fast to check if a toggle is on or off because it is just a simple function operating on local state, without the need to poll data from the database.

    + \ No newline at end of file diff --git a/unleash-academy/advanced-for-devs.html b/unleash-academy/advanced-for-devs.html index ef267456f6..4ede25f964 100644 --- a/unleash-academy/advanced-for-devs.html +++ b/unleash-academy/advanced-for-devs.html @@ -20,7 +20,7 @@ - + @@ -30,7 +30,7 @@
    Skip to main content

    Advanced for Developers

    info

    This Unleash Academy course is for all developer roles working with Unleash, after Foundational content has been reviewed.

    note

    Estimated time burden: 45 minutes

    Learning Objectives​

    Unlock the full potential of Unleash, streamline your development process and make data-driven decisions with confidence. Learn how Unleash can support your business needs and understand advanced usage like collaboration, data insights and A/B testing, auto-remediation, and integration into third party tools.

    You’ll master advanced use cases and implement best practices - this course will empower you to maximize Unleash's capabilities for your projects.

    Course Detail​

    Embedded Player

    The full course is shown above.
    Click the icon in the top right corner of the embedded player to view your progress as you work through the videos.
    Options to go full screen, view the playlist on YouTube or share are also enabled.

    - + \ No newline at end of file diff --git a/unleash-academy/foundational.html b/unleash-academy/foundational.html index ea9ab23346..854c6a8677 100644 --- a/unleash-academy/foundational.html +++ b/unleash-academy/foundational.html @@ -20,7 +20,7 @@ - + @@ -31,7 +31,7 @@ An understanding of Unleash anatomy and architecture and how the different systems connect together.

    Intro to Feature Flags/Toggles & Unleash

    Anatomy of Unleash

    Architecture overview

    How to use Unleash

    Course Detail​

    Embedded Player

    The full course is shown above.
    Click the icon in the top right corner of the embedded player to view your progress as you work through the videos.
    Options to go full screen, view the playlist on YouTube or share are also enabled.

    - + \ No newline at end of file diff --git a/unleash-academy/introduction.html b/unleash-academy/introduction.html index ac81a48cdd..a00312a1cf 100644 --- a/unleash-academy/introduction.html +++ b/unleash-academy/introduction.html @@ -20,7 +20,7 @@ - + @@ -29,7 +29,7 @@
    Skip to main content

    Unleash Academy

    Introduction​

    Unleash Academy is your go-to portal for complimentary self-paced training materials around the Unleash platform.

    Whether you are new to feature flags or a seasoned feature management user and whatever your organizational role, our materials will help onboard you to the full suite of capabilities the Unleash platform has to offer, refresh your existing knowledge, broaden your knowledge to new use cases, and much more!

    Any Unleash user is welcomed - from Open Source, Pro to Enterprise.

    Content is carefully curated to ensure the best, most relevant targeted learning experience. Review the next section on how to use the content to get started today!

    Learning Paths and How to use this content​

    Content is built around Learning Paths that are based on common user roles and personas using Unleash today. This helps ensure that you maximize value from the time you spend with Unleash Academy by reviewing content that will help you achieve your goals with Unleash.

    1. Start by identifying the persona most closely associated with your day to day responsibilities.
    Example titles are provided for additional guidance:

    • Developer
      • E.g Software Engineer, Software Developer
    • DevOps / Admin
      • Platform Engineer, Site Reliability Engineer, DevOps Engineer, Systems Administrator, Cloud Infrastructure Consultant
    • Product Owner
      • Product Manager, Product Analyst
    • People Leader
      • Manager, Executive
    note

    All roles working with Unleash start with the Foundational training. Then, role dependent courses are offered thereafter.

    2. Now check the course directory or the graphic below to find out which courses apply to your persona!

    Course Directory​

    Directory by Persona​

    1. Foundational (75min)
    2. Advanced for Developers (45min)

    Select the tab that corresponds to your persona. A course list is shown - plan to complete the courses in the displayed order, noting the estimated completion times.

    info

    See also the following visualization of the learning paths

    Course order for Developer, DevOps, Product and Leader personas
    Learning Paths organized by Persona

    Directory by Course​

    - + \ No newline at end of file diff --git a/unleash-academy/managing-unleash-for-devops.html b/unleash-academy/managing-unleash-for-devops.html index f6ccb56b64..f1edc96be8 100644 --- a/unleash-academy/managing-unleash-for-devops.html +++ b/unleash-academy/managing-unleash-for-devops.html @@ -20,7 +20,7 @@ - + @@ -30,7 +30,7 @@
    Skip to main content

    Managing Unleash for DevOps/Admins

    info

    This Unleash Academy course is for all DevOps and Admin roles working with Unleash, after Foundational content has been reviewed.

    note

    Estimated time burden: 45 minutes

    Learning Objectives​

    Understand how to deploy Unleash in a secure and performant manner through Edge, maintain and manage users, groups, permissions, and RBAC.

    Course Detail​

    Embedded Player

    The full course is shown above.
    Click the icon in the top right corner of the embedded player to view your progress as you work through the videos.
    Options to go full screen, view the playlist on YouTube or share are also enabled.

    - + \ No newline at end of file diff --git a/using-unleash.html b/using-unleash.html index e2b601d5d4..6c84a0d442 100644 --- a/using-unleash.html +++ b/using-unleash.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Using Unleash

    Documentation on how to accomplish specific tasks when building with Unleash, including API and SDK documentation.

    - + \ No newline at end of file diff --git a/using-unleash/deploy.html b/using-unleash/deploy.html index 58327b44c8..56a2c8f28f 100644 --- a/using-unleash/deploy.html +++ b/using-unleash/deploy.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Self-Hosting Unleash

    All you need to learn how to deploy and manage your own Unleash instance.

    - + \ No newline at end of file diff --git a/using-unleash/deploy/configuring-unleash-v3.html b/using-unleash/deploy/configuring-unleash-v3.html index 45e7ee88fe..505d723e2f 100644 --- a/using-unleash/deploy/configuring-unleash-v3.html +++ b/using-unleash/deploy/configuring-unleash-v3.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Configuring Unleash v3

    This is the guide on how to configure Unleash v3 self-hosted. If you are using Unleash v4 you should checkout configuring Unleash

    In order to customize "anything" in Unleash you need to use Unleash from Node.js:

    const unleash = require('unleash-server');

    const unleashOptions = {
      db: {
        user: 'unleash_user',
        password: 'passord',
        host: 'localhost',
        port: 5432,
        database: 'unleash',
        ssl: false,
        pool: {
          min: 0,
          max: 4,
          idleTimeoutMillis: 30000,
        },
      },
      enableRequestLogger: true,
    };

    unleash.start(unleashOptions);

    Available Unleash options include:

    • db - The database configuration object taking the following properties:
      • user - the database username (DATABASE_USERNAME)
      • password - the database password (DATABASE_PASSWORD)
      • host - the database hostname (DATABASE_HOST)
      • port - the database port defaults to 5432 (DATABASE_PORT)
      • database - the database name to be used (DATABASE_NAME)
      • ssl - an object describing ssl options, see https://node-postgres.com/features/ssl (DATABASE_SSL, as a stringified json object)
      • version - the postgres database version. Used to connect a non-standard database. Defaults to undefined, which let the underlying adapter to detect the version automatically. (DATABASE_VERSION)
      • pool - an object describing pool options, see https://knexjs.org/guide/#pool. We support the following four fields:
        • min - minimum connections in connections pool (defaults to 0) (DATABASE_POOL_MIN)
        • max - maximum connections in connections pool (defaults to 4) (DATABASE_POOL_MAX)
        • idleTimeoutMillis - time in milliseconds a connection must be idle before being marked as a candidate for eviction (defaults to 30000) (DATABASE_POOL_IDLE_TIMEOUT_MS)
        • afterCreate - a callback for for configuring active connections, see https://knexjs.org/guide/#aftercreate. This is incompatible with the ALLOW_NON_STANDARD_DB_DATES environment variable, which will override this property to support non-standard Postgres date formats. If you've set your Postgres instance to use a date style other than ISO, DMY then you'll need to set the ALLOW_NON_STANDARD_DB_DATES environment variable to true. Setting the environment variable should be preferred over writing your own callback.
    • databaseUrl - (deprecated) the postgres database url to connect to. Only used if db object is not specified, and overrides the db object and any environment variables that change parts of it (like DATABASE_SSL). Should include username/password. This value may also be set via the DATABASE_URL environment variable. Alternatively, if you would like to read the database url from a file, you may set the DATABASE_URL_FILE environment variable with the full file path. The contents of the file must be the database url exactly.
    • databaseSchema - the postgres database schema to use. Defaults to 'public'. (DATABASE_SCHEMA)
    • port - which port the unleash-server should bind to. If port is omitted or is 0, the operating system will assign an arbitrary unused port. Will be ignored if pipe is specified. This value may also be set via the HTTP_PORT environment variable
    • host - which host the unleash-server should bind to. If host is omitted, the server will accept connections on the unspecified IPv6 address (::) when IPv6 is available, or the unspecified IPv4 address (0.0.0.0) otherwise. This value may also be set via the HTTP_HOST environment variable
    • pipe - parameter to identify IPC endpoints. See https://nodejs.org/api/net.html#net_identifying_paths_for_ipc_connections for more details
    • enableLegacyRoutes (boolean) - allows you to turn on/off support for legacy routes to support older clients. Disabled by default. Will be removed in 4.x.
    • serverMetrics (boolean) - use this option to turn on/off prometheus metrics.
    • preHook (function) - this is a hook if you need to provide any middlewares to express before unleash adds any. Express app instance is injected as first argument.
    • preRouterHook (function) - use this to register custom express middlewares before the unleash specific routers are added. This is typically how you would register custom middlewares to handle authentication.
    • adminAuthentication (string) - use this when implementing custom admin authentication securing-unleash. Possible values are:
      • none - will disable authentication altogether
      • unsecure - (default) will use simple cookie based authentication. UI will require the user to specify an email in order to use unleash.
      • custom - use this when you implement your own custom authentication logic.
    • ui (object) - Set of UI specific overrides. You may set the following keys: headerBackground, environment, slogan.
    • getLogger (function) - Used to register a custom log provider.
    • eventHook (function(event, data)) - If provided, this function will be invoked whenever a feature is mutated. The possible values for event are 'feature-created', 'feature-updated', 'feature-archived', 'feature-revived'. The data argument contains information about the mutation. Its fields are type (string) - the event type (same as event); createdBy (string) - the user who performed the mutation; data - the contents of the change. The contents in data differs based on the event type; For 'feature-archived' and 'feature-revived', the only field will be name - the name of the feature. For 'feature-created' and 'feature-updated' the data follows this schema defined in the source code. See an api here.
    • baseUriPath (string) - use to register a base path for all routes on the application. For example /my/unleash/base (note the starting /). Defaults to /. Can also be configured through the environment variable BASE_URI_PATH.
    • unleashUrl (string) - Used to specify the official URL this instance of Unleash can be accessed at for an end user. Can also be configured through the environment variable UNLEASH_URL.
    • secureHeaders (boolean) - use this to enable security headers (HSTS, CSP, etc) when serving Unleash from HTTPS. Can also be configured through the environment variable SECURE_HEADERS.
    • checkVersion - the checkVersion object deciding where to check for latest version
      • url - The url to check version (Defaults to https://version.unleash.run) - Overridable with (UNLEASH_VERSION_URL)
      • enable - Whether version checking is enabled (defaults to true) - Overridable with (CHECK_VERSION) (if anything other than true, does not check)

    Disabling Auto-Start​

    If you're using Unleash as part of a larger express app, you can disable the automatic server start by calling server.create. It takes the same options as server.start, but will not begin listening for connections.

    const unleash = require('unleash-server');
    // ... const app = express();

    unleash
      .create({
        databaseUrl: 'postgres://unleash_user:password@localhost:5432/unleash',
        port: 4242,
      })
      .then((result) => {
        app.use(result.app);
        console.log(`Unleash app generated and attached to parent application`);
      });

    Securing Unleash​

    You can integrate Unleash with your authentication provider (OAuth 2.0). Read more about securing unleash.

    How do I configure the log output?​

    By default, unleash uses log4js to log important information. It is possible to swap out the logger provider (only when using Unleash programmatically). You do this by providing an implementation of the getLogger function as This enables filtering of log levels and easy redirection of output streams.

    function getLogger(name) {
      // do something with the name
      return {
        debug: console.log,
        info: console.log,
        warn: console.log,
        error: console.error,
      };
    }

    The logger interface with its debug, info, warn and error methods expects format string support as seen in debug or the JavaScript console object. Many commonly used logging implementations cover this API, e.g., bunyan, pino or winston.

    Database pooling connection timeouts​

    • Please be aware of the default values of connection pool about idle session handling.
    • If you have a network component which closes idle sessions on tcp layer, please ensure, that the connection pool idleTimeoutMillis setting is lower than the timespan as the network component will close the idle connection.
    - + \ No newline at end of file diff --git a/using-unleash/deploy/configuring-unleash.html b/using-unleash/deploy/configuring-unleash.html index a3fd402fed..433e0a6412 100644 --- a/using-unleash/deploy/configuring-unleash.html +++ b/using-unleash/deploy/configuring-unleash.html @@ -20,7 +20,7 @@ - + @@ -29,7 +29,7 @@
    Skip to main content

    Configuring Unleash

    This is the guide on how to configure Unleash v4 self-hosted. If you are still using Unleash v3 you should checkout configuring Unleash v3

    Must configure​

    Database​

    In order for Unleash server to work, you need a running database and its connection details. See the database configuration section for the available options and configuration details.

    Nice to configure​

    Unleash URL​

    • Configured with UNLEASH_URL Should be set to the public discoverable URL of your instance, so if your instance is accessed by your users at https://unleash.mysite.com use that. If you're deploying this to a subpath, include the subpath in this. So https://mysite.com/unleash will also be correct.
    • Used to create
      • Reset password URLs
      • Welcome link for new users
      • Links in events for our Slack, Microsoft Teams and Datadog integrations

    Email server details​

    Used to send reset-password mails and welcome mails when onboarding new users.
    NOTE - If this is not configured, you will not be able to allow your users to reset their own passwords.

    For more details, see here

    Further customization​

    In order to customize "anything" in Unleash you need to use Unleash from Node.js or start the docker image with environment variables.

    const unleash = require('unleash-server');

    const unleashOptions = {
      db: {
        user: 'unleash_user',
        password: 'password',
        host: 'localhost',
        port: 5432,
        database: 'unleash',
        ssl: false,
        pool: {
          min: 0,
          max: 4,
          idleTimeoutMillis: 30000,
        },
      },
      enableRequestLogger: true,
    };

    unleash.start(unleashOptions);

    Available Unleash options include:

    • authentication - (object) - An object for configuring/implementing custom admin authentication

      • enableApiToken / AUTH_ENABLE_API_TOKEN: boolean — Should unleash require API tokens for access? Defaults to true.

      • type / AUTH_TYPE: string — What kind of authentication to use. Possible values

        • open-source - Sign in with username and password. This is the default value.
        • custom - If implementing your own authentication hook, use this
        • none - Turn off authentication all together
        • demo - Only requires an email to sign in (was default in v3)

      • customAuthHandler: function (app: any, config: IUnleashConfig): void — custom express middleware handling authentication. Used when type is set to custom. Can not be set via environment variables.

      • initialAdminUser: { username: string, password: string} | null — whether to create an admin user with default password - Defaults to using admin and unleash4all as the username and password. Can not be overridden by setting the UNLEASH_DEFAULT_ADMIN_USERNAME and UNLEASH_DEFAULT_ADMIN_PASSWORD environment variables.

        • initApiTokens / INIT_ADMIN_API_TOKENS, INIT_CLIENT_API_TOKENS, and INIT_FRONTEND_API_TOKENS: ApiTokens[] — Array of API tokens to create on startup. The tokens will only be created if the database doesn't already contain any API tokens. Example:
        [
          {
            environment: '*',
            project: '*',
            secret: '*:*.964a287e1b728cb5f4f3e0120df92cb5',
            type: ApiTokenType.ADMIN,
            username: 'some-user',
          },
        ];

        The tokens can be of any API token type. Note that admin tokens must target all environments and projects (i.e. use '*' for environments and project and start the secret with *:*.).

        You can also use the environment variables INIT_ADMIN_API_TOKENS, INIT_CLIENT_API_TOKENS, and INIT_FRONTEND_API_TOKENS. All variables require a comma-separated list of API tokens to initialize (for instance *:*.some-random-string, *:*.some-other-token). The tokens found in INIT_ADMIN_API_TOKENS, INIT_CLIENT_API_TOKENS, and INIT_FRONTEND_API_TOKENS will be created as admin, client, and frontend tokens respectively, and Unleash will assign usernames automatically.

    • databaseUrl - (deprecated) the postgres database url to connect to. Only used if db object is not specified, and overrides the db object and any environment variables that change parts of it (like DATABASE_SSL). Should include username/password. This value may also be set via the DATABASE_URL environment variable. Alternatively, if you would like to read the database url from a file, you may set the DATABASE_URL_FILE environment variable with the full file path. The contents of the file must be the database url exactly.

    • db - The database configuration object. See the database configuration section for a full overview of the available properties.

    • disableLegacyFeaturesApi (boolean) - whether to disable the legacy features API. Defaults to false (DISABLE_LEGACY_FEATURES_API). Introduced in Unleash 4.6.

    • email - the email object configuring an SMTP server for sending welcome mails and password reset mails

      • host - The server URL to your SMTP server
      • port - Which port the SMTP server is running on. Defaults to 465 (Secure SMTP)
      • secure (boolean) - Whether to use SMTPS or not.
      • sender - Which email should be set as sender of mails being sent from Unleash?
      • smtpuser - Username for your SMTP server
      • smtppass - Password for your SMTP server

    • eventHook (function(event, data)) - (deprecated in Unleash 4.3 in favor of the Webhook integration. Removed in Unleash 5) If provided, this function will be invoked whenever a feature is mutated. The possible values for event are 'feature-created', 'feature-archived' and 'feature-revived'. The data argument contains information about the mutation. Its fields are type (string) - the event type (same as event); createdBy (string) - the user who performed the mutation; data - the contents of the change. The contents in data differs based on the event type; For 'feature-archived' and 'feature-revived', the only field will be name - the name of the feature. For 'feature-created' the data follows a schema defined in the code here. See an api here.

    • getLogger (function) - Used to register a custom log provider.

    • logLevel (debug | info | warn | error | fatal) - The lowest level to log at, also configurable using environment variable LOG_LEVEL.

    • enableRequestLogger (boolean) - use this to enable logging for requested urls and response codes (default: false).

    • preHook (function) - this is a hook if you need to provide any middlewares to express before unleash adds any. Express app instance is injected as first argument.

    • preRouterHook (function) - use this to register custom express middlewares before the unleash specific routers are added.

    • secureHeaders (boolean) - use this to enable security headers (HSTS, CSP, etc) when serving Unleash from HTTPS. Can also be configured through the environment variable SECURE_HEADERS.

    • additionalCspAllowedDomains (CspAllowedDomains) - use this when you want to enable security headers but have additional domains you need to allow traffic to. You can set the following environment variables:

      • CSP_ALLOWED_DEFAULT to allow new defaultSrc (comma separated list)
      • CSP_ALLOWED_FONT to allow new fontSrc (comma separated list)
      • CSP_ALLOWED_STYLE to allow new styleSrc (comma separated list)
      • CSP_ALLOWED_SCRIPT to allow new scriptSrc (comma separated list)
      • CSP_ALLOWED_IMG to allow new imgSrc (comma separated list)
      • CSP_ALLOWED_CONNECT to allow new connectSrc (comma separated list)
      • CSP_ALLOWED_FRAME to allow new frameSrc (comma separated listed)
      • CSP_ALLOWED_MEDIA to allow new mediaSrc (comma separated list)
      • CSP_ALLOWED_OBJECT to allow new objectSrc (comma separated list)

    • server - The server config object taking the following properties

      • port - which port the unleash-server should bind to. If port is omitted or is 0, the operating system will assign an arbitrary unused port. Will be ignored if pipe is specified. This value may also be set via the HTTP_PORT environment variable
      • host - which host the unleash-server should bind to. If host is omitted, the server will accept connections on the unspecified IPv6 address (::) when IPv6 is available, or the unspecified IPv4 address (0.0.0.0) otherwise. This value may also be set via the HTTP_HOST environment variable
      • pipe - parameter to identify IPC endpoints. See https://nodejs.org/api/net.html#net_identifying_paths_for_ipc_connections for more details
      • serverMetrics (boolean) - use this option to turn on/off prometheus metrics.
      • baseUriPath (string) - use to register a base path for all routes on the application. For example /my/unleash/base (note the starting /). Defaults to /. Can also be configured through the environment variable BASE_URI_PATH.
      • unleashUrl (string) - Used to specify the official URL this instance of Unleash can be accessed at for an end user. Can also be configured through the environment variable UNLEASH_URL.
      • gracefulShutdownEnable: (boolean) - Used to control if Unleash should shutdown gracefully (close connections, stop tasks,). Defaults to true. GRACEFUL_SHUTDOWN_ENABLE
      • gracefulShutdownTimeout: (number) - Used to control the timeout, in milliseconds, for shutdown Unleash gracefully. Will kill all connections regardless if this timeout is exceeded. Defaults to 1000ms GRACEFUL_SHUTDOWN_TIMEOUT

    • session - The session config object takes the following options:

      • ttlHours (number) - The number of hours a user session is allowed to live before a new sign-in is required. Defaults to 48 hours. SESSION_TTL_HOURS
      • clearSiteDataOnLogout (boolean) - When true, a logout action will return a Clear Site Data response header instructing the browser to clear all cookies on the same domain Unleash is running on. If disabled unleash will only destroy and clear the session cookie. Defaults to true. SESSION_CLEAR_SITE_DATA_ON_LOGOUT
      • cookieName - Name of the cookies used to hold the session id. Defaults to 'unleash-session'.

    • ui (object) - Set of UI specific overrides. You may set the following keys: environment, slogan.

    • versionCheck - the object deciding where to check for latest version

      • url - The url to check version (Defaults to https://version.unleash.run) - Overridable with (UNLEASH_VERSION_URL)
      • enable - Whether version checking is enabled (defaults to true) - Overridable with (CHECK_VERSION) (if anything other than true, does not check)

    • environmentEnableOverrides - A list of environment names to force enable at startup. This is feature should be used with caution. When passed a list, this will enable each environment in that list and disable all other environments. You can't use this to disable all environments, passing an empty list will do nothing. If one of the given environments is not already enabled on startup then it will also enable projects and toggles for that environment. Note that if one of the passed environments doesn't already exist this will do nothing aside from log a warning.

    • clientFeatureCaching - configuring memoization of the /api/client/features endpoint

      • enabled - set to true by default - Overridable with (CLIENT_FEATURE_CACHING_ENABLED)
      • maxAge - the time to cache features, set to 600 milliseconds by default - Overridable with (CLIENT_FEATURE_CACHING_MAXAGE) ) (accepts milliseconds)

    • frontendApi - Configuration options for the Unleash front-end API.

      • refreshIntervalInMs - how often (in milliseconds) front-end clients should refresh their data from the cache. Overridable with the FRONTEND_API_REFRESH_INTERVAL_MS environment variable.

    • accessControlMaxAge - You can configure the max-age of the Access-Control-Max-Age header. Defaults to 86400 seconds. Overridable with the ACCESS_CONTROL_MAX_AGE environment variable.

    • responseTimeWithAppNameKillSwitch - use this to disable metrics with app names. This is enabled by default but may increase the cardinality of metrics causing Unleash memory usage to grow if your app name is randomly generated (which is not recommended). Overridable with the UNLEASH_RESPONSE_TIME_WITH_APP_NAME_KILL_SWITCH environment variable.

    • disableCompression - Disables Express compression middleware, useful when configuring the application in a serverless environment. Defaults to false. Overridable with the SERVER_DISABLE_COMPRESSION environment variable.

    • keepAliveTimeout - Use this to tweak connection keepalive timeout in seconds. Useful for hosted situations where you need to make sure your connections are closed before terminating the instance. Defaults to 15. Overridable with the SERVER_KEEPALIVE_TIMEOUT environment variable. You can also set the environment variable ENABLED_ENVIRONMENTS to a comma delimited string of environment names to override environments.

    • metricsRateLimiting - Use the following to tweak the rate limits for /api/client/register, /api/client/metrics, /api/frontend/register and /api/frontend/metrics POST endpoints

      • clientMetricsMaxPerMinute - How many requests per minute per IP is allowed against POST /api/client/metrics before returning 429. Set to 6000 by default (100rps) - Overridable with REGISTER_CLIENT_RATE_LIMIT_PER_MINUTE environment variable
      • clientRegisterMaxPerMinute - How many requests per minute per IP is allowed against POST /api/client/register before returning 429. Set to 6000 by default (100rps) - Overridable with CLIENT_METRICS_RATE_LIMIT_PER_MINUTE environment variable
      • frontendMetricsMaxPerMinute - How many requests per minute per IP is allowed against POST /api/frontend/metrics before returning 429. Set to 6000 by default (100rps) - Overridable with FRONTEND_METRICS_RATE_LIMIT_PER_MINUTE environment variable
      • frontendRegisterMaxPerMinute - How many requests per minute per IP is allowed against POST /api/frontend/register before returning 429. Set to 6000 by default (100rps) - Overridable with REGISTER_FRONTEND_RATE_LIMIT_PER_MINUTE environment variable

    • rateLimiting - Use the following to tweak the rate limits for POST /auth/simple (Password-based login) and POST /api/admin/user-admin (Creating users)

      • simpleLoginMaxPerMinute - How many requests per minute per IP is allowed against POST /auth/simple before returning 429. Set to 10 by default - Overridable with SIMPLE_LOGIN_LIMIT_PER_MINUTE environment variable
      • createUserMaxPerMinute - How many requests per minute per IP is allowed against POST /api/admin/user-admin before returning 429. Set to 20 by default - Overridable with CREATE_USER_RATE_LIMIT_PER_MINUTE environment variable

    Disabling Auto-Start​

    If you're using Unleash as part of a larger express app, you can disable the automatic server start by calling server.create. It takes the same options as server.start, but will not begin listening for connections.

    const express = require('express');
    const unleash = require('unleash-server');
    const app = express();

    const start = async () => {
      const instance = await unleash.create({
        databaseUrl: 'postgres://unleash_user:password@localhost:5432/unleash',
      });
      app.use(instance.app);
      console.log(`Unleash app generated and attached to parent application`);
    };

    start();

    Graceful shutdown​

    PS! Unleash will listen for the SIGINT signal and automatically trigger graceful shutdown of Unleash.

    If you need to stop Unleash (close database connections, and stop running Unleash tasks) you may use the stop function. Be aware that it is not possible to restart the Unleash instance after stopping it, but you can create a new instance of Unleash.

    const express = require('express');
    const unleash = require('unleash-server');
    const app = express();

    const start = async () => {
      const instance = await unleash.start({
        databaseUrl: 'postgres://unleash_user:password@localhost:5432/unleash',
        port: 4242,
      });

      //Sometime later
      await instance.stop();
      console.log('Unleash has now stopped');
    };

    start();

    Segment limits​

    caution

    Changing segment limits could have a negative impact on the performance of Unleash SDKs and cause network congestion. Think twice before changing these values.

    Some facets of the segments feature can be customized via environment variables. This lets you change the segment limits that Unleash uses.

    UNLEASH_STRATEGY_SEGMENTS_LIMIT controls the maximum number of segments that can be applied to a single strategy. The default is 5.

    UNLEASH_SEGMENT_VALUES_LIMIT controls the maximum number of values that you can assign across a segment's constraints. The default is 1000 (Since v5.1.0; it was 100 before v5.1.0)

    Securing Unleash​

    You can integrate Unleash with your authentication provider (OAuth 2.0). Read more about securing unleash.

    How do I configure the log output?​

    By default, unleash uses log4js to log important information. It is possible to swap out the logger provider (only when using Unleash programmatically). You do this by providing an implementation of the getLogger function as This enables filtering of log levels and easy redirection of output streams.

    function getLogger(name) {
      // do something with the name
      return {
        debug: console.log,
        info: console.log,
        warn: console.log,
        error: console.error,
      };
    }

    The logger interface with its debug, info, warn and error methods expects format string support as seen in debug or the JavaScript console object. Many commonly used logging implementations cover this API, e.g., bunyan, pino or winston.

    Database configuration​

    info

    In-code configuration values take precedence over environment values: If you provide a database username both via environment variables and in code with the Unleash options object, Unleash will use the in-code username.

    You cannot run the Unleash server without a database. You must provide Unleash with database connection details for it to start correctly.

    The available options are listed in the table below. Options can be specified either via JavaScript (only when starting Unleash via code) or via environment variables. The "property name" column below gives the name of the property on the Unleash options' db object.

    Property nameEnvironment variableDefault valueDescription
    userDATABASE_USERNAMEunleash_userThe database username.
    passwordDATABASE_PASSWORDpasswordThe database password.
    hostDATABASE_HOSTlocalhostThe database hostname.
    portDATABASE_PORT5432The database port.
    databaseDATABASE_NAMEunleashThe name of the database.
    sslDATABASE_SSLN/AAn object describing SSL options. In code, provide a regular JavaScript object. When using the environment variable, provide a stringified JSON object.
    poolN/A (use the below variables)An object describing database pool options. With environment variables, use the options below directly.
    pool.minDATABASE_POOL_MIN0The minimum number of connections in the connection pool.
    pool.maxDATABASE_POOL_MAX4The maximum number of connections in the connection pool.
    pool.idleTimeoutMillisDATABASE_POOL_IDLE_TIMEOUT_MS30000The amount of time (in milliseconds) that a connection must be idle for before it is marked as a candidate for eviction.
    applicationNameDATABASE_APPLICATION_NAMEunleashThe name of the application that created this Client instance.
    schemaDATABASE_SCHEMApublicThe schema to use in the database.

    Alternatively, you can use a single-host libpq connection string to connect to the database. You can provide it directly or from a file by using one of the below options. In JavaScript, these are top-level properties of the root configuration object, not the db object.

    Property nameEnvironment variableDefault valueDescription
    databaseUrlDATABASE_URLN/AA string that matches a single-host libpq connection string, such as postgres://USER:PASSWORD@HOST:PORT/DATABASE. Unleash does not support using multiple hosts.
    databaseUrlFileDATABASE_URL_FILEN/AThe path to a file that contains a libpq connection string.

    Below is an example JavaScript configuration object.

    const unleashOptions = {
      databaseUrl: 'postgres:/USER:PASSWORD@HOST:PORT/DATABASE',
      databaseUrlFile: '/path/to/file',
      db: {
        user: 'unleash_user',
        password: 'password',
        host: 'localhost',
        port: 5432,
        database: 'unleash',
        ssl: false,
        pool: {
          min: 0,
          max: 4,
          idleTimeoutMillis: 30000,
        },
      },
    };

    db.ssl vs DATABASE_SSL options​

    When initializing Unleash from code, you'll provide the db.ssl option as a JavaScript object. As such, any functions will get evaluated before the object is used for configuration. When using the DATABASE_SSL environment variable, you must provide the value as a stringified JSON object. The object will get parsed before being used for configuration, but no further evaluation will take place.

    If you want to read content from a file, you should either initialize Unleash via JavaScript or manually interpolate the required values into the environment variable:

    Reading from the file system in JavaScript
    const unleashOptions = {
      db: {
        // other options omitted for brevity
        ssl: {
          ca: fs.readFileSync('/path/to/server-certificates/root.crt').toString(),
        },
      },
    };

    Enabling self-signed certificates​

    To use self-signed certificates, you should set the SSL property rejectUnauthorized to false and set the ca property to the value of the certificate:

    Enable self-signed certificates
    const unleashOptions = {
      db: {
        // other options omitted for brevity
        ssl: {
          rejectUnauthorized: false,
          ca: fs.readFileSync('/path/to/server-certificates/root.crt').toString(),
        },
      },
    };

    Visit the node-postgres library's SSL section for more information.

    Supported Postgres SSL modes​

    Unleash builds directly on the node-postgres library, so we support all the same SSL modes that they support. As of version 8 (released on February 25th 2020), node-postgres no longer supports all sslmodes. For this reason, Unleash cannot support all of Postgres' SSL modes. Specifically, Unleash does not support sslmode=prefer. Instead you must know whether you require an SSL connection ahead of time.

    Troubleshooting: database pooling connection timeouts​

    • Check the default values of connection pool about idle session handling.

    • If you have a network component which closes idle sessions on the TCP layer, make sure that the connection pool's idleTimeoutMillis setting is lower than the timespan setting. If it isn't, then the network component will close the connection.

    Proxying requests from Unleash​

    You can configure proxy services that intercept all outgoing requests from Unleash. This lets you use the Microsoft Teams or the Webhook integration for external services, even if the internet can only be reached via a proxy on your machine or container (for example if restricted by a firewall or similiar).

    As an example, here's how you could do it using the node-global-proxy package:

    const proxy = require("node-global-proxy").default;

    proxy.setConfig({
        http: "http://user:password@url:8080",      //proxy adress, replace values as needed
        //https: "https://user:password@url:1080",  //if a https proxy is needed
      });

    proxy.start();      //this starts the proxy, after this call all requests will be proxied

    Using above code-snippet, every outgoing request from unleash or its integrations will be subsequently routed through set proxy. If the proxy routing needs to be bypassed or stopped, its possible to stop it by using

    proxy.stop();

    - + \ No newline at end of file diff --git a/using-unleash/deploy/database-backup.html b/using-unleash/deploy/database-backup.html index 638201f09e..882b49bd3c 100644 --- a/using-unleash/deploy/database-backup.html +++ b/using-unleash/deploy/database-backup.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Database Backup

    When upgrading to a new major version of Unleash, we advise to do a full database backup to ease rollback in case of failures.

    1. Create a database backup:
    pg_dump --clean -U unleash_user -W -h localhost unleash > unleash-db.dump

    1. Restore from a backup:
    psql -U unleash_user -W -h localhost unleash < unleash-db.dump
    - + \ No newline at end of file diff --git a/using-unleash/deploy/database-setup.html b/using-unleash/deploy/database-setup.html index e24bd4340c..3e2c9c8b7f 100644 --- a/using-unleash/deploy/database-setup.html +++ b/using-unleash/deploy/database-setup.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Database Setup

    To run Unleash you need to have PostgreSQL database (PostgreSQL v14.x or newer).

    1. Create a local unleash databases in PostgreSQL
    $ psql postgres <<SQL
    CREATE USER unleash_user WITH PASSWORD 'password';
    CREATE DATABASE unleash;
    GRANT ALL PRIVILEGES ON DATABASE unleash to unleash_user;
    SQL

    You will now have a PostgreSQL database with the following configuration:

    • database name: unleash
    • username: unleash_user
    • password: password
    • host: localhost (assuming you started it locally)
    • port: 5432 (assuming you are using the default PostgreSQL port)
    - + \ No newline at end of file diff --git a/using-unleash/deploy/email-service.html b/using-unleash/deploy/email-service.html index c9acd586ee..a3833bd71f 100644 --- a/using-unleash/deploy/email-service.html +++ b/using-unleash/deploy/email-service.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Email service

    New since Unleash v4.0.0 is an email service allowing us to send reset password and welcome mails to new users. In order for this to work you'll need to tell unleash what SMTP service you'd like to send mails from.

    If the service is not configured you'll see a log line every time you add a new user saying

    [2021-05-07T12:59:04.572] [WARN] routes/user-controller.ts - email
    was not sent to the user because email configuration is lacking

    Configuring​

    Depending on your deploy case there are different ways of configuring this service. Full documentation of all configuration possibilities is available here

    Docker​

    With docker, we configure the mail service via environment variables.

    You'll want to at least include EMAIL_HOST, EMAIL_USER, EMAIL_PASSWORD and EMAIL_SENDER

    Environment variables:

    • EMAIL_HOST - Your SMTP server address
    • EMAIL_PORT - Your SMTP server port - defaults to 567
    • EMAIL_SECURE - whether to use SMTPS - set to false or true - defaults to false,
    • EMAIL_USER - the username to authenticate against your SMTP server
    • EMAIL_PASSWORD - the password for your SMTP user
    • EMAIL_SENDER - which address should reset-password mails and welcome mails be sent from - defaults to noreply@unleash-hosted.com which is probably not what you want.

    Node​

    With node, we can configure this when calling Unleash's start method.

    const unleash = require('unleash-server');

    unleash.start({
      email: {
        host: 'myhost',
        smtpuser: 'username',
        smtppass: 'password',
        sender: 'noreply@mycompany.com',
      },
    });

    Troubleshooting​

    For troubleshooting tips, please refer to the email service troubleshooting guide.

    - + \ No newline at end of file diff --git a/using-unleash/deploy/getting-started.html b/using-unleash/deploy/getting-started.html index 1cf44f576e..989692e948 100644 --- a/using-unleash/deploy/getting-started.html +++ b/using-unleash/deploy/getting-started.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Getting Started

    This section only applies if you plan to self-host Unleash. If you are looking for our hosted solution you should head over to www.getunleash.io

    Requirements​

    You will need:

    Start Unleash server​

    Whichever option you choose to start Unleash, you must specify a database URI (it can be set in the environment variable DATABASE_URL). If your database server is not set up to support SSL you'll also need to set the environment variable DATABASE_SSL to false

    Once the server has started, you will see the message:

    Unleash started on http://localhost:4242

    To run multiple replicas of Unleash simply point all instances to the same database.

    Unleash v4: The first time Unleash starts it will create a default user which you can use to sign-in to you Unleash instance and add more users with:

    • username: admin
    • password: unleash4all

    If you'd like the default admin user to be created with a different username and password, you may define the following environment variables when running Unleash:

    • UNLEASH_DEFAULT_ADMIN_USERNAME
    • UNLEASH_DEFAULT_ADMIN_PASSWORD

    The way of defining these variables may vary depending on how you run Unleash.

    Option 1 - use Docker​

    Useful links:

    Steps:

    1. Create a network by running docker network create unleash
    2. Start a postgres database:
    docker run -e POSTGRES_PASSWORD=some_password \
      -e POSTGRES_USER=unleash_user -e POSTGRES_DB=unleash \
      --network unleash --name postgres postgres
    1. Start Unleash via docker:
    docker run -p 4242:4242 \
      -e DATABASE_HOST=postgres -e DATABASE_NAME=unleash \
      -e DATABASE_USERNAME=unleash_user -e DATABASE_PASSWORD=some_password \
      -e DATABASE_SSL=false \
      --network unleash --pull=always unleashorg/unleash-server

    Option 2 - use Docker-compose​

    Steps:

    1. Clone the Unleash repository.
    2. Run docker compose up -d in repository root folder.

    Option 3 - from Node.js​

    1. Create a new folder/directory on your development computer.

    2. From a terminal/bash shell, install the dependencies:

      npm init
      npm install unleash-server --save

    3. Create a file called server.js, paste the following into it and save.

      const unleash = require('unleash-server');

      unleash
        .start({
          db: {
            ssl: false,
            host: 'localhost',
            port: 5432,
            database: 'unleash',
            user: 'unleash_user',
            password: 'password',
          },
          server: {
            port: 4242,
          },
        })
        .then((unleash) => {
          console.log(
            `Unleash started on http://localhost:${unleash.app.get('port')}`,
          );
        });

    4. Run server.js:

      node server.js

    Create an api token for your client​

    Test your server and create a sample API call​

    Once the Unleash server has started, go to localhost:4242 in your browser. If you see an empty list of feature toggles, try creating one with curl from a terminal/bash shell:

    curl --location -H "Authorization: <apitoken from previous step>" \
      --request POST 'http://localhost:4242/api/admin/features' \
      --header 'Content-Type: application/json' --data-raw '{\
      "name": "Feature.A",\
      "description": "Dolor sit amet.",\
      "type": "release",\
      "enabled": false,\
      "stale": false,\
      "strategies": [\
        {\
          "name": "default",\
          "parameters": {}\
        }\
      ]\
    }'

    Version check​

    • Unleash checks that it uses the latest version by making a call to https://version.unleash.run.
      • This is a cloud function storing instance id to our database for statistics.
    • This request includes a unique instance id for your server.
    • If you do not wish to check for upgrades define the environment variable CHECK_VERSION to anything else other than true before starting, and Unleash won't make any calls
      • export CHECK_VERSION=false
    - + \ No newline at end of file diff --git a/using-unleash/deploy/google-auth-hook.html b/using-unleash/deploy/google-auth-hook.html index 0069bcb183..d65847a3e6 100644 --- a/using-unleash/deploy/google-auth-hook.html +++ b/using-unleash/deploy/google-auth-hook.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Google Auth Hook

    You can also find the complete source code for this guide in the unleash-examples project.

    This part of the tutorial shows how to create a sign-in flow for users and integrate with Unleash server project. The implementation assumes that I am working in localhost with 4242 port.

    If you are still using Unleash v3 you need to follow the google-auth-hook-v3

    This is a simple index.ts server file.

    const unleash = require('unleash-server');

    unleash.start(options).then((unleash) => {
      console.log(`Unleash started on http://localhost:${unleash.app.get('port')}`);
    });

    Creating a web application client ID​

    1. Go to the credentials section in the Google Cloud Platform Console.

    2. Click OAuth consent screen. Type a product name. Fill in any relevant optional fields. Click Save.

    3. Click Create credentials > OAuth client ID.

    4. Under Application type, select Web Application.

    5. Type the Name.

    6. Under Authorized redirect URIs enter the following URLs, one at a time.

    http://localhost:4242/api/auth/callback

    1. Click Create.

    2. Copy the CLIENT ID and CLIENT SECRET and save them for later use.

    Add dependencies​

    Add two dependencies @passport-next/passport and @passport-next/passport-google-oauth2 inside index.ts file

    const unleash = require('unleash-server');
    const passport = require('@passport-next/passport');
    const GoogleOAuth2Strategy =
      require('@passport-next/passport-google-oauth2').Strategy;

    Add googleAdminAuth() function and other options. Make sure to also accept the services argument to get access to the userService.

    function googleAdminAuth(app, config, services) {
      const { baseUriPath } = config.server;
      const { userService } = services;
    }

    let options = {
      authentication: {
        type: 'custom',
        customAuthHandler: googleAdminAuth,
      },
    };

    unleash.start(options).then((instance) => {
      console.log(
        `Unleash started on http://localhost:${instance.app.get('port')}`,
      );
    });

    In googleAdminAuth function: Configure the Google strategy for use by Passport.js​

    OAuth 2-based strategies require a verify function which receives the credential (accessToken) for accessing the Google API on the user's behalf, along with the user's profile. The function must invoke cb with a user object, which will be set at req.user in route handlers after authentication.

    const GOOGLE_CLIENT_ID = '...';
    const GOOGLE_CLIENT_SECRET = '...';
    const GOOGLE_CALLBACK_URL = 'http://localhost:4242/api/auth/callback';

    function googleAdminAuth(app, config, services) {
      const { baseUriPath } = config.server;
      const { userService } = services;

      passport.use(
        new GoogleOAuth2Strategy(
          {
            clientID: GOOGLE_CLIENT_ID,
            clientSecret: GOOGLE_CLIENT_SECRET,
            callbackURL: GOOGLE_CALLBACK_URL,
          },
          async function (accessToken, refreshToken, profile, cb) {
            // Extract the minimal profile information we need from the profile object
            // and connect with Unleash
            const email = profile.emails[0].value;
            const user = await userService.loginUserWithoutPassword(email, true);
            cb(null, user);
          },
        ),
      );
    }

    In googleAdminAuth function​

    Configure passport package.

    function googleAdminAuth(app, config, services) {
      // ...
      app.use(passport.initialize());
      app.use(passport.session());
      passport.serializeUser((user, done) => done(null, user));
      passport.deserializeUser((user, done) => done(null, user));
      // ...
    }

    Implement a preRouter hook for /auth/google/login. It's necessary for login with Google.

    function googleAdminAuth(app, config, services) {
      // ...
      app.get(
        '/auth/google/login',
        passport.authenticate('google', { scope: ['email'] }),
      );
      // ...
    }

    Implement a preRouter hook for /api/auth/callback. It's a callback when the login is executed.

    function googleAdminAuth(app, config, services) {
      // ...
      app.get(
        '/api/auth/callback',
        passport.authenticate('google', {
          failureRedirect: '/api/admin/error-login',
        }),
        (req, res) => {
          // Successful authentication, redirect to your app.
          res.redirect('/');
        },
      );
      // ...
    }

    Implement a preRouter hook for /api/.

    function googleAdminAuth(app, config, services) {
      // ...
      app.use('/api/', (req, res, next) => {
        if (req.user) {
          next();
        } else {
          // Instruct unleash-frontend to pop-up auth dialog
          return res
            .status('401')
            .json(
              new unleash.AuthenticationRequired({
                path: '/auth/google/login',
                type: 'custom',
                message: `You have to identify yourself in order to use Unleash. Click the button and follow the instructions.`,
              }),
            )
            .end();
        }
      });
      // ...
    }

    The complete code​

    You can also find the complete source code for this guide in the unleash-examples project.

    The index.ts server file.

    'use strict';

    const unleash = require('unleash-server');
    const passport = require('@passport-next/passport');
    const GoogleOAuth2Strategy = require('@passport-next/passport-google-oauth2');

    const GOOGLE_CLIENT_ID = '...';
    const GOOGLE_CLIENT_SECRET = '...';
    const GOOGLE_CALLBACK_URL = 'http://localhost:4242/api/auth/callback';

    function googleAdminAuth(app, config, services) {
      const { baseUriPath } = config.server;
      const { userService } = services;

      passport.use(
        new GoogleOAuth2Strategy(
          {
            clientID: GOOGLE_CLIENT_ID,
            clientSecret: GOOGLE_CLIENT_SECRET,
            callbackURL: GOOGLE_CALLBACK_URL,
          },
          async (accessToken, refreshToken, profile, cb) => {
            const email = profile.emails[0].value;
            const user = await userService.loginUserWithoutPassword(email, true);
            cb(null, user);
          },
        ),
      );

      app.use(passport.initialize());
      app.use(passport.session());
      passport.serializeUser((user, done) => done(null, user));
      passport.deserializeUser((user, done) => done(null, user));

      app.get(
        '/auth/google/login',
        passport.authenticate('google', { scope: ['email'] }),
      );
      app.get(
        '/api/auth/callback',
        passport.authenticate('google', {
          failureRedirect: '/api/admin/error-login',
        }),
        (req, res) => {
          res.redirect('/');
        },
      );

      app.use('/api/', (req, res, next) => {
        if (req.user) {
          next();
        } else {
          return res
            .status('401')
            .json(
              new unleash.AuthenticationRequired({
                path: '/auth/google/login',
                type: 'custom',
                message: `You have to identify yourself in order to use Unleash. Click the button and follow the instructions.`,
              }),
            )
            .end();
        }
      });
    }

    const options = {
      authentication: {
        type: 'custom',
        customAuthHandler: googleAdminAuth,
      },
    };

    unleash.start(options);
    - + \ No newline at end of file diff --git a/using-unleash/deploy/google-auth-v3.html b/using-unleash/deploy/google-auth-v3.html index 9186192630..29aedede90 100644 --- a/using-unleash/deploy/google-auth-v3.html +++ b/using-unleash/deploy/google-auth-v3.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Google Auth v3

    You can also find the complete source code for this guide in the unleash-examples project.

    This part of the tutorial shows how to create a sign-in flow for users and integrate with Unleash server project. The implementation assumes that I am working in localhost with 4242 port.

    This is a simple index.ts server file.

    const unleash = require('unleash-server');

    unleash.start(options).then((unleash) => {
      console.log(`Unleash started on http://localhost:${unleash.app.get('port')}`);
    });

    Creating a web application client ID​

    1. Go to the credentials section in the Google Cloud Platform Console.

    2. Click OAuth consent screen. Type a product name. Fill in any relevant optional fields. Click Save.

    3. Click Create credentials > OAuth client ID.

    4. Under Application type, select Web Application.

    5. Type the Name.

    6. Under Authorized redirect URIs enter the following URLs, one at a time.

    http://localhost:4242/api/auth/callback

    1. Click Create.

    2. Copy the CLIENT ID and CLIENT SECRET and save them for later use.

    Add dependencies​

    Add two dependencies @passport-next/passport and @passport-next/passport-google-oauth2 inside index.ts file

    const unleash = require('unleash-server');
    const passport = require('@passport-next/passport');
    const GoogleOAuth2Strategy =
      require('@passport-next/passport-google-oauth2').Strategy;

    Configure the Google strategy for use by Passport.js​

    OAuth 2-based strategies require a verify function which receives the credential (accessToken) for accessing the Google API on the user's behalf, along with the user's profile. The function must invoke cb with a user object, which will be set at req.user in route handlers after authentication.

    const GOOGLE_CLIENT_ID = '...';
    const GOOGLE_CLIENT_SECRET = '...';
    const GOOGLE_CALLBACK_URL = 'http://localhost:4242/api/auth/callback';

    passport.use(
      new GoogleOAuth2Strategy(
        {
          clientID: GOOGLE_CLIENT_ID,
          clientSecret: GOOGLE_CLIENT_SECRET,
          callbackURL: GOOGLE_CALLBACK_URL,
        },
        function (accessToken, refreshToken, profile, cb) {
          // Extract the minimal profile information we need from the profile object
          // and connect with Unleash to get name and email.
          cb(
            null,
            new unleash.User({
              name: profile.displayName,
              email: profile.emails[0].value,
            }),
          );
        },
      ),
    );

    Add googleAdminAuth() function and other options

    function googleAdminAuth(app) {}

    let options = {
      adminAuthentication: 'custom',
      preRouterHook: googleAdminAuth,
    };

    unleash.start(options).then((instance) => {
      console.log(
        `Unleash started on http://localhost:${instance.app.get('port')}`,
      );
    });

    In googleAdminAuth function​

    Configure passport package.

    function googleAdminAuth(app) {
      app.use(passport.initialize());
      app.use(passport.session());
      passport.serializeUser((user, done) => done(null, user));
      passport.deserializeUser((user, done) => done(null, user));
      // ...
    }

    Implement a preRouter hook for /auth/google/login. It's necessary for login with Google.

    function googleAdminAuth(app) {
      // ...
      app.get(
        '/auth/google/login',
        passport.authenticate('google', { scope: ['email'] }),
      );
      // ...
    }

    Implement a preRouter hook for /api/auth/callback. It's a callback when the login is executed.

    function googleAdminAuth(app) {
      // ...
      app.get(
        '/api/auth/callback',
        passport.authenticate('google', {
          failureRedirect: '/api/admin/error-login',
        }),
        (req, res) => {
          // Successful authentication, redirect to your app.
          res.redirect('/');
        },
      );
      // ...
    }

    Implement a preRouter hook for /api/admin.

    function googleAdminAuth(app) {
      // ...
      app.use('/api/admin/', (req, res, next) => {
        if (req.user) {
          next();
        } else {
          // Instruct unleash-frontend to pop-up auth dialog
          return res
            .status('401')
            .json(
              new unleash.AuthenticationRequired({
                path: '/auth/google/login',
                type: 'custom',
                message: `You have to identify yourself in order to use Unleash. Click the button and follow the instructions.`,
              }),
            )
            .end();
        }
      });
      // ...
    }

    The complete code​

    The index.ts server file.

    'use strict';

    const unleash = require('unleash-server');
    const passport = require('@passport-next/passport');
    const GoogleOAuth2Strategy = require('@passport-next/passport-google-oauth2');

    const GOOGLE_CLIENT_ID = '...';
    const GOOGLE_CLIENT_SECRET = '...';
    const GOOGLE_CALLBACK_URL = 'http://localhost:4242/api/auth/callback';

    passport.use(
      new GoogleOAuth2Strategy(
        {
          clientID: GOOGLE_CLIENT_ID,
          clientSecret: GOOGLE_CLIENT_SECRET,
          callbackURL: GOOGLE_CALLBACK_URL,
        },
        (accessToken, refreshToken, profile, cb) => {
          cb(
            null,
            new unleash.User({
              name: profile.displayName,
              email: profile.emails[0].value,
            }),
          );
        },
      ),
    );

    function googleAdminAuth(app) {
      app.use(passport.initialize());
      app.use(passport.session());
      passport.serializeUser((user, done) => done(null, user));
      passport.deserializeUser((user, done) => done(null, user));

      app.get(
        '/auth/google/login',
        passport.authenticate('google', { scope: ['email'] }),
      );
      app.get(
        '/api/auth/callback',
        passport.authenticate('google', {
          failureRedirect: '/api/admin/error-login',
        }),
        (req, res) => {
          res.redirect('/');
        },
      );

      app.use('/api/admin/', (req, res, next) => {
        if (req.user) {
          next();
        } else {
          return res
            .status('401')
            .json(
              new unleash.AuthenticationRequired({
                path: '/auth/google/login',
                type: 'custom',
                message: `You have to identify yourself in order to use Unleash. Click the button and follow the instructions.`,
              }),
            )
            .end();
        }
      });
    }

    const options = {
      adminAuthentication: 'custom',
      preRouterHook: googleAdminAuth,
    };

    unleash.start(options).then((instance) => {
      console.log(
        `Unleash started on http://localhost:${instance.app.get('port')}`,
      );
    });
    - + \ No newline at end of file diff --git a/using-unleash/deploy/license-keys.html b/using-unleash/deploy/license-keys.html index 72d6db54f4..34718733cc 100644 --- a/using-unleash/deploy/license-keys.html +++ b/using-unleash/deploy/license-keys.html @@ -20,7 +20,7 @@ - + @@ -32,7 +32,7 @@ 2) Specifying a environment variable upon container deployment

    The process is the same whether you are licensing your self-hosted instance for the first time.

    note

    After updating a license key, a manual browser refresh may be required for any displayed licensing related banners to be removed from your session.

    Admin UI​

    info

    This area of the UI can also be used to verify the currently installed key details

    1) Log in to the Unleash UI as an admin privileged user
    2) Navigate to the admin menu (gear icon) -> License
    3) If a key is already installed, the following details will be shown:

    4) Paste the new license key and click Update license key

    License overview screen

    Environment Variable​

    License key installation or update through an environment variable on container deployment is also possible, using the format UNLEASH_LICENSE.

    For security, if using helm charts or docker compose to deploy Unleash, a best practice would be to setup the license key as a secret and reference it in the helm configuration values.yaml or docker-compose.yml.

    info

    The default image references in the Helm chart point to open-source Unleash resources. To use Unleash Enterprise, you must manually update the image references to point to the appropriate unleash-enterprise images

    - + \ No newline at end of file diff --git a/using-unleash/deploy/securing-unleash-v3.html b/using-unleash/deploy/securing-unleash-v3.html index 439b2cc36b..4a5dc04163 100644 --- a/using-unleash/deploy/securing-unleash-v3.html +++ b/using-unleash/deploy/securing-unleash-v3.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Securing Unleash v3

    This guide is only relevant if you are using Unleash Open-Source. The Enterprise edition does already ship with a secure setup and multiple SSO options.

    The Unleash API is split into two different paths: /api/client and /api/admin. This makes it easy to have different authentication strategy for the admin interface and the client-api used by the applications integrating with Unleash.

    General settings​

    Unleash uses an encrypted cookie to maintain a user session. This allows users to be logged in across multiple instances of Unleash. To protect this cookie, Unleash will automatically generate a secure token the first time you start Unleash.

    Securing the Admin API​

    To secure the Admin API, you have to tell Unleash that you are using a custom admin authentication and implement your authentication logic as a preHook.

    const unleash = require('unleash-server');
    const myCustomAdminAuth = require('./auth-hook');

    unleash
      .start({
        databaseUrl: 'postgres://unleash_user:passord@localhost:5432/unleash',
        adminAuthentication: 'custom',
        preRouterHook: myCustomAdminAuth,
      })
      .then((unleash) => {
        console.log(
          `Unleash started on http://localhost:${unleash.app.get('port')}`,
        );
      });

    Additionally, you can trigger the admin interface to prompt the user to sign in by configuring your middleware to return a 401 status on protected routes. The response body must contain a message and a path used to redirect the user to the proper login route.

    {
      "message": "You must be logged in to use Unleash",
      "path": "/custom/login"
    }

    Examples of custom authentication hooks:

    Securing the Client API​

    A common way to support client access is to use pre-shared secrets. This can be solved by having clients send a shared key in an HTTP header with every client request to the Unleash API. All official Unleash clients should support this.

    In the Java client this would look like this:

    UnleashConfig unleashConfig = UnleashConfig.builder()
      .appName("my-app")
      .instanceId("my-instance-1")
      .unleashAPI(unleashAPI)
      .customHttpHeader("Authorization", "12312Random")
      .build();

    On the Unleash server side, you need to implement a preRouter hook which verifies that all calls to /api/client include this pre-shared key in the defined header. This could look something like this.

    const unleash = require('unleash-server');
    const sharedSecret = '12312Random';

    unleash
      .start({
        databaseUrl: 'postgres://unleash_user:passord@localhost:5432/unleash',
        preRouterHook: (app) => {
          app.use('/api/client', (req, res, next) => {
            if (req.header('authorization') !== sharedSecret) {
              res.sendStatus(401);
            } else {
              next();
            }
          });
        },
      })
      .then((unleash) => {
        console.log(
          `Unleash started on http://localhost:${unleash.app.get('port')}`,
        );
      });

    client-auth-unleash.js

    - + \ No newline at end of file diff --git a/using-unleash/deploy/securing-unleash.html b/using-unleash/deploy/securing-unleash.html index 74eac72aaf..411a3e77c5 100644 --- a/using-unleash/deploy/securing-unleash.html +++ b/using-unleash/deploy/securing-unleash.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Securing Unleash

    If you are still using Unleash v3 you need to follow the securing-unleash-v3

    This guide is only relevant if you are using Unleash Open-Source. The Enterprise edition does already ship with multiple SSO options, such as SAML 2.0, OpenID Connect.

    Unleash Open-Source v4 comes with username/password authentication out of the box. In addition Unleash v4 also comes with API token support, to make it easy to handle access tokens for Client SDKs and programmatic access to the Unleash APIs.

    Password requirements​

    Unleash requires a strong password.

    • minimum 10 characters long
    • contains at least one uppercase letter
    • contains at least one number
    • contains at least one special character (symbol)

    Implementing Custom Authentication​

    If you do not wish to use the built-in username/password authentication you can add a customAuthHandler

    To secure the Admin API, you have to tell Unleash that you are using a custom admin authentication and implement your authentication logic as a preHook.

    const unleash = require('unleash-server');
    const myCustomAdminAuth = require('./auth-hook');

    unleash
      .start({
        databaseUrl: 'postgres://unleash_user:password@localhost:5432/unleash',
        authentication: {
          type: 'custom',
          customAuthHandler: myCustomAdminAuth,
        },
      })
      .then((unleash) => {
        console.log(
          `Unleash started on http://localhost:${unleash.app.get('port')}`,
        );
      });

    Additionally, you can trigger the admin interface to prompt the user to sign in by configuring your middleware to return a 401 status on protected routes. The response body must contain a message and a path used to redirect the user to the proper login route.

    {
      "message": "You must be logged in to use Unleash",
      "path": "/custom/login"
    }

    Examples of custom authentication hooks:

    - + \ No newline at end of file diff --git a/using-unleash/deploy/upgrading-unleash.html b/using-unleash/deploy/upgrading-unleash.html index 46aedd0939..d674fc06cf 100644 --- a/using-unleash/deploy/upgrading-unleash.html +++ b/using-unleash/deploy/upgrading-unleash.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    Upgrading Unleash

    Generally, the intention is that unleash-server should always provide support for clients one major version lower than the current one. This should make it possible to upgrade unleash gradually.

    Upgrading directly from v3.x to v5.x​

    Ivar Østhus, Unleash CTO and Co-Founder, demonstrates how to update Unleash 3.x to Unleash 5.x in just a few minutes with no downtime. You can also watch this on YouTube with a transcript.

    Upgrading from v4.x to v5.x​

    Unleash v5 was released on April 27th, 2023. It contains a few breaking changes.

    Requires Node.js version 18+​

    Unleash v5 drops support Node.js versions below 18, which is the current active LTS at the time of release. Unleash v4 officially supported Node.js v14 and v16, but both of these will reach end of life in 2023.

    The Google Authenticator provider for SSO has been removed​

    The Google Authenticator provider is now hidden by default. We recommend using OpenID Connect instead.

    However, if you are running a self hosted version of Unleash and you need to temporarily re-enable Google SSO, you can do so by setting the GOOGLE_AUTH_ENABLED environment variable to true. If you're running a hosted version of Unleash, you'll need to reach out to us and ask us to re-enable the flag. However, the ability to do this will be removed in a future release and this is not safe to depend on.

    This provider was deprecated in v4.

    Default database password​

    The Unleash default database password is now password instead of passord. Turns out that the Norwegian word for password is too similar to the English word, and that people would think it was a typo.

    This should only impact dev builds and initial setup. You should never use the default password in any production environments.

    The /api/admin/features API is gone​

    Most of the old features API was deprecated in v4.3 and superseded by the project API instead. In v5, the deprecated parts have been completely removed. The only operations on that API that are still active are the operations to add or remove a tag from a feature toggle.

    Error message structure​

    Some of Unleash's API error messages have changed their structure. Specifically, this applies to error messages generated by our OpenAPI validation layer. However, only their structure has changed (and they now contain more human-friendly messages); the error codes should still be the same.

    Previously, they would look like this:

    {
      "error": "Request validation failed",
      "validation": [
        {
          "keyword": "type",
          "dataPath": ".body.parameters",
          "schemaPath": "#/components/schemas/addonCreateUpdateSchema/properties/parameters/type",
          "params": {
            "type": "object"
          },
          "message": "should be object"
        }
      ]
    }

    Now they look like this instead, and are more in line with the rest of Unleash's error messages.

    {
      "id": "37a1765f-a5a0-4371-8aa2-341f331579f9",
      "name": "ValidationError",
      "message": "Request validation failed: the payload you provided doesn't conform to the schema. Check the `details` property for a list of errors that we found.",
      "details": [
        {
          "description": "The .parameters property should be object. You sent [].",
          "path": "parameters"
        }
      ]
    }

    As such, if you're relying on the specifics of the error structure for those API errors, you might need to update your handling.

    Upgrading from v3.x to v4.x​

    Before you upgrade we strongly recommend that you take a full database backup, to make sure you can downgrade to version 3.

    You can also read the highlights of what's new in v4.

    1. All API calls now require a token.​

    If you are upgrading from Unleash Open-Source v3 client SDKs did not need to use an API token in order to connect to Unleash-server. Starting from v4 we have back-ported the API token handling for Enterprise in to the Open-Source version. This means that all client SDKs now need to use a client token in order to connect to Unleash.

    Read more in the API token documentation.

    2. Configuring Unleash​

    We have done a lot of changes to the options you can pass in to Unleash. If you are manually configuring Unleash you should have a look on the updated configuring Unleash documentation

    3. Role-based Access Control (RBAC)​

    We have implemented RBAC in Unleash v4. This has totally changed the permission system in Unleash.

    Required actions: If you have implemented "custom authentication" for your users you will need to make changes to your integration:

    • extendedPermissions option has been removed. You can no longer specify custom permission per-user basis. All "logged_in users" must belong to a "root" role. This can be "Admin", "Editor" or "Viewer". This is taken care of when you create new users via userService.
    • All "logged-in users" needs to be defined in Unleash and have a unique ID. This can be achieved by calling "createUser" on "userService".

    Code example:

    const user = userService.loginUserWithoutPassword(
      'some@getunleash.io',
      false, // autoCreateUser. Set to true if you want to create users on the fly.
    );

    // The user needs to be set on the current active session
    req.session.user = user;

    4. Legacy v2 routes removed​

    Only relevant if you use the enableLegacyRoutes option.

    In v2 you could query feature toggles on /api/features. This was deprecated in v4 and we introduced two different endpoints (/api/admin/features and /api/client/features) to be able to optimize performance and security. In v3 you could still enable the legacy routes via the enableLegacyRoutes option. This was removed in v4.

    5. Unleash CLI has been removed​

    Unleash no longer ships with a binary that allows you to start Unleash directly from the command line. From v4 you need to either use Unleash via docker or programmatically.

    Read more in our getting started documentation

    Upgrading from v2.x to v3.x​

    The notable change introduced in Unleash v3.x is a strict separation of API paths for client requests and admin requests. This makes it easier to implement different authentication mechanisms for the admin UI and all unleash-clients. You can read more about securing unleash.

    The recommended approach is to first upgrade the unleash-server to v3 (which still supports v2 clients). After this is done, you should upgrade all your clients to v3.

    After upgrading all your clients, you should consider turning off legacy routes, used by v2 clients. To do this, set the configuration option enableLegacyRoutes to false as described in the page on configuring Unleash v3.

    Upgrading from v1.0 to v2.0​

    Caveat 1: Not used db-migrate to migrate the Unleash database?​

    In FINN we used liquibase, for internal reasons, to migrate our database. Because unleash from version 2.0 migrates the database internally, with db-migrate, you need to make sure that all previous migrations for version 1 exist, so that Unleash does not try to create already existing tables.

    How to check?​

    If you don't have a "migrations" table with 7 unique migrations you are affected by this.

    How to fix?​

    Before starting unleash version 2 you have to run the SQL located under scripts/fix-migrations-version-1.sql

    Caveat 2: databaseUrl (not databaseUri)​

    Using Unleash as a library and injecting your own config? Then you should know that we changed the databaseUri config param name to databaseUrl. This is to make sure the param is aligned with the environment variable DATABASE_URL and avoid multiple names for the same config param.

    - + \ No newline at end of file diff --git a/using-unleash/troubleshooting.html b/using-unleash/troubleshooting.html index 6773773781..1b26b9a798 100644 --- a/using-unleash/troubleshooting.html +++ b/using-unleash/troubleshooting.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    How-to: troubleshooting

    Troubleshooting common problems. If you want to suggest new items, please phrase the title as a concrete problem

    - + \ No newline at end of file diff --git a/using-unleash/troubleshooting/cors.html b/using-unleash/troubleshooting/cors.html index ab4996d020..228b1d60ad 100644 --- a/using-unleash/troubleshooting/cors.html +++ b/using-unleash/troubleshooting/cors.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    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. These settings can be changed in the Unleash Dashboard under Settings -> CORS Origins or by using the API. Allowing all origins (using a single asterisk) will address this matter and is a great starting point when troubleshooting the behavior.
    2. 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: *.
    - + \ No newline at end of file diff --git a/using-unleash/troubleshooting/email-service.html b/using-unleash/troubleshooting/email-service.html index e5f1d55369..0e51a47c20 100644 --- a/using-unleash/troubleshooting/email-service.html +++ b/using-unleash/troubleshooting/email-service.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    The email service is not working correctly on my self-hosted Unleash instance

    When setting up your self-hosted Unleash instance, one of the available options is to configure an email service that will allow Unleash to send reset password and welcome emails to users.

    Here's how to troubleshoot some common issues related to the email service.

    Configuration​

    The most common issues arise from misconfiguration. Please refer to the following documentation for guidance:

    You should double check that the details in your configuration look correct.

    Invalid URL error​

    Make sure that the UNLEASH_URL variable is correctly set to a valid URL. This should be set to the public discoverable URL of your Unleash instance, and it should include the protocol (http or https).

    Examples:

    • Subdomain: https://unleash.mysite.com
    • Subpath: https://mysite.com/unleash

    SMTP TLS port​

    Please double check that you're trying to reach your SMTP server on the TLS port, typically 587.

    Custom SSL certificate​

    If you're using your own SMTP server which uses a custom SSL certificate, you will need to tell Unleash to trust that certificate. You can do this by setting the NODE_EXTRA_CA_CERTS variable to the path of the certificate file.

    This is usually done by mounting the custom certificate in a volume, and then setting NODE_EXTRA_CA_CERTS to the absolute path in the container where it can find the certificate. For example, if you mount it to /var/certs, you should set NODE_EXTRA_CA_CERTS to something like /var/certs/mycert.crt.

    - + \ No newline at end of file diff --git a/using-unleash/troubleshooting/feature-not-available.html b/using-unleash/troubleshooting/feature-not-available.html index e3c8b84eeb..33a96a2da6 100644 --- a/using-unleash/troubleshooting/feature-not-available.html +++ b/using-unleash/troubleshooting/feature-not-available.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    I don't see a documented Unleash feature in my admin UI

    Occasionally, users might come across a situation where a documented Unleash feature isn't visible in their admin UI. Here's how to troubleshoot this issue.

    You can usually find availability information in the feature's documentation page, displayed in a box like this:

    Availability

    Cool new feature was introduced as a beta feature in Unleash 5.5 and is only available in Unleash Enterprise. We plan to make this feature generally available to all Enterprise users in Unleash 5.6.

    1. Check that the feature is available in your current Unleash version. For example, Service accounts are available in Unleash 4.21 and later. If you're running a previous version, you'll need to update your Unleash instance.
    2. Make sure the feature is available for your plan, as you may need to upgrade your plan to access the feature.
    3. If this is a beta feature, it may not be enabled for your Unleash instance. Here's how you can enable it:
      • If you have a hosted Unleash instance and you'd like early access to the new feature, reach out to us so we can enable it for you.
      • If you're running a self-hosted Unleash instance, make sure you've enabled the feature in your Unleash configuration. Usually, this involves setting the correct environment variable. You can check the current flags and respective environment variables in your version's src/lib/types/experimental.ts. Setting this variable may look something like UNLEASH_EXPERIMENTAL_NEW_FEATURE=true.

    If you've followed the above steps and still can't access the feature, please contact us for further assistance.

    If you're currently using a beta feature, please reach out to us! We would be thrilled if you could provide some feedback.

    - + \ No newline at end of file diff --git a/using-unleash/troubleshooting/flag-exposure.html b/using-unleash/troubleshooting/flag-exposure.html index 8340902f78..e91d907e75 100644 --- a/using-unleash/troubleshooting/flag-exposure.html +++ b/using-unleash/troubleshooting/flag-exposure.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    My feature flag is enabled but all/some of our users are not exposed to it

    To confirm how users will have flags resolved, follow these steps:

    1. Ensure your application is waiting for the ready event: It could be that frontend clients are calling isEnabled('feature-flag') before they have the response from the server. In this case, you should defer isEnabled calls until the client has emitted the ready event.
    2. The Unleash Playground was developed with this particular use case in mind. An access token can be used along with context values (passed in via the UI) to see how a flag will be resolved.
    3. When using a gradual rollout strategy, be mindful of the stickiness value. When evaluating a flag, if the provided context does not include the field used in the stickiness configuration, the gradual rollout strategy will be evaluated to false.
    - + \ No newline at end of file diff --git a/using-unleash/troubleshooting/flag-not-returned.html b/using-unleash/troubleshooting/flag-not-returned.html index 2c72b5ee28..a7191eae79 100644 --- a/using-unleash/troubleshooting/flag-not-returned.html +++ b/using-unleash/troubleshooting/flag-not-returned.html @@ -20,7 +20,7 @@ - + @@ -28,7 +28,7 @@
    Skip to main content

    My feature flag is not returned in the Frontend API/Edge/Proxy

    By default, these endpoints will not return feature flags that are not enabled. This is mainly to save on bandwidth but it makes it a bit difficult to debug when features are not being returned.

    The first thing to look into is to validate that the feature is well configured and then check the token used from the SDK because it determines the set of accessible features. Last, verify that the context you're providing contains all the required data.

    1. Check that the feature is properly enabled:
      1. Verify that the feature has a strategy associated to it that will return true for your context (ref: add a strategy)
      2. Verify that the feature has been enabled in the environment used by the client application (ref: enabling a feature flag)
    2. Check that your token is of the right type. To connect to the Frontend API, Edge or Proxy, you need to use a Front-end token
    3. Check that your token has access to the feature flag. The token access configuration is immutable post-creation and defines the set of features that the token can access. The different parts of a token determine what projects and environment can be accessed:
      1. Access to all projects (current and future) - Tokens with a leading asterisk will provide access to all projects in a particular environment. For example, the token *:production:xyz123etc... will provide access to flags in the production environment of all projects.
      2. Access to a discrete list of projects - Tokens with a leading set of square brackets (empty) will be given access to a subset of projects in a particular environment. The token will look similar to the following: []:production:xyz123etc.... Which projects the token has access to can be found on the API Tokens page in the Unleash admin UI.
      3. Single project access - Tokens that lead with a project name are bound to the specified project and environment. For example, my_fullstack_app:production:xyz123etc... will only have access to flags in the "my_fullstack_app" project as set in the production environment.
    4. When using a gradual rollout strategy, be mindful of the stickiness value. When evaluating a flag, if the provided context does not include the field used in the stickiness configuration, the gradual rollout strategy will be evaluated to false and therefore it will not be returned by the API.
    5. Feature activation strategies may have constraints, segments, and rules that can be combined in different ways that can lead to complex scenarios. Try using the Playground to verify that the feature is properly configured and responding as expected.
    - + \ No newline at end of file