debian-mirror-gitlab/doc/api/features.md

149 lines
3.2 KiB
Markdown
Raw Normal View History

2020-06-23 00:09:42 +05:30
---
stage: Release
group: Progressive Delivery
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers
---
2017-09-10 17:25:29 +05:30
# Features flags API
2020-05-24 23:13:21 +05:30
This API is for managing Flipper-based [feature flags used in development of GitLab](../development/feature_flags/index.md).
2017-09-10 17:25:29 +05:30
All methods require administrator authorization.
Notice that currently the API only supports boolean and percentage-of-time gate
values.
## List all features
Get a list of all persisted features, with its gate values.
2020-04-08 14:13:33 +05:30
```plaintext
2017-09-10 17:25:29 +05:30
GET /features
```
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/features"
2017-09-10 17:25:29 +05:30
```
Example response:
```json
[
{
"name": "experimental_feature",
"state": "off",
"gates": [
{
"key": "boolean",
"value": false
}
]
},
2020-05-24 23:13:21 +05:30
{
"name": "my_user_feature",
"state": "on",
"gates": [
{
"key": "percentage_of_actors",
"value": 34
}
]
},
2017-09-10 17:25:29 +05:30
{
"name": "new_library",
"state": "on",
"gates": [
{
"key": "boolean",
"value": true
}
]
}
]
```
## Set or create a feature
Set a feature's gate value. If a feature with the given name doesn't exist yet
it will be created. The value can be a boolean, or an integer to indicate
percentage of time.
2020-04-08 14:13:33 +05:30
```plaintext
2017-09-10 17:25:29 +05:30
POST /features/:name
```
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `name` | string | yes | Name of the feature to create or update |
| `value` | integer/string | yes | `true` or `false` to enable/disable, or an integer for percentage of time |
2020-05-24 23:13:21 +05:30
| `key` | string | no | `percentage_of_actors` or `percentage_of_time` (default) |
2017-09-10 17:25:29 +05:30
| `feature_group` | string | no | A Feature group name |
| `user` | string | no | A GitLab username |
2019-12-04 20:38:33 +05:30
| `group` | string | no | A GitLab group's path, for example `gitlab-org` |
2019-12-21 20:55:43 +05:30
| `project` | string | no | A projects path, for example `gitlab-org/gitlab-foss` |
2017-09-10 17:25:29 +05:30
2019-03-02 22:35:43 +05:30
Note that you can enable or disable a feature for a `feature_group`, a `user`,
2019-07-07 11:18:12 +05:30
a `group`, and a `project` in a single API call.
2017-09-10 17:25:29 +05:30
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --data "value=30" --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/features/new_library"
2017-09-10 17:25:29 +05:30
```
Example response:
```json
{
"name": "new_library",
"state": "conditional",
"gates": [
{
"key": "boolean",
"value": false
},
{
"key": "percentage_of_time",
"value": 30
}
]
}
```
2018-05-09 12:01:36 +05:30
2020-05-24 23:13:21 +05:30
### Set percentage of actors rollout
Rollout to percentage of actors.
```plaintext
POST https://gitlab.example.com/api/v4/features/my_user_feature?private_token=<your_access_token>
Content-Type: application/x-www-form-urlencoded
value=42&key=percentage_of_actors&
```
Example response:
```json
{
"name": "my_user_feature",
"state": "conditional",
"gates": [
{
"key": "boolean",
"value": false
},
{
"key": "percentage_of_actors",
"value": 42
}
]
}
```
Rolls out the `my_user_feature` to `42%` of actors.
2018-05-09 12:01:36 +05:30
## Delete a feature
Removes a feature gate. Response is equal when the gate exists, or doesn't.
2020-04-08 14:13:33 +05:30
```plaintext
2018-05-09 12:01:36 +05:30
DELETE /features/:name
```