2020-06-17 03:08:38 +00:00
---
stage: Release
2020-12-01 15:09:28 +00:00
group: Release
2020-11-26 06:09:20 +00:00
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/#assignments
2020-06-17 03:08:38 +00:00
---
2021-09-09 15:09:24 +00:00
# Feature flags API **(FREE SELF)**
2017-05-31 21:06:01 +00:00
2020-05-15 18:07:52 +00:00
This API is for managing Flipper-based [feature flags used in development of GitLab ](../development/feature_flags/index.md ).
2017-05-31 21:06:01 +00:00
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-02-27 09:09:01 +00:00
```plaintext
2017-05-31 21:06:01 +00:00
GET /features
```
2020-01-30 15:09:15 +00:00
```shell
2020-05-28 00:08:37 +00:00
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/features"
2017-05-31 21:06:01 +00:00
```
Example response:
```json
[
{
"name": "experimental_feature",
"state": "off",
"gates": [
{
"key": "boolean",
"value": false
}
2020-11-19 03:08:59 +00:00
],
"definition": null
2017-05-31 21:06:01 +00:00
},
2020-05-14 00:07:47 +00:00
{
"name": "my_user_feature",
"state": "on",
"gates": [
{
"key": "percentage_of_actors",
"value": 34
}
2020-11-19 03:08:59 +00:00
],
"definition": {
"name": "my_user_feature",
"introduced_by_url": "https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40880",
"rollout_issue_url": "https://gitlab.com/gitlab-org/gitlab/-/issues/244905",
"group": "group::ci",
"type": "development",
"default_enabled": false
}
2020-05-14 00:07:47 +00:00
},
2017-05-31 21:06:01 +00:00
{
"name": "new_library",
"state": "on",
"gates": [
{
"key": "boolean",
"value": true
}
2020-11-19 03:08:59 +00:00
],
"definition": null
}
]
```
## List all feature definitions
Get a list of all feature definitions.
```plaintext
GET /features/definitions
```
```shell
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/features/definitions"
```
Example response:
```json
[
{
"name": "api_kaminari_count_with_limit",
"introduced_by_url": "https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/23931",
"rollout_issue_url": null,
"milestone": "11.8",
"type": "ops",
"group": "group::ecosystem",
"default_enabled": false
},
{
"name": "marginalia",
"introduced_by_url": null,
"rollout_issue_url": null,
"milestone": null,
"type": "ops",
"group": null,
"default_enabled": false
2017-05-31 21:06:01 +00:00
}
]
```
## Set or create a feature
2020-12-17 21:09:57 +00:00
Set a feature's gate value. If a feature with the given name doesn't exist yet,
it's created. The value can be a boolean, or an integer to indicate
2017-05-31 21:06:01 +00:00
percentage of time.
2020-02-27 09:09:01 +00:00
```plaintext
2017-05-31 21:06:01 +00:00
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-14 00:07:47 +00:00
| `key` | string | no | `percentage_of_actors` or `percentage_of_time` (default) |
2017-06-28 17:29:56 +00:00
| `feature_group` | string | no | A Feature group name |
2017-06-21 14:49:51 +00:00
| `user` | string | no | A GitLab username |
2019-08-23 08:50:24 +00:00
| `group` | string | no | A GitLab group's path, for example `gitlab-org` |
2019-09-18 18:06:14 +00:00
| `project` | string | no | A projects path, for example `gitlab-org/gitlab-foss` |
2021-01-29 18:09:17 +00:00
| `force` | boolean | no | Skip feature flag validation checks, such as a YAML definition |
2017-05-31 21:06:01 +00:00
2021-07-28 21:08:53 +00:00
You can enable or disable a feature for a `feature_group` , a `user` ,
2019-02-07 20:27:03 +00:00
a `group` , and a `project` in a single API call.
2017-06-27 16:58:56 +00:00
2020-01-30 15:09:15 +00:00
```shell
2020-05-28 00:08:37 +00:00
curl --data "value=30" --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/features/new_library"
2017-05-31 21:06:01 +00:00
```
Example response:
```json
{
"name": "new_library",
"state": "conditional",
"gates": [
{
"key": "boolean",
"value": false
},
{
"key": "percentage_of_time",
"value": 30
}
2020-11-19 03:08:59 +00:00
],
"definition": {
"name": "my_user_feature",
"introduced_by_url": "https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40880",
"rollout_issue_url": "https://gitlab.com/gitlab-org/gitlab/-/issues/244905",
"group": "group::ci",
"type": "development",
"default_enabled": false
}
2017-05-31 21:06:01 +00:00
}
```
2018-04-03 11:35:26 +00:00
2020-05-14 00:07:47 +00:00
### Set percentage of actors rollout
2020-05-15 03:08:10 +00:00
Rollout to percentage of actors.
2020-05-14 00:07:47 +00:00
```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
},
{
2020-05-15 03:08:10 +00:00
"key": "percentage_of_actors",
2020-05-14 00:07:47 +00:00
"value": 42
}
2020-11-19 03:08:59 +00:00
],
"definition": {
"name": "my_user_feature",
"introduced_by_url": "https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40880",
"rollout_issue_url": "https://gitlab.com/gitlab-org/gitlab/-/issues/244905",
"group": "group::ci",
"type": "development",
"default_enabled": false
}
2020-05-14 00:07:47 +00:00
}
```
2020-05-15 03:08:10 +00:00
Rolls out the `my_user_feature` to `42%` of actors.
2020-05-14 00:07:47 +00:00
2018-04-03 11:35:26 +00:00
## Delete a feature
Removes a feature gate. Response is equal when the gate exists, or doesn't.
2020-02-27 09:09:01 +00:00
```plaintext
2018-04-03 11:35:26 +00:00
DELETE /features/:name
```