1
0
mirror of https://github.com/Unleash/unleash.git synced 2024-12-22 19:07:54 +01:00

docs: new variants per environment (#2590)

## About the changes
Documentation about feature toggle variants per environment

## Discussion points
The version when this will be available is still to be defined.

---------

Co-authored-by: Thomas Heartman <thomas@getunleash.ai>
This commit is contained in:
Gastón Fournier 2023-02-24 15:25:03 +01:00 committed by GitHub
parent 94bfb757d6
commit 291bcb4a0f
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
6 changed files with 88 additions and 8 deletions

View File

@ -65,6 +65,10 @@ export default class VariantsController extends Controller {
handler: this.getVariants,
middleware: [
openApiService.validPath({
summary: 'Retrieve variants for a feature (deprecated) ',
description:
'(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](https://docs.getunleash.io/reference/environments) as the source of truth. If more than one production environment is found, the first one will be used.',
deprecated: true,
tags: ['Features'],
operationId: 'getFeatureVariants',
responses: {
@ -80,6 +84,11 @@ export default class VariantsController extends Controller {
handler: this.patchVariants,
middleware: [
openApiService.validPath({
summary:
"Apply a patch to a feature's variants (in all environments).",
description: `Apply a list of patches patch to the specified feature's variants. The patch objects should conform to the [JSON-patch format (RFC 6902)](https://www.rfc-editor.org/rfc/rfc6902).
**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](/docs/reference/api/unleash/patch-environments-feature-variants.api.mdx), which **is** an atomic operation.`,
tags: ['Features'],
operationId: 'patchFeatureVariants',
requestBody: createRequestSchema('patchesSchema'),
@ -96,6 +105,16 @@ export default class VariantsController extends Controller {
handler: this.overwriteVariants,
middleware: [
openApiService.validPath({
summary:
'Create (overwrite) variants for a feature toggle in all environments',
description: `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\``,
tags: ['Features'],
operationId: 'overwriteFeatureVariants',
requestBody: createRequestSchema('variantsSchema'),
@ -112,6 +131,8 @@ export default class VariantsController extends Controller {
handler: this.getVariantsOnEnv,
middleware: [
openApiService.validPath({
summary: 'Get variants for a feature in an environment',
description: `Returns the variants for a feature in a specific environment. If the feature has no variants it will return an empty array of variants`,
tags: ['Features'],
operationId: 'getEnvironmentFeatureVariants',
responses: {
@ -127,6 +148,8 @@ export default class VariantsController extends Controller {
handler: this.patchVariantsOnEnv,
middleware: [
openApiService.validPath({
summary: "Patch a feature's variants in an environment",
description: `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)](https://www.rfc-editor.org/rfc/rfc6902).`,
tags: ['Features'],
operationId: 'patchEnvironmentsFeatureVariants',
requestBody: createRequestSchema('patchesSchema'),
@ -143,6 +166,16 @@ export default class VariantsController extends Controller {
handler: this.overwriteVariantsOnEnv,
middleware: [
openApiService.validPath({
summary:
'Create (overwrite) variants for a feature in an environment',
description: `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\``,
tags: ['Features'],
operationId: 'overwriteEnvironmentFeatureVariants',
requestBody: createRequestSchema('variantsSchema'),

View File

@ -6815,6 +6815,7 @@ If the provided project does not exist, the list of events will be empty.",
},
"/api/admin/projects/{projectId}/features/{featureName}/environments/{environment}/variants": {
"get": {
"description": "Returns the variants for a feature in a specific environment. If the feature has no variants it will return an empty array of variants",
"operationId": "getEnvironmentFeatureVariants",
"parameters": [
{
@ -6854,11 +6855,13 @@ If the provided project does not exist, the list of events will be empty.",
"description": "featureVariantsSchema",
},
},
"summary": "Get variants for a feature in an environment",
"tags": [
"Features",
],
},
"patch": {
"description": "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)](https://www.rfc-editor.org/rfc/rfc6902).",
"operationId": "patchEnvironmentsFeatureVariants",
"parameters": [
{
@ -6909,11 +6912,20 @@ If the provided project does not exist, the list of events will be empty.",
"description": "featureVariantsSchema",
},
},
"summary": "Patch a feature's variants in an environment",
"tags": [
"Features",
],
},
"put": {
"description": "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\`",
"operationId": "overwriteEnvironmentFeatureVariants",
"parameters": [
{
@ -6964,6 +6976,7 @@ If the provided project does not exist, the list of events will be empty.",
"description": "featureVariantsSchema",
},
},
"summary": "Create (overwrite) variants for a feature in an environment",
"tags": [
"Features",
],
@ -7031,6 +7044,8 @@ If the provided project does not exist, the list of events will be empty.",
},
"/api/admin/projects/{projectId}/features/{featureName}/variants": {
"get": {
"deprecated": true,
"description": "(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](https://docs.getunleash.io/reference/environments) as the source of truth. If more than one production environment is found, the first one will be used.",
"operationId": "getFeatureVariants",
"parameters": [
{
@ -7062,11 +7077,15 @@ If the provided project does not exist, the list of events will be empty.",
"description": "featureVariantsSchema",
},
},
"summary": "Retrieve variants for a feature (deprecated) ",
"tags": [
"Features",
],
},
"patch": {
"description": "Apply a list of patches patch to the specified feature's variants. The patch objects should conform to the [JSON-patch format (RFC 6902)](https://www.rfc-editor.org/rfc/rfc6902).
⚠️ **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](/docs/reference/api/unleash/patch-environments-feature-variants.api.mdx), which **is** an atomic operation.",
"operationId": "patchFeatureVariants",
"parameters": [
{
@ -7109,11 +7128,20 @@ If the provided project does not exist, the list of events will be empty.",
"description": "featureVariantsSchema",
},
},
"summary": "Apply a patch to a feature's variants (in all environments).",
"tags": [
"Features",
],
},
"put": {
"description": "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\`",
"operationId": "overwriteFeatureVariants",
"parameters": [
{
@ -7156,6 +7184,7 @@ If the provided project does not exist, the list of events will be empty.",
"description": "featureVariantsSchema",
},
},
"summary": "Create (overwrite) variants for a feature toggle in all environments",
"tags": [
"Features",
],

View File

@ -611,7 +611,15 @@ Transfer-Encoding: chunked
### Put variants for Feature Toggle {#update-variants}
<ApiRequest verb="put" url="api/admin/projects/:projectId/features/:featureName/variants" title="Create (overwrite) variants for a feature toggle (example data)" payload={[
:::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](#update-variants-per-environment) instead.
:::
<ApiRequest verb="put" url="api/admin/projects/:projectId/features/:featureName/variants" title="Create (overwrite) variants for a feature toggle in all environments (example data)" payload={[
{
"name": "variant1",
"weightType": "fix",
@ -697,7 +705,15 @@ Content-Type: application/json; charset=utf-8
### PATCH variants for a feature toggle
<ApiRequest verb="patch" url="api/admin/projects/:projectId/features/:featureName/variants" title="Patch variants for a feature toggle (example data)" payload={[{"op": "add", "path": "/1", "value": {
:::caution
This API documentation is no longer maintained. You should use the [OpenAPI docs for this endpoint](/docs/reference/api/unleash/overwrite-feature-variants.api.mdx) 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](/docs/reference/api/unleash/overwrite-feature-variants-on-environments.api.mdx) instead.
:::
<ApiRequest verb="patch" url="api/admin/projects/:projectId/features/:featureName/variants" title="Patch variants for a feature toggle in all environments (example data)" payload={[{"op": "add", "path": "/1", "value": {
"name": "new-variant",
"weightType": "fix",
"weight": 200

View File

@ -1,10 +1,12 @@
---
title: Feature Toggle Variants
---
<div class="alert alert--info" role="alert">
<em>Feature toggle variants</em> were introduced in <em>Unleash v3.2.0</em>.
</div>
<br/>
:::info 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.
@ -12,12 +14,12 @@ Variants facilitate A/B testing and experimentation by letting you create contro
## 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.
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. When working with a toggle with variants in a client, you will typically use the variant's name to find out which variant it is.
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**:

Binary file not shown.

Before

Width:  |  Height:  |  Size: 93 KiB

After

Width:  |  Height:  |  Size: 47 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 105 KiB

After

Width:  |  Height:  |  Size: 42 KiB