features.md 2.04 KB
Newer Older
1
# Features flags API
2 3 4 5 6 7 8 9 10 11 12 13 14 15 16

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.

```
GET /features
```

```bash
17
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/features
18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60
```

Example response:

```json
[
  {
    "name": "experimental_feature",
    "state": "off",
    "gates": [
      {
        "key": "boolean",
        "value": false
      }
    ]
  },
  {
    "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.

```
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 |
61
| `feature_group` | string | no | A Feature group name |
62
| `user` | string | no | A GitLab username |
63 64
| `group` | string | no | A GitLab group's path, for example `gitlab-org` |
| `project` | string | no | A projects path, for example `gitlab-org/gitlab-ce` |
65

66
Note that you can enable or disable a feature for a `feature_group`, a `user`,
67
a `group`, and a `project` in a single API call.
68

69
```bash
70
curl --data "value=30" --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/features/new_library
71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90
```

Example response:

```json
{
  "name": "new_library",
  "state": "conditional",
  "gates": [
    {
      "key": "boolean",
      "value": false
    },
    {
      "key": "percentage_of_time",
      "value": 30
    }
  ]
}
```
91 92 93 94 95 96 97 98

## Delete a feature

Removes a feature gate. Response is equal when the gate exists, or doesn't.

```
DELETE /features/:name
```