kotovalexarian-likes-gitlab/gitlab-org--gitlab-foss
1
0
Fork 0
Code Releases Activity
gitlab-org--gitlab-foss/doc/api/feature_flag_specs.md

300 lines
10 KiB
Markdown
Raw Blame History

---
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
---
# Feature Flag Specs API **(PREMIUM)**
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9566) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.5.
CAUTION: **Deprecation:**
This API is deprecated and [scheduled for removal in GitLab 14.0](https://gitlab.com/gitlab-org/gitlab/-/issues/213369).
The API for creating, updating, reading and deleting Feature Flag Specs.
Automation engineers benefit from this API by being able to modify Feature Flag Specs without accessing user interface.
To manage the [Feature Flag](../operations/feature_flags.md) resources via public API, please refer to the [Feature Flags API](feature_flags.md) document.
Users with Developer or higher [permissions](../user/permissions.md) can access Feature Flag Specs API.
## List all effective feature flag specs under the specified environment
Get all effective feature flag specs under the specified [environment](../ci/environments/index.md).
For instance, there are two specs, `staging` and `production`, for a feature flag.
When you pass `production` as a parameter to this endpoint, the system returns
the `production` feature flag spec only.
```plaintext
GET /projects/:id/feature_flag_scopes
```
| Attribute | Type | Required | Description |
| ------------------- | ---------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). |
| `environment` | string | yes | The [environment](../ci/environments/index.md) name |
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/feature_flag_scopes?environment=production"
```
Example response:
```json
[
{
"id": 88,
"active": true,
"environment_scope": "production",
"strategies": [
{
"name": "userWithId",
"parameters": {
"userIds": "1,2,3"
}
}
],
"created_at": "2019-11-04T08:36:41.327Z",
"updated_at": "2019-11-04T08:36:41.327Z",
"name": "awesome_feature"
},
{
"id": 82,
"active": true,
"environment_scope": "*",
"strategies": [
{
"name": "default",
"parameters": {}
}
],
"created_at": "2019-11-04T08:13:51.425Z",
"updated_at": "2019-11-04T08:39:45.751Z",
"name": "merge_train"
},
{
"id": 81,
"active": false,
"environment_scope": "production",
"strategies": [
{
"name": "default",
"parameters": {}
}
],
"created_at": "2019-11-04T08:13:10.527Z",
"updated_at": "2019-11-04T08:13:10.527Z",
"name": "new_live_trace"
}
]
```
## List all specs of a feature flag
Get all specs of a feature flag.
```plaintext
GET /projects/:id/feature_flags/:name/scopes
```
| Attribute | Type | Required | Description |
| ------------------- | ---------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). |
| `name` | string | yes | The name of the feature flag. |
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/feature_flags/new_live_trace/scopes"
```
Example response:
```json
[
{
"id": 79,
"active": false,
"environment_scope": "*",
"strategies": [
{
"name": "default",
"parameters": {}
}
],
"created_at": "2019-11-04T08:13:10.516Z",
"updated_at": "2019-11-04T08:13:10.516Z"
},
{
"id": 80,
"active": true,
"environment_scope": "staging",
"strategies": [
{
"name": "default",
"parameters": {}
}
],
"created_at": "2019-11-04T08:13:10.525Z",
"updated_at": "2019-11-04T08:13:10.525Z"
},
{
"id": 81,
"active": false,
"environment_scope": "production",
"strategies": [
{
"name": "default",
"parameters": {}
}
],
"created_at": "2019-11-04T08:13:10.527Z",
"updated_at": "2019-11-04T08:13:10.527Z"
}
]
```
## New feature flag spec
Creates a new feature flag spec.
```plaintext
POST /projects/:id/feature_flags/:name/scopes
```
| Attribute | Type | Required | Description |
| ------------------- | ---------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). |
| `name` | string | yes | The name of the feature flag. |
| `environment_scope` | string | yes | The [environment spec](../ci/environments/index.md#scoping-environments-with-specs) of the feature flag. |
| `active` | boolean | yes | Whether the spec is active. |
| `strategies` | JSON | yes | The [strategies](../operations/feature_flags.md#feature-flag-strategies) of the feature flag spec. |
```shell
curl "https://gitlab.example.com/api/v4/projects/1/feature_flags/new_live_trace/scopes" \
--header "PRIVATE-TOKEN: <your_access_token>" \
--header "Content-type: application/json" \
--data @- << EOF
{
"environment_scope": "*",
"active": false,
"strategies": [{ "name": "default", "parameters": {} }]
}
EOF
```
Example response:
```json
{
"id": 81,
"active": false,
"environment_scope": "*",
"strategies": [
{
"name": "default",
"parameters": {}
}
],
"created_at": "2019-11-04T08:13:10.527Z",
"updated_at": "2019-11-04T08:13:10.527Z"
}
```
## Single feature flag spec
Gets a single feature flag spec.
```plaintext
GET /projects/:id/feature_flags/:name/scopes/:environment_scope
```
| Attribute | Type | Required | Description |
| ------------------- | ---------------- | ---------- | ---------------------------------------------------------------------------------------|
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). |
| `name` | string | yes | The name of the feature flag. |
| `environment_scope` | string | yes | The URL-encoded [environment spec](../ci/environments/index.md#scoping-environments-with-specs) of the feature flag. |
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/:id/feature_flags/new_live_trace/scopes/production"
```
Example response:
```json
{
"id": 81,
"active": false,
"environment_scope": "production",
"strategies": [
{
"name": "default",
"parameters": {}
}
],
"created_at": "2019-11-04T08:13:10.527Z",
"updated_at": "2019-11-04T08:13:10.527Z"
}
```
## Edit feature flag spec
Updates an existing feature flag spec.
```plaintext
PUT /projects/:id/feature_flags/:name/scopes/:environment_scope
```
| Attribute | Type | Required | Description |
| ------------------- | ---------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). |
| `name` | string | yes | The name of the feature flag. |
| `environment_scope` | string | yes | The URL-encoded [environment spec](../ci/environments/index.md#scoping-environments-with-specs) of the feature flag. |
| `active` | boolean | yes | Whether the spec is active. |
| `strategies` | JSON | yes | The [strategies](../operations/feature_flags.md#feature-flag-strategies) of the feature flag spec. |
```shell
curl "https://gitlab.example.com/api/v4/projects/1/feature_flags/new_live_trace/scopes/production" \
--header "PRIVATE-TOKEN: <your_access_token>" \
--header "Content-type: application/json" \
--data @- << EOF
{
"active": true,
"strategies": [{ "name": "userWithId", "parameters": { "userIds": "1,2,3" } }]
}
EOF
```
Example response:
```json
{
"id": 81,
"active": true,
"environment_scope": "production",
"strategies": [
{
"name": "userWithId",
"parameters": { "userIds": "1,2,3" }
}
],
"created_at": "2019-11-04T08:13:10.527Z",
"updated_at": "2019-11-04T08:13:10.527Z"
}
```
## Delete feature flag spec
Deletes a feature flag spec.
```plaintext
DELETE /projects/:id/feature_flags/:name/scopes/:environment_scope
```
| Attribute | Type | Required | Description |
| ------------------- | ---------------- | ---------- | ---------------------------------------------------------------------------------------|
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). |
| `name` | string | yes | The name of the feature flag. |
| `environment_scope` | string | yes | The URL-encoded [environment spec](../ci/environments/index.md#scoping-environments-with-specs) of the feature flag. |
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" --request DELETE "https://gitlab.example.com/api/v4/projects/1/feature_flags/new_live_trace/scopes/production"
```
View git blame Copy permalink