From e37714d61a3e64cf455dde127027cff8e95305e3 Mon Sep 17 00:00:00 2001
From: Thomas Heartman <thomas@getunleash.ai>
Date: Wed, 30 Mar 2022 12:31:51 +0200
Subject: [PATCH 01/31] docs: First draft of segments reference doc
---
website/docs/reference/segments.mdx | 40 +++++++++++++++++++++++++++++
website/sidebars.js | 1 +
2 files changed, 41 insertions(+)
create mode 100644 website/docs/reference/segments.mdx
diff --git a/website/docs/reference/segments.mdx b/website/docs/reference/segments.mdx
new file mode 100644
index 0000000000..660500d2e3
--- /dev/null
+++ b/website/docs/reference/segments.mdx
@@ -0,0 +1,40 @@
+---
+title: Segments
+---
+
+:::info Availability
+Strategy constraints are available to Unleash Pro and Enterprise users from Unleash 4.10 and onwards.
+:::
+
+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.
+
+
+## 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.
+
+## 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/feature-toggles-api-v2.md)).
+
+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?]
+
+## When to use segments
+
+Segments let you create user groups based on data available in the Unleash context.
+These groups can be as simple or 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.
+
+If you need to keep time-based feature availability in sync across, you can use segments to achieve this too. For instance, you could create a "Black Friday" segment which is only satisfied on that specific Friday and use that to synchronize the availability of a number of related features.
diff --git a/website/sidebars.js b/website/sidebars.js
index a5c0f86f93..d99dfd3b03 100644
--- a/website/sidebars.js
+++ b/website/sidebars.js
@@ -255,6 +255,7 @@ module.exports = {
'advanced/toggle_variants',
'user_guide/projects',
'user_guide/rbac',
+ 'reference/segments',
'advanced/enterprise-authentication',
'advanced/stickiness',
'advanced/strategy_constraints',
From 3440b4f42a0edbd523e42f5c0457970d23775f2c Mon Sep 17 00:00:00 2001
From: Thomas Heartman <thomas@getunleash.ai>
Date: Wed, 30 Mar 2022 16:01:07 +0200
Subject: [PATCH 02/31] docs: add segments api placeholder
---
website/docs/api/admin/segments.mdx | 20 ++++++++++++++++++++
website/sidebars.js | 1 +
2 files changed, 21 insertions(+)
create mode 100644 website/docs/api/admin/segments.mdx
diff --git a/website/docs/api/admin/segments.mdx b/website/docs/api/admin/segments.mdx
new file mode 100644
index 0000000000..6ef8883ab6
--- /dev/null
+++ b/website/docs/api/admin/segments.mdx
@@ -0,0 +1,20 @@
+---
+title: /api/admin/segments
+---
+export const basePath = "/api/admin/segments"
+
+### Get all segments: `GET /{{{basePath}}}`
+
+### Create segment: `POST /`
+
+### Get segment by id: `GET /:id`
+
+### Update segment by id: `PUT /:id`
+
+### Delete segment by id: `DELETE /:id`
+
+### List strategies that use a specific segment: `GET /:id/strategies`
+
+### List segments applied to a specific strategy: `GET /strategies/:strategyId`
+
+### Replace activation strategy segments `POST /strategies/:strategyId`
diff --git a/website/sidebars.js b/website/sidebars.js
index d99dfd3b03..1a0b97275c 100644
--- a/website/sidebars.js
+++ b/website/sidebars.js
@@ -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',
From 032176576b1748b83eebfabc8cb351844099de42 Mon Sep 17 00:00:00 2001
From: Thomas Heartman <thomas@getunleash.ai>
Date: Fri, 1 Apr 2022 13:44:27 +0200
Subject: [PATCH 03/31] chore: add more docusaurus alias resolutions
---
website/.storybook/main.js | 71 ++++++++++++++++++++++++++++++++++++++
website/package.json | 1 +
2 files changed, 72 insertions(+)
diff --git a/website/.storybook/main.js b/website/.storybook/main.js
index a964a6a81e..8c3da7bff5 100644
--- a/website/.storybook/main.js
+++ b/website/.storybook/main.js
@@ -1,3 +1,5 @@
+const AliasPlugin = require('enhanced-resolve/lib/AliasPlugin');
+
module.exports = {
stories: [
'../src/**/*.stories.mdx',
@@ -19,9 +21,72 @@ module.exports = {
webpackFinal: async (config) => {
const path = require('path');
+ const docusaurusPath = (...paths) =>
+ path.resolve(
+ __dirname,
+ '../',
+ 'node_modules',
+ '@docusaurus',
+ ...paths,
+ );
+
+ config.resolve.plugins = [
+ 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',
+ ),
+ ];
+
+ // const docusaurusAliases = await loadDocusaurusAliases();
+ // console.log(docusaurusAliases);
+
config.resolve.alias = {
...config.resolve.alias,
'@site': path.resolve(__dirname, '../'),
+ '@docusaurus/theme-common': path.resolve(
+ __dirname,
+ '../',
+ 'node_modules',
+ '@docusaurus',
+ 'theme-common',
+ 'src',
+ 'index.ts',
+ ),
+ '@docusaurus/utils-common': path.resolve(
+ __dirname,
+ '../',
+ 'node_modules',
+ '@docusaurus',
+ 'utils-common',
+ 'lib',
+ ),
+ '@docusaurus/plugin-content-docs': path.resolve(
+ __dirname,
+ '../',
+ 'node_modules',
+ '@docusaurus',
+ 'plugin-content-docs',
+ 'src',
+ ),
'@docusaurus': path.resolve(
__dirname,
'../',
@@ -44,6 +109,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;
});
diff --git a/website/package.json b/website/package.json
index 2480968541..0800350fd0 100644
--- a/website/package.json
+++ b/website/package.json
@@ -62,6 +62,7 @@
"@storybook/testing-library": "^0.0.9",
"@tsconfig/docusaurus": "^1.0.4",
"babel-loader": "^8.2.3",
+ "enhanced-resolve": "^5.9.2",
"storybook-addon-root-attribute": "^1.0.2",
"typescript": "^4.6.2"
}
From d167de76d865b0372106d9698af069fc8c53008d Mon Sep 17 00:00:00 2001
From: Thomas Heartman <thomas@getunleash.ai>
Date: Fri, 1 Apr 2022 13:48:26 +0200
Subject: [PATCH 04/31] docs: add stories file for API request component
---
website/package.json | 1 +
.../ApiRequest/ApiRequest.stories.jsx | 56 +++++++++++++++++++
.../{ApiRequest.jsx => ApiRequest/index.tsx} | 2 +-
3 files changed, 58 insertions(+), 1 deletion(-)
create mode 100644 website/src/components/ApiRequest/ApiRequest.stories.jsx
rename website/src/components/{ApiRequest.jsx => ApiRequest/index.tsx} (97%)
diff --git a/website/package.json b/website/package.json
index 0800350fd0..3bc552b185 100644
--- a/website/package.json
+++ b/website/package.json
@@ -63,6 +63,7 @@
"@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"
}
diff --git a/website/src/components/ApiRequest/ApiRequest.stories.jsx b/website/src/components/ApiRequest/ApiRequest.stories.jsx
new file mode 100644
index 0000000000..8a0aff8d9f
--- /dev/null
+++ b/website/src/components/ApiRequest/ApiRequest.stories.jsx
@@ -0,0 +1,56 @@
+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 Step1 = Template.bind({});
+Step1.args = {
+ open: true,
+ seedData: {
+ currentStep: 1,
+ },
+};
+
+export const Step2 = Template.bind({});
+Step2.args = {
+ seedData: {
+ currentStep: 2,
+ },
+ open: true,
+};
+
+export const Step3 = Template.bind({});
+Step3.args = {
+ seedData: {
+ currentStep: 3,
+ },
+ open: true,
+};
+
+export const Step4 = Template.bind({});
+Step4.args = {
+ seedData: {
+ currentStep: 4,
+ },
+ open: true,
+};
+
+export const WithLocalStorage = Template.bind({});
+WithLocalStorage.args = {
+ open: true,
+};
+
+export const Closed = Template.bind({});
diff --git a/website/src/components/ApiRequest.jsx b/website/src/components/ApiRequest/index.tsx
similarity index 97%
rename from website/src/components/ApiRequest.jsx
rename to website/src/components/ApiRequest/index.tsx
index 55bb02886d..725b066959 100644
--- a/website/src/components/ApiRequest.jsx
+++ b/website/src/components/ApiRequest/index.tsx
@@ -22,7 +22,7 @@ const Component = ({ verb, payload, url, title }) => {
const prettyPayload = JSON.stringify(payload, null, indentation);
return (
- <Tabs groupId="api-request">
+ <Tabs>
<TabItem value="http" label="HTTP">
<CodeBlock language="http" title={title}>
{`
From cfbe04272ae4424297da6fbc54ebbcd116537d1d Mon Sep 17 00:00:00 2001
From: Thomas Heartman <thomas@getunleash.ai>
Date: Fri, 1 Apr 2022 15:00:30 +0200
Subject: [PATCH 05/31] feat: make API request component work without payloads
There's been no previous need for GET or DELETE requests, but now that
we do need them, the payload shouldn't show up as `undefined`
---
.../ApiRequest/ApiRequest.stories.jsx | 57 ++++++++--------
website/src/components/ApiRequest/index.tsx | 65 +++++++++++++------
2 files changed, 74 insertions(+), 48 deletions(-)
diff --git a/website/src/components/ApiRequest/ApiRequest.stories.jsx b/website/src/components/ApiRequest/ApiRequest.stories.jsx
index 8a0aff8d9f..257fc77afc 100644
--- a/website/src/components/ApiRequest/ApiRequest.stories.jsx
+++ b/website/src/components/ApiRequest/ApiRequest.stories.jsx
@@ -16,41 +16,40 @@ const Template = (args) => (
</BrowserRouter>
);
-export const Step1 = Template.bind({});
-Step1.args = {
- open: true,
- seedData: {
- currentStep: 1,
- },
+export const GET = Template.bind({});
+GET.args = {
+ verb: 'get',
+ url: 'api/admin/segments',
+ title: 'List all segments (example).',
};
-export const Step2 = Template.bind({});
-Step2.args = {
- seedData: {
- currentStep: 2,
- },
- open: true,
+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 Step3 = Template.bind({});
-Step3.args = {
- seedData: {
- currentStep: 3,
- },
- open: true,
+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 Step4 = Template.bind({});
-Step4.args = {
- seedData: {
- currentStep: 4,
- },
- open: true,
+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 WithLocalStorage = Template.bind({});
-WithLocalStorage.args = {
- open: true,
+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.',
};
-
-export const Closed = Template.bind({});
diff --git a/website/src/components/ApiRequest/index.tsx b/website/src/components/ApiRequest/index.tsx
index 725b066959..0e0bc3caef 100644
--- a/website/src/components/ApiRequest/index.tsx
+++ b/website/src/components/ApiRequest/index.tsx
@@ -17,40 +17,67 @@ import CodeBlock from '@theme/CodeBlock';
const indentation = 2;
-const Component = ({ verb, payload, url, title }) => {
+type Props = {
+ verb: string,
+ payload?: any,
+ url: string,
+ title?: string
+}
+
+type PropsWithoutPayload = Omit<Props, 'payload'>
+
+
+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>
<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>
From fc6ea25ebdc8250b83e4f2f23bfe71cace720779 Mon Sep 17 00:00:00 2001
From: Thomas Heartman <thomas@getunleash.ai>
Date: Fri, 1 Apr 2022 15:46:02 +0200
Subject: [PATCH 06/31] docs: add more endpoint data
---
website/docs/api/admin/segments.mdx | 40 +++++++++++++++++++++++++++--
1 file changed, 38 insertions(+), 2 deletions(-)
diff --git a/website/docs/api/admin/segments.mdx b/website/docs/api/admin/segments.mdx
index 6ef8883ab6..f8ded71efe 100644
--- a/website/docs/api/admin/segments.mdx
+++ b/website/docs/api/admin/segments.mdx
@@ -1,9 +1,45 @@
---
title: /api/admin/segments
---
-export const basePath = "/api/admin/segments"
+import ApiRequest from '@site/src/components/ApiRequest'
+export const basePath = "api/admin/segments"
+export const path = (p) => `api/admin/segments/${p}`
-### Get all segments: `GET /{{{basePath}}}`
+:::info Availability
+The segments API is available to Pro and Enterprise users from Unleash 4.10.
+:::
+
+:::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
+
+<ApiRequest verb="Get" url={basePath} title="Retrieve all existing segments."/>
+
+<details>
+
+<summary>Responses</summary>
+
+##### 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:
+
+``` json
+[
+ {
+ "msg": "A project must have at least one owner."
+ }
+]
+```
+
+</details>
### Create segment: `POST /`
From 5d164db46cb04e756be04e2664f234b284e13559 Mon Sep 17 00:00:00 2001
From: Thomas Heartman <thomas@getunleash.ai>
Date: Fri, 1 Apr 2022 16:03:50 +0200
Subject: [PATCH 07/31] docs: add relevant types for this API
---
website/docs/api/admin/segments.mdx | 28 ++++++++++++++++++++++++++++
1 file changed, 28 insertions(+)
diff --git a/website/docs/api/admin/segments.mdx b/website/docs/api/admin/segments.mdx
index f8ded71efe..fd53b2fa72 100644
--- a/website/docs/api/admin/segments.mdx
+++ b/website/docs/api/admin/segments.mdx
@@ -54,3 +54,31 @@ You tried to remove the only user with the role `owner` in the project:
### List segments applied to a specific strategy: `GET /strategies/:strategyId`
### Replace activation strategy segments `POST /strategies/:strategyId`
+
+## Types
+
+### `ISegment`: segment interface {#isegment}
+
+``` ts
+export interface ISegment {
+ id: number;
+ name: string;
+ description?: string;
+ constraints: IConstraint[];
+ createdBy?: string;
+ createdAt: Date;
+}
+```
+
+### `IConstraint`: constraint interface {#iconstraint}
+
+```ts
+export interface IConstraint {
+ contextName: string;
+ operator: string;
+ values?: string[];
+ value?: string;
+ inverted?: boolean;
+ caseInsensitive?: boolean;
+}
+```
From d88032710b7419e402fcf01ac59bd4095fbed65f Mon Sep 17 00:00:00 2001
From: Thomas Heartman <thomas@getunleash.ai>
Date: Fri, 1 Apr 2022 16:04:10 +0200
Subject: [PATCH 08/31] docs: describe GET /api/admin/segments
---
website/docs/api/admin/segments.mdx | 25 +++++++++++++------------
1 file changed, 13 insertions(+), 12 deletions(-)
diff --git a/website/docs/api/admin/segments.mdx b/website/docs/api/admin/segments.mdx
index fd53b2fa72..e291198fa3 100644
--- a/website/docs/api/admin/segments.mdx
+++ b/website/docs/api/admin/segments.mdx
@@ -13,28 +13,29 @@ The segments API is available to Pro and Enterprise users from Unleash 4.10.
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).
+The segments API lets you create, read, update, and delete [segments](../../reference/segments.mdx). All payload
-### Get all segments
+## Get all segments
+
+Retrieve all segments that exist in this Unleash instance. Returns a list of [segment objects](#isegment).
<ApiRequest verb="Get" url={basePath} title="Retrieve all existing segments."/>
-<details>
+<details open>
-<summary>Responses</summary>
+<summary>Example responses</summary>
-##### 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:
+### 200 OK
``` json
[
{
- "msg": "A project must have at least one owner."
+ "id": 1,
+ "name": "my-segment",
+ "description": "a segment description",
+ "constraints": [],
+ "createdBy": "user id",
+ "createdAt": "2022-04-01T14:02:25.491Z"
}
]
```
From 102438946e2816e4a320598451ff345859980eed Mon Sep 17 00:00:00 2001
From: Thomas Heartman <thomas@getunleash.ai>
Date: Fri, 1 Apr 2022 16:24:05 +0200
Subject: [PATCH 09/31] docs: add POST and GET by ID
---
website/docs/api/admin/segments.mdx | 90 ++++++++++++++++++++++++++---
1 file changed, 82 insertions(+), 8 deletions(-)
diff --git a/website/docs/api/admin/segments.mdx b/website/docs/api/admin/segments.mdx
index e291198fa3..f38a8d186f 100644
--- a/website/docs/api/admin/segments.mdx
+++ b/website/docs/api/admin/segments.mdx
@@ -34,7 +34,7 @@ Retrieve all segments that exist in this Unleash instance. Returns a list of [se
"name": "my-segment",
"description": "a segment description",
"constraints": [],
- "createdBy": "user id",
+ "createdBy": "user@example.com",
"createdAt": "2022-04-01T14:02:25.491Z"
}
]
@@ -42,22 +42,96 @@ Retrieve all segments that exist in this Unleash instance. Returns a list of [se
</details>
-### Create segment: `POST /`
+## Create segment
-### Get segment by id: `GET /:id`
+Create a new segment with the specified configuration.
-### Update segment by id: `PUT /:id`
+<ApiRequest verb="post" url={basePath} title="Create a new segment."
+payload={{
+ "name": "my-segment",
+ "description": "a segment description",
+ "constraints": []
+}}
+/>
-### Delete segment by id: `DELETE /:id`
-### List strategies that use a specific segment: `GET /:id/strategies`
+<details open>
-### List segments applied to a specific strategy: `GET /strategies/:strategyId`
+<summary>Example responses</summary>
-### Replace activation strategy segments `POST /strategies/:strategyId`
+### 200 OK
+
+Contains the newly created segment object.
+
+``` json
+{
+ "id": 1,
+ "name": "my-segment",
+ "description": "a segment description",
+ "constraints": [],
+ "createdBy": "user@example.com",
+ "createdAt": "2022-04-01T14:02:25.491Z"
+}
+```
+
+### 400 Bad request
+
+A segment with the provided name already exists.
+
+</details>
+
+### Payload structure
+
+Use a JSON object with the following parameters to create a new segment.
+
+| Parameter | Type | Required | Description | Example value |
+|---------------|--------------------------------------------|----------|------------------------------------------------|--------------------------------------------------|
+| `name` | string | Yes | The name of the segment. Must be URL friendly. | `"mobile-users"` |
+| `description` | string | No | A description of the segment. | `"This segment is for users on mobile devices."` |
+| `constraints` | list of [constraint objects](#iconstraint) | Yes | The constraints in this segment. | `[]` |
+
+## Get segment by ID
+
+Retrieves the segment with the specified ID.
+<ApiRequest verb="Get" url={`${ basePath }/<segment-id>`} title="Retrieve the segment with the provided ID."/>
+
+<details open>
+
+<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 segment by id: `PUT /:id`
+
+## Delete segment by id: `DELETE /:id`
+
+## List strategies that use a specific segment: `GET /:id/strategies`
+
+## List segments applied to a specific strategy: `GET /strategies/:strategyId`
+
+## Replace activation strategy segments `POST /strategies/:strategyId`
## Types
+### Segment creation payload
+
### `ISegment`: segment interface {#isegment}
``` ts
From e03876286cbe21e3e9126c4890edb2be7a12fa68 Mon Sep 17 00:00:00 2001
From: Thomas Heartman <thomas@getunleash.ai>
Date: Sat, 2 Apr 2022 16:27:09 +0200
Subject: [PATCH 10/31] docs: finish the API docs for segments
---
website/docs/api/admin/segments.mdx | 201 ++++++++++++++++++++++++----
1 file changed, 177 insertions(+), 24 deletions(-)
diff --git a/website/docs/api/admin/segments.mdx b/website/docs/api/admin/segments.mdx
index f38a8d186f..27bb7ca37a 100644
--- a/website/docs/api/admin/segments.mdx
+++ b/website/docs/api/admin/segments.mdx
@@ -21,7 +21,7 @@ Retrieve all segments that exist in this Unleash instance. Returns a list of [se
<ApiRequest verb="Get" url={basePath} title="Retrieve all existing segments."/>
-<details open>
+<details>
<summary>Example responses</summary>
@@ -55,26 +55,15 @@ payload={{
/>
-<details open>
+<details>
<summary>Example responses</summary>
-### 200 OK
+### 201 Created
-Contains the newly created segment object.
+The segment was successfully created. This response has no body.
-``` json
-{
- "id": 1,
- "name": "my-segment",
- "description": "a segment description",
- "constraints": [],
- "createdBy": "user@example.com",
- "createdAt": "2022-04-01T14:02:25.491Z"
-}
-```
-
-### 400 Bad request
+### 400 Bad Request
A segment with the provided name already exists.
@@ -82,9 +71,9 @@ A segment with the provided name already exists.
### Payload structure
-Use a JSON object with the following parameters to create a new segment.
+Use a JSON object with the following properties to create a new segment.
-| Parameter | Type | Required | Description | Example value |
+| Property | Type | Required | Description | Example value |
|---------------|--------------------------------------------|----------|------------------------------------------------|--------------------------------------------------|
| `name` | string | Yes | The name of the segment. Must be URL friendly. | `"mobile-users"` |
| `description` | string | No | A description of the segment. | `"This segment is for users on mobile devices."` |
@@ -95,7 +84,7 @@ Use a JSON object with the following parameters to create a new segment.
Retrieves the segment with the specified ID.
<ApiRequest verb="Get" url={`${ basePath }/<segment-id>`} title="Retrieve the segment with the provided ID."/>
-<details open>
+<details>
<summary>Example responses</summary>
@@ -118,15 +107,163 @@ No segment with the provided ID exists.
</details>
-## Update segment by id: `PUT /:id`
+## Update an existing segment
-## Delete segment by id: `DELETE /:id`
+Replace the data of the specified segment with the provided payload.
-## List strategies that use a specific segment: `GET /:id/strategies`
-## List segments applied to a specific strategy: `GET /strategies/:strategyId`
+<ApiRequest verb="put" url={`${ basePath }/<segment-id>`} title="Update a segment with new data."
+payload={{
+ "name": "my-segment",
+ "description": "this is a newly provided description.",
+ "constraints": []
+}}
+/>
-## Replace activation strategy segments `POST /strategies/:strategyId`
+<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={`${ basePath }/<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](#ifeaturestrategy).
+
+<ApiRequest verb="Get" url={`${basePath}/<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](#isegment).
+
+<ApiRequest verb="Get" url={`${basePath}/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={`${basePath}/strategies`} title="Replace the segments to the specified strategy."
+payload={{
+ "projectId": "my-project",
+ "strategyId": "my-strategy",
+ "environmentId": "development",
+ "segmentIds": []
+}}
+/>
+
+<details>
+
+<summary>Example responses</summary>
+
+### 201 Created
+
+The strategy's list of segments was succesfully 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. | `[]` |
## Types
@@ -157,3 +294,19 @@ export interface IConstraint {
caseInsensitive?: boolean;
}
```
+
+### `IFeatureStrategy`: strategy interface {#ifeaturestrategy}
+
+``` ts
+export interface IFeatureStrategy {
+ id: string;
+ featureName: string;
+ projectId: string;
+ environment: string;
+ strategyName: string;
+ parameters: object;
+ sortOrder?: number;
+ constraints: IConstraint[];
+ createdAt?: Date;
+}
+```
From 3846ad8252b582b6c997ec9b82d34ce1a6187c85 Mon Sep 17 00:00:00 2001
From: Thomas Heartman <thomas@getunleash.ai>
Date: Sat, 2 Apr 2022 16:27:20 +0200
Subject: [PATCH 11/31] fix: re-add the groupId prop for the API request tabs
component.
---
website/src/components/ApiRequest/index.tsx | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/website/src/components/ApiRequest/index.tsx b/website/src/components/ApiRequest/index.tsx
index 0e0bc3caef..6d865657d0 100644
--- a/website/src/components/ApiRequest/index.tsx
+++ b/website/src/components/ApiRequest/index.tsx
@@ -64,7 +64,7 @@ http ${verbUpper} \\
).trim()
return (
- <Tabs>
+ <Tabs groupId="api-request">
<TabItem value="http" label="HTTP">
<CodeBlock language="http" title={title}>
{httpBlock}
From 45dc2c8c337c6e98179ff105854582cf67fe8d69 Mon Sep 17 00:00:00 2001
From: Thomas Heartman <thomas@getunleash.ai>
Date: Sat, 2 Apr 2022 16:27:53 +0200
Subject: [PATCH 12/31] fix: remove redundant heading
---
website/docs/api/admin/segments.mdx | 2 --
1 file changed, 2 deletions(-)
diff --git a/website/docs/api/admin/segments.mdx b/website/docs/api/admin/segments.mdx
index 27bb7ca37a..a7336aef77 100644
--- a/website/docs/api/admin/segments.mdx
+++ b/website/docs/api/admin/segments.mdx
@@ -267,8 +267,6 @@ Use a JSON object with the following properties to update the list of applied se
## Types
-### Segment creation payload
-
### `ISegment`: segment interface {#isegment}
``` ts
From 8eb91fc860992524323540f085ba1ce21a120c0b Mon Sep 17 00:00:00 2001
From: Thomas Heartman <thomas@getunleash.ai>
Date: Sat, 2 Apr 2022 16:28:24 +0200
Subject: [PATCH 13/31] fix(docs): fix the quotes of JSON property in table
---
website/docs/api/admin/segments.mdx | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/website/docs/api/admin/segments.mdx b/website/docs/api/admin/segments.mdx
index a7336aef77..a19c080ecd 100644
--- a/website/docs/api/admin/segments.mdx
+++ b/website/docs/api/admin/segments.mdx
@@ -263,7 +263,7 @@ Use a JSON object with the following properties to update the list of applied se
| `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. | `[]` |
+| `segmentIds` | list of segment IDs (numbers) | Yes | The list of segment IDs to apply to the strategy. | `[]` |
## Types
From facf546df49f427a89bc3aa924e49515087e917f Mon Sep 17 00:00:00 2001
From: Thomas Heartman <thomas@getunleash.ai>
Date: Sat, 2 Apr 2022 16:29:45 +0200
Subject: [PATCH 14/31] docs(fix): fix internal links between segments docs
---
website/docs/api/admin/segments.mdx | 2 +-
website/docs/reference/segments.mdx | 2 +-
2 files changed, 2 insertions(+), 2 deletions(-)
diff --git a/website/docs/api/admin/segments.mdx b/website/docs/api/admin/segments.mdx
index a19c080ecd..aa0a62b38e 100644
--- a/website/docs/api/admin/segments.mdx
+++ b/website/docs/api/admin/segments.mdx
@@ -13,7 +13,7 @@ The segments API is available to Pro and Enterprise users from Unleash 4.10.
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). All payload
+The segments API lets you create, read, update, and delete [segments](../../reference/segments.mdx).
## Get all segments
diff --git a/website/docs/reference/segments.mdx b/website/docs/reference/segments.mdx
index 660500d2e3..880532efeb 100644
--- a/website/docs/reference/segments.mdx
+++ b/website/docs/reference/segments.mdx
@@ -21,7 +21,7 @@ If an activation strategy has a segment *and* additional constraints applied, th
## 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/feature-toggles-api-v2.md)).
+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.
From 79b5582542cc68fff8bda3bb44d717ec26e4c70d Mon Sep 17 00:00:00 2001
From: Thomas Heartman <thomas@getunleash.ai>
Date: Sat, 2 Apr 2022 16:33:51 +0200
Subject: [PATCH 15/31] docs(fix): various typos and abstractions fixed
---
website/docs/api/admin/segments.mdx | 16 ++++++++--------
1 file changed, 8 insertions(+), 8 deletions(-)
diff --git a/website/docs/api/admin/segments.mdx b/website/docs/api/admin/segments.mdx
index aa0a62b38e..9aa8c2a194 100644
--- a/website/docs/api/admin/segments.mdx
+++ b/website/docs/api/admin/segments.mdx
@@ -3,7 +3,7 @@ title: /api/admin/segments
---
import ApiRequest from '@site/src/components/ApiRequest'
export const basePath = "api/admin/segments"
-export const path = (p) => `api/admin/segments/${p}`
+export const path = (p) => `${basePath}/${p}`
:::info Availability
The segments API is available to Pro and Enterprise users from Unleash 4.10.
@@ -82,7 +82,7 @@ Use a JSON object with the following properties to create a new segment.
## Get segment by ID
Retrieves the segment with the specified ID.
-<ApiRequest verb="Get" url={`${ basePath }/<segment-id>`} title="Retrieve the segment with the provided ID."/>
+<ApiRequest verb="Get" url={path("<segment-id>")} title="Retrieve the segment with the provided ID."/>
<details>
@@ -112,7 +112,7 @@ No segment with the provided ID exists.
Replace the data of the specified segment with the provided payload.
-<ApiRequest verb="put" url={`${ basePath }/<segment-id>`} title="Update a segment with new data."
+<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.",
@@ -138,7 +138,7 @@ No segment with the provided ID exists.
Delete the request with the specified ID.
-<ApiRequest verb="delete" url={`${ basePath }/<segment-id>`} title="Delete a segment." />
+<ApiRequest verb="delete" url={path("<segment-id>")} title="Delete a segment." />
<details>
@@ -162,7 +162,7 @@ The segment is being used by at least one strategy and can not be deleted. To de
Retrieve all strategies that use the specified segment. Returns a list of [activation strategy objects](#ifeaturestrategy).
-<ApiRequest verb="Get" url={`${basePath}/<segment-id>/strategies`} title="Retrieve all activation strategies that use the specified segment."/>
+<ApiRequest verb="Get" url={path("<segment-id>/strategies")} title="Retrieve all activation strategies that use the specified segment."/>
<details>
@@ -195,7 +195,7 @@ No segment with the provided id exists.
Retrieve all segments that are applied to the specified strategy. Returns a list of [segment objects](#isegment).
-<ApiRequest verb="Get" url={`${basePath}/strategies/<strategy-id>`} title="Retrieve all segments that are used by the specified strategy."/>
+<ApiRequest verb="Get" url={path("strategies/<strategy-id>")} title="Retrieve all segments that are used by the specified strategy."/>
<details>
@@ -227,7 +227,7 @@ No strategy with the provided id exists.
Replace the segments applied to the specified activation strategy with the provided segment list.
-<ApiRequest verb="post" url={`${basePath}/strategies`} title="Replace the segments to the specified strategy."
+<ApiRequest verb="post" url={path("strategies")} title="Replace the segments to the specified strategy."
payload={{
"projectId": "my-project",
"strategyId": "my-strategy",
@@ -242,7 +242,7 @@ payload={{
### 201 Created
-The strategy's list of segments was succesfully updated.
+The strategy's list of segments was successfully updated.
### 403 Forbidden
From c0228a0ca30f57eb6483189e2bc34e9df29ab827 Mon Sep 17 00:00:00 2001
From: Thomas Heartman <thomas@getunleash.ai>
Date: Sat, 2 Apr 2022 16:39:16 +0200
Subject: [PATCH 16/31] chore: remove unused code
---
website/src/components/ApiRequest/index.tsx | 3 ---
1 file changed, 3 deletions(-)
diff --git a/website/src/components/ApiRequest/index.tsx b/website/src/components/ApiRequest/index.tsx
index 6d865657d0..de29343edb 100644
--- a/website/src/components/ApiRequest/index.tsx
+++ b/website/src/components/ApiRequest/index.tsx
@@ -24,9 +24,6 @@ type Props = {
title?: string
}
-type PropsWithoutPayload = Omit<Props, 'payload'>
-
-
const Component: React.FC<Props> = ({ verb, payload, url, title }) => {
const verbUpper = verb?.toUpperCase() || '';
const prettyPayload = JSON.stringify(payload, null, indentation);
From f59f43bb4c7747aedfafbaaee851a172f4c2a486 Mon Sep 17 00:00:00 2001
From: Thomas Heartman <thomas@getunleash.ai>
Date: Sat, 2 Apr 2022 16:40:37 +0200
Subject: [PATCH 17/31] chore: use `docusaurusPath` function consistently.
---
website/.storybook/main.js | 32 ++++----------------------------
1 file changed, 4 insertions(+), 28 deletions(-)
diff --git a/website/.storybook/main.js b/website/.storybook/main.js
index 8c3da7bff5..4004822abe 100644
--- a/website/.storybook/main.js
+++ b/website/.storybook/main.js
@@ -62,41 +62,17 @@ module.exports = {
config.resolve.alias = {
...config.resolve.alias,
'@site': path.resolve(__dirname, '../'),
- '@docusaurus/theme-common': path.resolve(
- __dirname,
- '../',
- 'node_modules',
- '@docusaurus',
+ '@docusaurus/theme-common': docusaurusPath(
'theme-common',
'src',
'index.ts',
),
- '@docusaurus/utils-common': path.resolve(
- __dirname,
- '../',
- 'node_modules',
- '@docusaurus',
- 'utils-common',
- 'lib',
- ),
- '@docusaurus/plugin-content-docs': path.resolve(
- __dirname,
- '../',
- 'node_modules',
- '@docusaurus',
+ '@docusaurus/utils-common': docusaurusPath('utils-common', 'lib'),
+ '@docusaurus/plugin-content-docs': docusaurusPath(
'plugin-content-docs',
'src',
),
- '@docusaurus': path.resolve(
- __dirname,
- '../',
- 'node_modules',
- '@docusaurus',
- 'core',
- 'lib',
- 'client',
- 'exports',
- ),
+ '@docusaurus': docusaurusPath('core', 'lib', 'client', 'exports'),
'@generated': path.resolve(__dirname, '../', '.docusaurus'),
};
From c8578f06c90a764b46a7e48d74d44b441f7b989c Mon Sep 17 00:00:00 2001
From: Thomas Heartman <thomas@getunleash.ai>
Date: Sat, 2 Apr 2022 16:42:04 +0200
Subject: [PATCH 18/31] chore: remove comment code
---
website/.storybook/main.js | 3 ---
1 file changed, 3 deletions(-)
diff --git a/website/.storybook/main.js b/website/.storybook/main.js
index 4004822abe..87d3dd1406 100644
--- a/website/.storybook/main.js
+++ b/website/.storybook/main.js
@@ -56,9 +56,6 @@ module.exports = {
),
];
- // const docusaurusAliases = await loadDocusaurusAliases();
- // console.log(docusaurusAliases);
-
config.resolve.alias = {
...config.resolve.alias,
'@site': path.resolve(__dirname, '../'),
From 524be02b740a5c2fc20551ad7028ed8516c3ee57 Mon Sep 17 00:00:00 2001
From: Thomas Heartman <thomas@getunleash.ai>
Date: Sat, 2 Apr 2022 16:47:38 +0200
Subject: [PATCH 19/31] docs(docs): document the use of AliasPlugin for theme
resolution
---
website/.storybook/main.js | 12 ++++++++++++
1 file changed, 12 insertions(+)
diff --git a/website/.storybook/main.js b/website/.storybook/main.js
index 87d3dd1406..a80e92f0a6 100644
--- a/website/.storybook/main.js
+++ b/website/.storybook/main.js
@@ -31,6 +31,18 @@ module.exports = {
);
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',
[
From cc670a018cbfb6d539f9ec14834a11c2e49c8b42 Mon Sep 17 00:00:00 2001
From: Thomas Heartman <thomas@getunleash.ai>
Date: Mon, 4 Apr 2022 11:34:53 +0200
Subject: [PATCH 20/31] docs: update segments availability: indicate that it's
experimental
---
website/docs/reference/segments.mdx | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/website/docs/reference/segments.mdx b/website/docs/reference/segments.mdx
index 880532efeb..f18e6adb58 100644
--- a/website/docs/reference/segments.mdx
+++ b/website/docs/reference/segments.mdx
@@ -3,7 +3,7 @@ title: Segments
---
:::info Availability
-Strategy constraints are available to Unleash Pro and Enterprise users from Unleash 4.10 and onwards.
+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).
From 020e94e3585edbd3a173b06c0cfac6addda75e81 Mon Sep 17 00:00:00 2001
From: Thomas Heartman <thomas@getunleash.ai>
Date: Mon, 4 Apr 2022 11:44:03 +0200
Subject: [PATCH 21/31] docs: update segments availability in API docs too
---
website/docs/api/admin/segments.mdx | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/website/docs/api/admin/segments.mdx b/website/docs/api/admin/segments.mdx
index 9aa8c2a194..4dff889ca7 100644
--- a/website/docs/api/admin/segments.mdx
+++ b/website/docs/api/admin/segments.mdx
@@ -6,7 +6,7 @@ export const basePath = "api/admin/segments"
export const path = (p) => `${basePath}/${p}`
:::info Availability
-The segments API is available to Pro and Enterprise users from Unleash 4.10.
+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
From e4c2e8807d70ddcea0e190e5e942cb46c01031ba Mon Sep 17 00:00:00 2001
From: Thomas Heartman <thomas@getunleash.ai>
Date: Mon, 4 Apr 2022 11:44:37 +0200
Subject: [PATCH 22/31] docs: segment names don't need to be url-friendly.
---
website/docs/api/admin/segments.mdx | 10 +++++-----
1 file changed, 5 insertions(+), 5 deletions(-)
diff --git a/website/docs/api/admin/segments.mdx b/website/docs/api/admin/segments.mdx
index 4dff889ca7..771ed03afd 100644
--- a/website/docs/api/admin/segments.mdx
+++ b/website/docs/api/admin/segments.mdx
@@ -73,11 +73,11 @@ A segment with the provided name already exists.
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. Must be URL friendly. | `"mobile-users"` |
-| `description` | string | No | A description of the segment. | `"This segment is for users on mobile devices."` |
-| `constraints` | list of [constraint objects](#iconstraint) | Yes | The constraints in this 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](#iconstraint) | Yes | The constraints in this segment. | `[]` |
## Get segment by ID
From 93b20246a7a752f01b3292855d40c94af273095c Mon Sep 17 00:00:00 2001
From: Thomas Heartman <thomas@getunleash.ai>
Date: Mon, 4 Apr 2022 11:47:13 +0200
Subject: [PATCH 23/31] docs: make note of how to remove all segments from a
strategy
---
website/docs/api/admin/segments.mdx | 13 +++++++++++++
1 file changed, 13 insertions(+)
diff --git a/website/docs/api/admin/segments.mdx b/website/docs/api/admin/segments.mdx
index 771ed03afd..50d9a37eda 100644
--- a/website/docs/api/admin/segments.mdx
+++ b/website/docs/api/admin/segments.mdx
@@ -236,6 +236,19 @@ payload={{
}}
/>
+### 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>
From 971b411db12e3a8c35f4e1166f9bc24e99cac426 Mon Sep 17 00:00:00 2001
From: Thomas Heartman <thomas@getunleash.ai>
Date: Mon, 4 Apr 2022 11:48:59 +0200
Subject: [PATCH 24/31] docs: explain that with multiple segments, all must be
satisfied.
---
website/docs/reference/segments.mdx | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/website/docs/reference/segments.mdx b/website/docs/reference/segments.mdx
index f18e6adb58..633e82257e 100644
--- a/website/docs/reference/segments.mdx
+++ b/website/docs/reference/segments.mdx
@@ -17,7 +17,7 @@ If you update the segment, the changes will affect every strategy that uses that
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.
+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
From 14cb523c91b78ec587e11028ce562b99ed325fe7 Mon Sep 17 00:00:00 2001
From: Thomas Heartman <thomas@getunleash.ai>
Date: Mon, 4 Apr 2022 12:16:32 +0200
Subject: [PATCH 25/31] docs: expand on time-based strategies with segments
---
website/docs/reference/segments.mdx | 8 +++++---
1 file changed, 5 insertions(+), 3 deletions(-)
diff --git a/website/docs/reference/segments.mdx b/website/docs/reference/segments.mdx
index 633e82257e..172d084bec 100644
--- a/website/docs/reference/segments.mdx
+++ b/website/docs/reference/segments.mdx
@@ -30,11 +30,13 @@ A segment that is in use **cannot** be deleted. If you'd like to delete a segmen
## When to use segments
Segments let you create user groups based on data available in the Unleash context.
-These groups can be as simple or complex as you want to make them.
+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.
+or any combination thereof.
-If you need to keep time-based feature availability in sync across, you can use segments to achieve this too. For instance, you could create a "Black Friday" segment which is only satisfied on that specific Friday and use that to synchronize the availability of a number of related features.
+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
From d9aae95c26272f916b3d717b21398f7a1e33851d Mon Sep 17 00:00:00 2001
From: Thomas Heartman <thomas@getunleash.ai>
Date: Mon, 4 Apr 2022 12:32:03 +0200
Subject: [PATCH 26/31] docs: move when to use segments to top of document
---
website/docs/reference/segments.mdx | 25 +++++++++++--------------
1 file changed, 11 insertions(+), 14 deletions(-)
diff --git a/website/docs/reference/segments.mdx b/website/docs/reference/segments.mdx
index 172d084bec..ee1c0b6044 100644
--- a/website/docs/reference/segments.mdx
+++ b/website/docs/reference/segments.mdx
@@ -12,6 +12,17 @@ Like with strategy constraints, you apply segments to [feature toggle activation
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
@@ -26,17 +37,3 @@ Segments can be created, edited, and deleted from the segments page in the admin
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?]
-
-## When to use segments
-
-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
From bf9f9e9d6dfca501e2cc3a49c4ee8e3e20287a79 Mon Sep 17 00:00:00 2001
From: Thomas Heartman <thomas@getunleash.ai>
Date: Mon, 4 Apr 2022 13:55:53 +0200
Subject: [PATCH 27/31] docs: update return types to use JSON examples instead
of TS
---
website/docs/api/admin/segments.mdx | 107 +++++++++++++++++++---------
1 file changed, 73 insertions(+), 34 deletions(-)
diff --git a/website/docs/api/admin/segments.mdx b/website/docs/api/admin/segments.mdx
index 50d9a37eda..613d1c0312 100644
--- a/website/docs/api/admin/segments.mdx
+++ b/website/docs/api/admin/segments.mdx
@@ -17,7 +17,7 @@ The segments API lets you create, read, update, and delete [segments](../../refe
## Get all segments
-Retrieve all segments that exist in this Unleash instance. Returns a list of [segment objects](#isegment).
+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."/>
@@ -77,7 +77,7 @@ Use a JSON object with the following properties to create a new segment.
|---------------|--------------------------------------------|----------|----------------------------------|--------------------------------------------------|
| `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](#iconstraint) | Yes | The constraints in this segment. | `[]` |
+| `constraints` | list of [constraint objects](#constraint-type-description) | Yes | The constraints in this segment. | `[]` |
## Get segment by ID
@@ -160,7 +160,7 @@ The segment is being used by at least one strategy and can not be deleted. To de
## List strategies that use a specific segment
-Retrieve all strategies that use the specified segment. Returns a list of [activation strategy objects](#ifeaturestrategy).
+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."/>
@@ -193,7 +193,7 @@ 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](#isegment).
+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."/>
@@ -280,44 +280,83 @@ Use a JSON object with the following properties to update the list of applied se
## Types
-### `ISegment`: segment interface {#isegment}
+The segments API exposes the following types:
-``` ts
-export interface ISegment {
- id: number;
- name: string;
- description?: string;
- constraints: IConstraint[];
- createdBy?: string;
- createdAt: Date;
+### 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"
}
```
-### `IConstraint`: constraint interface {#iconstraint}
+#### Description
-```ts
-export interface IConstraint {
- contextName: string;
- operator: string;
- values?: string[];
- value?: string;
- inverted?: boolean;
- caseInsensitive?: boolean;
+| 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
}
```
-### `IFeatureStrategy`: strategy interface {#ifeaturestrategy}
+#### Description
-``` ts
-export interface IFeatureStrategy {
- id: string;
- featureName: string;
- projectId: string;
- environment: string;
- strategyName: string;
- parameters: object;
- sortOrder?: number;
- constraints: IConstraint[];
- createdAt?: Date;
+:::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": "strategy-id",
+ "name": "flexibleRollout",
+ "constraints": [],
+ "parameters": {}
}
```
+
+#### Description
+
+| Property | Type | Required | Description | Example value |
+|----------------|---------------------------------------------------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------|
+| `id` | string | No | The ID of the strategy. | `"strategy id"` |
+| `name` | string | Yes | The name of the activation strategy. | `flexibleRollout` |
+| `constraints` | a list of [constraint objects](#constraint-type-description). | No | The list of constraints applied to this strategy. | `[]` |
+| `parameters` | object | Yes | A list of parameters for the strategy. | `{}` |
From 683e33915f06fdd4b9612b8149ecb2e2f8a46132 Mon Sep 17 00:00:00 2001
From: Thomas Heartman <thomas@getunleash.ai>
Date: Mon, 4 Apr 2022 14:33:38 +0200
Subject: [PATCH 28/31] docs: update payload for activation strategies
---
website/docs/api/admin/segments.mdx | 27 ++++++++++++++++++---------
1 file changed, 18 insertions(+), 9 deletions(-)
diff --git a/website/docs/api/admin/segments.mdx b/website/docs/api/admin/segments.mdx
index 613d1c0312..24cb76853f 100644
--- a/website/docs/api/admin/segments.mdx
+++ b/website/docs/api/admin/segments.mdx
@@ -345,18 +345,27 @@ Some constraint operators only support single values. If a constraint uses one o
``` json
{
- "id": "strategy-id",
- "name": "flexibleRollout",
+ "id": "64fbe72b-d107-4b26-b6b8-4fead08d286c",
"constraints": [],
- "parameters": {}
+ "environment": "default",
+ "featureName": "my-feature",
+ "parameters": {},
+ "projectId": "my-project",
+ "strategyName": "flexibleRollout",
+ "createdAt": "2022-05-30T20:45:24.000Z"
}
```
#### Description
-| Property | Type | Required | Description | Example value |
-|----------------|---------------------------------------------------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------|
-| `id` | string | No | The ID of the strategy. | `"strategy id"` |
-| `name` | string | Yes | The name of the activation strategy. | `flexibleRollout` |
-| `constraints` | a list of [constraint objects](#constraint-type-description). | No | The list of constraints applied to this strategy. | `[]` |
-| `parameters` | object | Yes | A list of parameters for the strategy. | `{}` |
+| Property | Type | Required | Description | Example value |
+|----------------|---------------------------------------------------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------|
+| `id` | GUID string | No | The ID of the strategy. | `"64fbe72b-d107-4b26-b6b8-4fead08d286c"` |
+| `constraints` | a list of [constraint objects](#constraint-type-description). | No | The list of constraints applied to this strategy. | `[]` |
+| `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"` |
+| `parameters` | object | Yes | Parameters for the strategy. | `{}` |
+| `projectId` | string | Yes | The name of the current project. | `"my-project"` |
+| `strategyName` | string | Yes | The name of the strategy. | `"flexibleRollout"` |
+| `parameters` | 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` |
+| `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"` |
From 6f2a336fc45645cc551ee3077fbdfacaafb55c3e Mon Sep 17 00:00:00 2001
From: Thomas Heartman <thomas@getunleash.ai>
Date: Mon, 4 Apr 2022 14:43:45 +0200
Subject: [PATCH 29/31] docs: simplify activation strategy payload
---
website/docs/api/admin/segments.mdx | 11 ++---------
1 file changed, 2 insertions(+), 9 deletions(-)
diff --git a/website/docs/api/admin/segments.mdx b/website/docs/api/admin/segments.mdx
index 24cb76853f..cae4e74775 100644
--- a/website/docs/api/admin/segments.mdx
+++ b/website/docs/api/admin/segments.mdx
@@ -346,13 +346,10 @@ Some constraint operators only support single values. If a constraint uses one o
``` json
{
"id": "64fbe72b-d107-4b26-b6b8-4fead08d286c",
- "constraints": [],
- "environment": "default",
+ "environment": "development",
"featureName": "my-feature",
- "parameters": {},
"projectId": "my-project",
- "strategyName": "flexibleRollout",
- "createdAt": "2022-05-30T20:45:24.000Z"
+ "strategyName": "flexibleRollout"
}
```
@@ -361,11 +358,7 @@ Some constraint operators only support single values. If a constraint uses one o
| Property | Type | Required | Description | Example value |
|----------------|---------------------------------------------------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------|
| `id` | GUID string | No | The ID of the strategy. | `"64fbe72b-d107-4b26-b6b8-4fead08d286c"` |
-| `constraints` | a list of [constraint objects](#constraint-type-description). | No | The list of constraints applied to this strategy. | `[]` |
| `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"` |
-| `parameters` | object | Yes | Parameters for the strategy. | `{}` |
| `projectId` | string | Yes | The name of the current project. | `"my-project"` |
| `strategyName` | string | Yes | The name of the strategy. | `"flexibleRollout"` |
-| `parameters` | 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` |
-| `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"` |
From 90794fc6ec272e240b967631a242dbf74d9af351 Mon Sep 17 00:00:00 2001
From: Thomas Heartman <thomas@getunleash.ai>
Date: Mon, 4 Apr 2022 14:49:13 +0200
Subject: [PATCH 30/31] docs: add segment ids examples for replacing strategy
segments
---
website/docs/api/admin/segments.mdx | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/website/docs/api/admin/segments.mdx b/website/docs/api/admin/segments.mdx
index cae4e74775..d1c6e7bd4b 100644
--- a/website/docs/api/admin/segments.mdx
+++ b/website/docs/api/admin/segments.mdx
@@ -232,7 +232,7 @@ payload={{
"projectId": "my-project",
"strategyId": "my-strategy",
"environmentId": "development",
- "segmentIds": []
+ "segmentIds": [61, 62, 63, 64]
}}
/>
From 35bd047af9f7fdaed266d9632d003391d6f94dd7 Mon Sep 17 00:00:00 2001
From: Thomas Heartman <thomas@getunleash.ai>
Date: Mon, 4 Apr 2022 14:56:34 +0200
Subject: [PATCH 31/31] docs: reword api return type description
---
website/docs/api/admin/segments.mdx | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/website/docs/api/admin/segments.mdx b/website/docs/api/admin/segments.mdx
index d1c6e7bd4b..a3602300fe 100644
--- a/website/docs/api/admin/segments.mdx
+++ b/website/docs/api/admin/segments.mdx
@@ -278,9 +278,9 @@ Use a JSON object with the following properties to update the list of applied se
| `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. | `[]` |
-## Types
+## API types
-The segments API exposes the following 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}