From 8c7f4e9d5f36cff46365a7f8c4b9c21578c1e781 Mon Sep 17 00:00:00 2001 From: GitLab Bot Date: Thu, 18 Jun 2020 11:18:50 +0000 Subject: Add latest changes from gitlab-org/gitlab@13-1-stable-ee --- doc/api/feature_flags.md | 368 ++++++++++++++++++++++------------------------- 1 file changed, 170 insertions(+), 198 deletions(-) (limited to 'doc/api/feature_flags.md') diff --git a/doc/api/feature_flags.md b/doc/api/feature_flags.md index 3e1b0e05298..f3af662c972 100644 --- a/doc/api/feature_flags.md +++ b/doc/api/feature_flags.md @@ -1,6 +1,15 @@ +--- +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 Flags API **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/9566) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.5. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9566) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.5. + +NOTE: **Note** +This API is behind a [feature flag](../user/project/operations/feature_flags.md#feature-flag-behavior-change-in-130). If this flag is not enabled in your environment, you can use the [legacy feature flags API](feature_flags_legacy.md). API for accessing resources of [GitLab Feature Flags](../user/project/operations/feature_flags.md). @@ -25,7 +34,7 @@ GET /projects/:id/feature_flags | `scope` | string | no | The condition of feature flags, one of: `enabled`, `disabled`. | ```shell -curl --header "PRIVATE-TOKEN: " https://gitlab.example.com/api/v4/projects/1/feature_flags +curl --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/projects/1/feature_flags" ``` Example response: @@ -35,113 +44,94 @@ Example response: { "name":"merge_train", "description":"This feature is about merge train", + "version": "new_version_flag", "created_at":"2019-11-04T08:13:51.423Z", "updated_at":"2019-11-04T08:13:51.423Z", - "scopes":[ - { - "id":82, - "active":false, - "environment_scope":"*", - "strategies":[ - { - "name":"default", - "parameters":{ - - } - } - ], - "created_at":"2019-11-04T08:13:51.425Z", - "updated_at":"2019-11-04T08:13:51.425Z" - }, - { - "id":83, - "active":true, - "environment_scope":"review/*", - "strategies":[ - { - "name":"default", - "parameters":{ - - } - } - ], - "created_at":"2019-11-04T08:13:51.427Z", - "updated_at":"2019-11-04T08:13:51.427Z" - }, - { - "id":84, - "active":false, - "environment_scope":"production", - "strategies":[ - { - "name":"default", - "parameters":{ - - } - } - ], - "created_at":"2019-11-04T08:13:51.428Z", - "updated_at":"2019-11-04T08:13:51.428Z" - } + "scopes":[], + "strategies": [ + { + "id": 1, + "name": "userWithId", + "parameters": { + "userIds": "user1" + }, + "scopes": [ + { + "id": 1, + "environment_scope": "production" + } + ] + } ] }, { "name":"new_live_trace", "description":"This is a new live trace feature", + "version": "new_version_flag", "created_at":"2019-11-04T08:13:10.507Z", "updated_at":"2019-11-04T08:13:10.507Z", - "scopes":[ - { - "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" - } + "scopes":[] + "strategies": [ + { + "id": 2, + "name": "default", + "parameters": {}, + "scopes": [ + { + "id": 2, + "environment_scope": "staging" + } + ] + } ] } ] ``` -## New feature flag +## Get a single feature flag + +Gets a single feature flag. + +```plaintext +GET /projects/:id/feature_flags/:name +``` + +| 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: " https://gitlab.example.com/api/v4/projects/1/feature_flags/awesome_feature +``` + +Example response: + +```json +{ + "name": "awesome_feature", + "description": null, + "version": "new_version_flag", + "created_at": "2020-05-13T19:56:33.119Z", + "updated_at": "2020-05-13T19:56:33.119Z", + "scopes": [], + "strategies": [ + { + "id": 36, + "name": "default", + "parameters": {}, + "scopes": [ + { + "id": 37, + "environment_scope": "production" + } + ] + } + ] +} +``` + +## Create a feature flag Creates a new feature flag. @@ -152,22 +142,24 @@ POST /projects/:id/feature_flags | 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. | -| `description` | string | no | The description of the feature flag. | -| `scopes` | JSON | no | The [feature flag specs](../user/project/operations/feature_flags.md#define-environment-specs) of the feature flag. | -| `scopes:environment_scope` | string | no | The [environment spec](../ci/environments/index.md#scoping-environments-with-specs). | -| `scopes:active` | boolean | no | Whether the spec is active. | -| `scopes:strategies` | JSON | no | The [strategies](../user/project/operations/feature_flags.md#feature-flag-strategies) of the feature flag spec. | +| `name` | string | yes | The name of the feature flag. | +| `version` | string | yes | The version of the feature flag. Must be `new_version_flag`. Omit or set to `legacy_flag` to create a [Legacy Feature Flag](feature_flags_legacy.md). | +| `description` | string | no | The description of the feature flag. | +| `strategies` | JSON | no | The feature flag [strategies](../user/project/operations/feature_flags.md#feature-flag-strategies). | +| `strategies:name` | JSON | no | The strategy name. | +| `strategies:parameters` | JSON | no | The strategy parameters. | +| `strategies:scopes` | JSON | no | The scopes for the strategy. | +| `strategies:scopes:environment_scope` | string | no | The environment spec for the scope. | ```shell -curl https://gitlab.example.com/api/v4/projects/1/feature_flags \ +curl "https://gitlab.example.com/api/v4/projects/1/feature_flags" \ --header "PRIVATE-TOKEN: " \ --header "Content-type: application/json" \ --data @- << EOF { - "name": "awesome_feature", - "scopes": [{ "environment_scope": "*", "active": false, "strategies": [{ "name": "default", "parameters": {} }] }, - { "environment_scope": "production", "active": true, "strategies": [{ "name": "userWithId", "parameters": { "userIds": "1,2,3" } }] }] + "name": "awesome_feature", + "version": "new_version_flag", + "strategies": [{ "name": "default", "parameters": {}, "scopes": [{ "environment_scope": "production" }] }] } EOF ``` @@ -176,121 +168,101 @@ Example response: ```json { - "name":"awesome_feature", - "description":null, - "created_at":"2019-11-04T08:32:27.288Z", - "updated_at":"2019-11-04T08:32:27.288Z", - "scopes":[ - { - "id":85, - "active":false, - "environment_scope":"*", - "strategies":[ - { - "name":"default", - "parameters":{ - - } - } - ], - "created_at":"2019-11-04T08:32:29.324Z", - "updated_at":"2019-11-04T08:32:29.324Z" - }, - { - "id":86, - "active":true, - "environment_scope":"production", - "strategies":[ - { - "name":"userWithId", - "parameters":{ - "userIds":"1,2,3" - } - } - ], - "created_at":"2019-11-04T08:32:29.328Z", - "updated_at":"2019-11-04T08:32:29.328Z" - } - ] + "name": "awesome_feature", + "description": null, + "version": "new_version_flag", + "created_at": "2020-05-13T19:56:33.119Z", + "updated_at": "2020-05-13T19:56:33.119Z", + "scopes": [], + "strategies": [ + { + "id": 36, + "name": "default", + "parameters": {}, + "scopes": [ + { + "id": 37, + "environment_scope": "production" + } + ] + } + ] } ``` -## Single feature flag +## Update a feature flag -Gets a single feature flag. +Updates a feature flag. ```plaintext -GET /projects/:id/feature_flags/:name +PUT /projects/:id/feature_flags/:name ``` | 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. | +| `name` | string | yes | The name of the feature flag. | +| `description` | string | no | The description of the feature flag. | +| `strategies` | JSON | no | The feature flag [strategies](../user/project/operations/feature_flags.md#feature-flag-strategies). | +| `strategies:id` | JSON | no | The feature flag strategy id. | +| `strategies:name` | JSON | no | The strategy name. | +| `strategies:parameters` | JSON | no | The strategy parameters. | +| `strategies:scopes` | JSON | no | The scopes for the strategy. | +| `strategies:scopes:id` | JSON | no | The scopes id. | +| `strategies:scopes:environment_scope` | string | no | The environment spec for the scope. | ```shell -curl --header "PRIVATE-TOKEN: " https://gitlab.example.com/api/v4/projects/1/feature_flags/new_live_trace +curl "https://gitlab.example.com/api/v4/projects/1/feature_flags/awesome_feature" \ + --header "PRIVATE-TOKEN: " \ + --header "Content-type: application/json" \ + --data @- << EOF +{ + "strategies": [{ "name": "gradualRolloutUserId", "parameters": { "groupId": "default", "percentage": "25" }, "scopes": [{ "environment_scope": "staging" }] }] +} +EOF ``` Example response: ```json { - "name":"new_live_trace", - "description":"This is a new live trace feature", - "created_at":"2019-11-04T08:13:10.507Z", - "updated_at":"2019-11-04T08:13:10.507Z", - "scopes":[ - { - "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" + "name": "awesome_feature", + "description": null, + "version": "new_version_flag", + "created_at": "2020-05-13T20:10:32.891Z", + "updated_at": "2020-05-13T20:10:32.891Z", + "scopes": [], + "strategies": [ + { + "id": 38, + "name": "gradualRolloutUserId", + "parameters": { + "groupId": "default", + "percentage": "25" }, - { - "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" - } - ] + "scopes": [ + { + "id": 40, + "environment_scope": "staging" + } + ] + }, + { + "id": 37, + "name": "default", + "parameters": {}, + "scopes": [ + { + "id": 39, + "environment_scope": "production" + } + ] + } + ] } ``` -## Delete feature flag +## Delete a feature flag Deletes a feature flag. @@ -304,5 +276,5 @@ DELETE /projects/:id/feature_flags/:name | `name` | string | yes | The name of the feature flag. | ```shell -curl --header "PRIVATE-TOKEN: " --request DELETE https://gitlab.example.com/api/v4/projects/1/feature_flags/awesome_feature +curl --header "PRIVATE-TOKEN: " --request DELETE "https://gitlab.example.com/api/v4/projects/1/feature_flags/awesome_feature" ``` -- cgit v1.2.1