Mirrors/unleash.unleash
1
0
Fork 0
mirror of https://github.com/Unleash/unleash.git synced 2025-03-18 00:19:49 +01:00
Code Issues Projects Releases Wiki Activity

Merge pull request #1474 from Unleash/docs/segments-reference-docs

Browse Source 
Add reference and API docs for segments
This commit is contained in:
Thomas Heartman 2022-04-04 15:06:01 +02:00 committed by GitHub
commit f64d2cb768
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
7 changed files with 569 additions and 27 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

72
website/.storybook/main.js
View File

@ -1,3 +1,5 @@
const AliasPlugin = require('enhanced-resolve/lib/AliasPlugin');
module.exports = {
stories: [
'../src/**/*.stories.mdx',
@ -19,19 +21,67 @@ module.exports = {
webpackFinal: async (config) => {
const path = require('path');
config.resolve.alias = {
...config.resolve.alias,
'@site': path.resolve(__dirname, '../'),
'@docusaurus': path.resolve(
const docusaurusPath = (...paths) =>
path.resolve(
__dirname,
'../',
'node_modules',
'@docusaurus',
'core',
'lib',
'client',
'exports',
...paths,
);
config.resolve.plugins = [
// add a "layered" approach to theme resolution that matches
// Docusaurus' theme resolution:
// https://docusaurus.io/docs/2.0.0-beta.17/advanced/client#theme-aliases
//
// First, check to see if the referenced component has
// been swizzled and exists in `../src/theme`.
//
// If it's not there, check the `theme-classic/lib-next/theme` directory in
// `node_modules`.
//
// Finally, if it's not found anywhere else, check the
// `theme-fallback` directory.
new AliasPlugin(
'described-resolve',
[
{
name: '@theme',
alias: [
path.resolve(__dirname, '../', 'src', 'theme'),
docusaurusPath(
'theme-classic',
'lib-next',
'theme',
),
docusaurusPath(
'core',
'lib',
'client',
'theme-fallback',
),
],
},
],
'resolve',
),
];
config.resolve.alias = {
...config.resolve.alias,
'@site': path.resolve(__dirname, '../'),
'@docusaurus/theme-common': docusaurusPath(
'theme-common',
'src',
'index.ts',
),
'@docusaurus/utils-common': docusaurusPath('utils-common', 'lib'),
'@docusaurus/plugin-content-docs': docusaurusPath(
'plugin-content-docs',
'src',
),
'@docusaurus': docusaurusPath('core', 'lib', 'client', 'exports'),
'@generated': path.resolve(__dirname, '../', '.docusaurus'),
};
@ -44,6 +94,12 @@ module.exports = {
...rule,
exclude: /\.module\.css$/,
};
} else if (rule.test.toString() === '/\\.(mjs|tsx?|jsx?)$/') {
return {
...rule,
// don't exclude docusaurus files
exclude: /node_modules\/(?!@docusaurus)/,
};
} else return rule;
});

364
website/docs/api/admin/segments.mdx Normal file
View File

@ -0,0 +1,364 @@
---
title: /api/admin/segments
---
import ApiRequest from '@site/src/components/ApiRequest'
export const basePath = "api/admin/segments"
export const path = (p) => `${basePath}/${p}`
:::info Availability
Segments are an **experimental feature** available to some Unleash Pro and Unleash Enterprise users. [Get in touch](https://slack.unleash.run) if you'd like to help us develop this feature.
:::
:::note
To use the admin API, you'll need to [create and use an admin API token](../../user_guide/token.md).
:::
The segments API lets you create, read, update, and delete [segments](../../reference/segments.mdx).
## Get all segments
Retrieve all segments that exist in this Unleash instance. Returns a list of [segment objects](#segment-type-description).
<ApiRequest verb="Get" url={basePath} title="Retrieve all existing segments."/>
<details>
<summary>Example responses</summary>
### 200 OK
``` json
[
{
"id": 1,
"name": "my-segment",
"description": "a segment description",
"constraints": [],
"createdBy": "user@example.com",
"createdAt": "2022-04-01T14:02:25.491Z"
}
]
```
</details>
## Create segment
Create a new segment with the specified configuration.
<ApiRequest verb="post" url={basePath} title="Create a new segment."
payload={{
"name": "my-segment",
"description": "a segment description",
"constraints": []
}}
/>
<details>
<summary>Example responses</summary>
### 201 Created
The segment was successfully created. This response has no body.
### 400 Bad Request
A segment with the provided name already exists.
</details>
### Payload structure
Use a JSON object with the following properties to create a new segment.
| Property | Type | Required | Description | Example value |
|---------------|--------------------------------------------|----------|----------------------------------|--------------------------------------------------|
| `name` | string | Yes | The name of the segment. | `"mobile-users"` |
| `description` | string | No | A description of the segment. | `"This segment is for users on mobile devices."` |
| `constraints` | list of [constraint objects](#constraint-type-description) | Yes | The constraints in this segment. | `[]` |
## Get segment by ID
Retrieves the segment with the specified ID.
<ApiRequest verb="Get" url={path("<segment-id>")} title="Retrieve the segment with the provided ID."/>
<details>
<summary>Example responses</summary>
### 200 OK
``` json
{
"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.
</details>
## Update an existing segment
Replace the data of the specified segment with the provided payload.
<ApiRequest verb="put" url={path("<segment-id>")} title="Update a segment with new data."
payload={{
"name": "my-segment",
"description": "this is a newly provided description.",
"constraints": []
}}
/>
<details>
<summary>Example responses</summary>
### 204 No Content
The update was successful. This response has no body.
### 404 Not Found
No segment with the provided ID exists.
</details>
## Delete a segment
Delete the request with the specified ID.
<ApiRequest verb="delete" url={path("<segment-id>")} title="Delete a segment." />
<details>
<summary>Example responses</summary>
### 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.
</details>
## List strategies that use a specific segment
Retrieve all strategies that use the specified segment. Returns a list of [activation strategy objects](#activation-strategy-type-description).
<ApiRequest verb="Get" url={path("<segment-id>/strategies")} title="Retrieve all activation strategies that use the specified segment."/>
<details>
<summary>Example responses</summary>
### 200 OK
``` json
[
{
"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.
</details>
## List segments applied to a specific strategy
Retrieve all segments that are applied to the specified strategy. Returns a list of [segment objects](#segment-type-description).
<ApiRequest verb="Get" url={path("strategies/<strategy-id>")} title="Retrieve all segments that are used by the specified strategy."/>
<details>
<summary>Example responses</summary>
### 200 OK
``` json
[
{
"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.
</details>
## Replace activation strategy segments
Replace the segments applied to the specified activation strategy with the provided segment list.
<ApiRequest verb="post" url={path("strategies")} title="Replace the segments to the specified strategy."
payload={{
"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".
``` json
{
"projectId": "my-project",
"strategyId": "my-strategy",
"environmentId": "development",
"segmentIds": []
}
```
<details>
<summary>Example responses</summary>
### 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.
</details>
### Payload structure
Use a JSON object with the following properties to update the list of applied segments.
| Property | Type | Required | Description | Example value |
|-----------------|-------------------------------|----------|---------------------------------------------------|-----------------|
| `projectId` | string | Yes | The ID of the feature toggle's project. | `"my-project"` |
| `strategyId` | string | Yes | The ID of the strategy. | `"my-strategy"` |
| `environmentId` | string | Yes | The ID of the environment. | `"development"` |
| `segmentIds` | list of segment IDs (numbers) | Yes | The 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 {#segment-type-description}
#### Example
``` json
{
"id": 12054,
"name": "segment name",
"description": "segment description",
"constraints": [],
"createdBy": "you@example.com",
"createdAt": "2022-05-23T15:45:22.000Z"
}
```
#### Description
| Property | Type | Required | Description | Example value |
|---------------|------------------------------------------------------------|----------|---------------------------------------------------------------------------|----------------------------------|
| `id` | number | Yes | The segment's ID. | `546` |
| `name` | string | Yes | The segment's name | `"my-segment"` |
| `description` | string | No | An optional description of the segment. | `"segment description"` |
| `constraints` | list of [constraint objects](#constraint-type-description) | Yes | The list of constraint objects in the segment. | `[]` |
| `createdBy` | string | No | An identifier for who created the segment. | `"you@example.com"` |
| `createdAt` | timestamp string | Yes | The time when the segment was created. Format: `YYYY-MM-DDThh:mm:ss.sTZD` | `"2022-04-23T13:56:24.45+01:00"` |
### Constraint {#constraint-type-description}
#### Example
```json
{
"contextName": "appName",
"operator": "STR_CONTAINS",
"values": [],
"inverted": false,
"caseInsensitive": false
}
```
#### Description
:::note `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](../../advanced/strategy-constraints.md) for more information on what operators support what number of values.
:::
| Property | Type | Required | Description | Example value |
|-------------------|-----------------------------------------------------------------------------------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------|
| `contextName` | string | Yes | The name of the context field targeted by the constraint. | `"myContextField"` |
| `operator` | string, the name of one of the [constraint operators](../../advanced/strategy-constraints.md) | Yes | The operator to apply to the context field. | `"DATE_BEFORE"` |
| `values` | a list of strings | Yes | The list of values to apply the constraint operator to. | `["value a", "value b"]` |
| `value` | string | No | The value to apply the constraint operator to. | `"15"` |
| `inverted` | boolean | No | Whether the result of [the constraint will be negated or not](../../advanced/strategy-constraints.md#constraint-negation). | `false` |
| `caseInsensitive` | boolean string | No | Whether the constraint operator is case sensitive or not. Only [applies to some string-based operators](../../advanced/strategy-constraints.md#string-operators). | `false` |
### Activation strategy {#activation-strategy-type-description}
#### Example
``` json
{
"id": "64fbe72b-d107-4b26-b6b8-4fead08d286c",
"environment": "development",
"featureName": "my-feature",
"projectId": "my-project",
"strategyName": "flexibleRollout"
}
```
#### Description
| Property | Type | Required | Description | Example value |
|----------------|---------------------------------------------------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------|
| `id` | GUID string | No | The ID of the strategy. | `"64fbe72b-d107-4b26-b6b8-4fead08d286c"` |
| `environment` | string | Yes | The name of the strategy's environment. | `"development"` |
| `featureName` | string | Yes | The name of the feature the strategy is applied to. | `"my-feature"` |
| `projectId` | string | Yes | The name of the current project. | `"my-project"` |
| `strategyName` | string | Yes | The name of the strategy. | `"flexibleRollout"` |

39
website/docs/reference/segments.mdx Normal file
View File

@ -0,0 +1,39 @@
---
title: Segments
---
:::info Availability
Segments are an **experimental feature** available to some Unleash Pro and Unleash Enterprise users. [Get in touch](https://slack.unleash.run) if you'd like to help us develop this feature.
:::
A **segment** is a reusable collection of [strategy constraints](../advanced/strategy-constraints.md).
Like with strategy constraints, you apply segments to [feature toggle activation strategies](../user_guide/activation-strategies.md).
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 thereof.
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 toggles 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
## 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*.
## Creating, updating, and deleting segments
Segments can be created, edited, and deleted from the segments page in the admin UI or via the API (see the [segments API documentation](../api/admin/segments.mdx)).
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.
[image of the segments page and the segments item in the menu?]

2
website/package.json
View File

@ -62,6 +62,8 @@
"@storybook/testing-library": "^0.0.9",
"@tsconfig/docusaurus": "^1.0.4",
"babel-loader": "^8.2.3",
"enhanced-resolve": "^5.9.2",
"react-router": "^6.3.0",
"storybook-addon-root-attribute": "^1.0.2",
"typescript": "^4.6.2"
}

2
website/sidebars.js
View File

@ -141,6 +141,7 @@ module.exports = {
'api/admin/features-archive',
'api/admin/metrics',
'api/admin/projects',
'api/admin/segments',
'api/admin/state',
'api/admin/strategies',
'api/admin/user-admin',
@ -255,6 +256,7 @@ module.exports = {
'advanced/toggle_variants',
'user_guide/projects',
'user_guide/rbac',
'reference/segments',
'advanced/enterprise-authentication',
'advanced/stickiness',
'advanced/strategy_constraints',

55
website/src/components/ApiRequest/ApiRequest.stories.jsx Normal file
View File

@ -0,0 +1,55 @@
import React from 'react';
import Component from './index';
import Layout from '@theme/Layout';
import { BrowserRouter } from 'react-router-dom';
export default {
title: 'API request component',
component: Component,
};
const Template = (args) => (
<BrowserRouter>
<Layout>
<Component {...args} />
</Layout>
</BrowserRouter>
);
export const GET = Template.bind({});
GET.args = {
verb: 'get',
url: 'api/admin/segments',
title: 'List all segments (example).',
};
export const POST = Template.bind({});
POST.args = {
verb: 'post',
payload: { name: '<feature-toggle-name>', impressionData: true },
url: 'api/admin/projects/<project-id>/features',
title: 'Create a feature toggle with impression data enabled. (example)',
};
export const PUT = Template.bind({});
PUT.args = {
verb: 'put',
payload: { name: '<feature-toggle-name>', impressionData: true },
url: 'api/admin/projects/<project-id>/features/<feature-id>',
title: 'Create a feature toggle with impression data enabled (example).',
};
export const PATCH = Template.bind({});
PATCH.args = {
verb: 'patch',
payload: [{ op: 'replace', path: '/impressionData', value: true }],
url: 'api/admin/projects/<project-id>/features/<feature-toggle-name>',
title: 'Enable impression data on an existing toggle (example).',
};
export const DELETE = Template.bind({});
DELETE.args = {
verb: 'delete',
url: 'api/admin/projects/<project-id>/features/<feature-toggle-id>',
title: 'Create a feature toggle with impression data enabled.',
};

62
website/src/components/ApiRequest.jsx → website/src/components/ApiRequest/index.tsx
View File

@ -17,40 +17,64 @@ import CodeBlock from '@theme/CodeBlock';
const indentation = 2;
const Component = ({ verb, payload, url, title }) => {
type Props = {
verb: string,
payload?: any,
url: string,
title?: string
}
const Component: React.FC<Props> = ({ verb, payload, url, title }) => {
const verbUpper = verb?.toUpperCase() || '';
const prettyPayload = JSON.stringify(payload, null, indentation);
const httpBlock = (payload ? `
${verbUpper} <unleash-url>/${url}
Authorization: <API-token>
content-type: application/json
${prettyPayload}` :`
${verbUpper} <unleash-url>/${url}
Authorization: <API-token>
content-type: application/json`).trim()
const curlBlock = (payload ? `
curl -H "Content-Type: application/json" \\
-H "Authorization: <API-token>" \\
-X ${verbUpper} \\
-d '${prettyPayload}' \\
<unleash-url>/${url}` : `
curl -H "Content-Type: application/json" \\
-H "Authorization: <API-token>" \\
-X ${verbUpper} \\
<unleash-url>/${url}` ).trim()
const httpieBlock = (payload ?
`echo '${prettyPayload}' \\
| http ${verbUpper} \\
<unleash-url>/${url} \\
Authorization:<API-token>`
: `
http ${verbUpper} \\
<unleash-url>/${url} \\
Authorization:<API-token>`.trim()
).trim()
return (
<Tabs groupId="api-request">
<TabItem value="http" label="HTTP">
<CodeBlock language="http" title={title}>
{`
${verbUpper} <unleash-url>/${url}
Authorization: <API-token>
content-type: application/json
${prettyPayload}
`.trim()}
{httpBlock}
</CodeBlock>
</TabItem>
<TabItem value="curl" label="cURL">
<CodeBlock language="bash" title={title}>
{`
curl -H "Content-Type: application/json" \\
-H "Authorization: <API-token>" \\
-X ${verbUpper} \\
-d '${prettyPayload}' \\
<unleash-url>/${url}
`.trim()}
{curlBlock}
</CodeBlock>
</TabItem>
<TabItem value="httpie" label="HTTPie">
<CodeBlock language="bash" title={title}>
{`echo '${prettyPayload}' \\
| http ${verbUpper} \\
<unleash-url>/${url} \\
Authorization:<API-token>`.trim()}
{httpieBlock}
</CodeBlock>
</TabItem>
</Tabs>