Add latest changes from gitlab-org/gitlab@13-1-stable-ee

1 files changed, 170 insertions, 198 deletions

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: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/feature_flags
+curl --header "PRIVATE-TOKEN: <your_access_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: <your_access_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: <your_access_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: <your_access_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: <your_access_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: <your_access_token>" --request DELETE https://gitlab.example.com/api/v4/projects/1/feature_flags/awesome_feature
+curl --header "PRIVATE-TOKEN: <your_access_token>" --request DELETE "https://gitlab.example.com/api/v4/projects/1/feature_flags/awesome_feature"
 ```