diff options
author | GitLab Bot <gitlab-bot@gitlab.com> | 2019-11-14 18:06:15 +0000 |
---|---|---|
committer | GitLab Bot <gitlab-bot@gitlab.com> | 2019-11-14 18:06:15 +0000 |
commit | 921d16124a626ad94e14bacb734033b0293ba431 (patch) | |
tree | 11be086bbc2b27701c3f8d885dd552af85b100c4 /doc/api | |
parent | d88843f370acfcbbd3e2b9d6d662d62132647d86 (diff) | |
download | gitlab-ce-921d16124a626ad94e14bacb734033b0293ba431.tar.gz |
Add latest changes from gitlab-org/gitlab@master
Diffstat (limited to 'doc/api')
-rw-r--r-- | doc/api/feature_flag_specs.md | 291 | ||||
-rw-r--r-- | doc/api/feature_flags.md | 308 |
2 files changed, 599 insertions, 0 deletions
diff --git a/doc/api/feature_flag_specs.md b/doc/api/feature_flag_specs.md new file mode 100644 index 00000000000..6a2cd047f85 --- /dev/null +++ b/doc/api/feature_flag_specs.md @@ -0,0 +1,291 @@ +# Feature Flag Specs API **(PREMIUM)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/9566) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.5. + +The API for creating, updating, reading and deleting [Feature Flag Specs](../user/project/operations/feature_flags.md#define-environment-specs). +Automation engineers benefit from this API by being able to modify Feature Flag Specs without accessing user interface. +To manage the [Feature Flag](../user/project/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.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. + +``` +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.md) name | + +```bash +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. + +``` +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. | + +```bash +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. + +``` +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.md#scoping-environments-with-specs) of the feature flag. | +| `active` | boolean | yes | Whether the spec is active. | +| `strategies` | json | yes | The [strategies](../user/project/operations/feature_flags.md#feature-flag-strategies) of the feature flag spec. | + +```bash +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. + +``` +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.md#scoping-environments-with-specs) of the feature flag. | + +```bash +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. + +``` +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.md#scoping-environments-with-specs) of the feature flag. | +| `active` | boolean | yes | Whether the spec is active. | +| `strategies` | json | yes | The [strategies](../user/project/operations/feature_flags.md#feature-flag-strategies) of the feature flag spec. | + +```bash +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. + +``` +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.md#scoping-environments-with-specs) of the feature flag. | + +```bash +curl --header "PRIVATE-TOKEN: <your_access_token>" --request DELETE https://gitlab.example.com/api/v4/projects/1/feature_flags/new_live_trace/scopes/production +``` diff --git a/doc/api/feature_flags.md b/doc/api/feature_flags.md new file mode 100644 index 00000000000..def452d36fb --- /dev/null +++ b/doc/api/feature_flags.md @@ -0,0 +1,308 @@ +# Feature Flags API **(PREMIUM)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/9566) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.5. + +API for accessing resources of [GitLab Feature Flags](../user/project/operations/feature_flags.md). + +Users with Developer or higher [permissions](../user/permissions.md) can access Feature Flag API. + +## Feature Flags pagination + +By default, `GET` requests return 20 results at a time because the API results +are [paginated](README.md#pagination). + +## List feature flags for a project + +Gets all feature flags of the requested project. + +``` +GET /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). | +| `scope` | string | no | The condition of feature flags, one of: `enabled`, `disabled`. | + +```bash +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/feature_flags +``` + +Example response: + +```json +[ + { + "name":"merge_train", + "description":"This feature is about merge train", + "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" + } + ] + }, + { + "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" + }, + { + "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 + +Creates a new feature flag. + +``` +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.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. | + +```bash +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" } }] }] +} +EOF +``` + +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" + } + ] +} +``` + +## Single feature flag + +Gets a single feature flag. + +``` +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. | + +```bash +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/feature_flags/new_live_trace +``` + +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" + }, + { + "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" + } + ] +} +``` + +## Delete feature flag + +Deletes a feature flag. + +``` +DELETE /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. | + +```bash +curl --header "PRIVATE-TOKEN: <your_access_token>" --request DELETE https://gitlab.example.com/api/v4/projects/1/feature_flags/awesome_feature +``` |