mirror of
https://github.com/Unleash/unleash.git
synced 2024-10-18 20:09:08 +02:00
311 lines
7.5 KiB
Plaintext
311 lines
7.5 KiB
Plaintext
---
|
|
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}`
|
|
|
|
:::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). All payload
|
|
|
|
## 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>
|
|
|
|
<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. 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>
|
|
|
|
<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={`${ basePath }/<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={`${ 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
|
|
|
|
### `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;
|
|
}
|
|
```
|
|
|
|
### `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;
|
|
}
|
|
```
|