Mirrors/unleash.unleash
1
0
Fork 0
mirror of https://github.com/Unleash/unleash.git synced 2025-01-25 00:07:47 +01:00
Code Issues Projects Releases Wiki Activity

docs: finish the API docs for segments

Browse Source
This commit is contained in:
Thomas Heartman 2022-04-02 16:27:09 +02:00
parent 102438946e
commit e03876286c
1 changed files with 177 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

201
website/docs/api/admin/segments.mdx
View File

@ -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."/> <ApiRequest verb="Get" url={basePath} title="Retrieve all existing segments."/>
<details open> <details>
<summary>Example responses</summary> <summary>Example responses</summary>
@ -55,26 +55,15 @@ payload={{
/> />
<details open> <details>
<summary>Example responses</summary> <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 ### 400 Bad Request
{
"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. A segment with the provided name already exists.
@ -82,9 +71,9 @@ A segment with the provided name already exists.
### Payload structure ### 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"` | | `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."` | | `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. 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={`${ basePath }/<segment-id>`} title="Retrieve the segment with the provided ID."/>
<details open> <details>
<summary>Example responses</summary> <summary>Example responses</summary>
@ -118,15 +107,163 @@ No segment with the provided ID exists.
</details> </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 ## Types
@ -157,3 +294,19 @@ export interface IConstraint {
caseInsensitive?: 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;
}
```