Add feature toggles through Flipper

3 files changed, 91 insertions, 0 deletions

diff --git a/doc/api/features.md b/doc/api/features.md
new file mode 100644
index 00000000000..89b8d3ac948
--- /dev/null
+++ b/doc/api/features.md
@@ -0,0 +1,83 @@
+# Features API
+
+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
+curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/features
+```
+
+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 |
+
+```bash
+curl --data "value=30" --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/features/new_library
+```
+
+Example response:
+
+```json
+{
+  "name": "new_library",
+  "state": "conditional",
+  "gates": [
+    {
+      "key": "boolean",
+      "value": false
+    },
+    {
+      "key": "percentage_of_time",
+      "value": 30
+    }
+  ]
+}
+```
diff --git a/doc/development/README.md b/doc/development/README.md
index 934c6849ff9..be013667684 100644
--- a/doc/development/README.md
+++ b/doc/development/README.md
@@ -42,6 +42,7 @@
 - [Sidekiq debugging](sidekiq_debugging.md)
 - [Object state models](object_state_models.md)
 - [Building a package for testing purposes](build_test_package.md)
+- [Manage feature flags](feature_flags.md)
 
 ## Databases
 
diff --git a/doc/development/feature_flags.md b/doc/development/feature_flags.md
new file mode 100644
index 00000000000..5c6316b9ac6
--- /dev/null
+++ b/doc/development/feature_flags.md
@@ -0,0 +1,7 @@
+# Manage feature flags
+
+Starting from GitLab 9.3 we support feature flags via
+[Flipper](https://github.com/jnunemaker/flipper/). You should use the `Feature`
+class (defined in `lib/feature.rb`) in your code to get, set and list feature
+flags. During runtime you can set the values for the gates via the
+[admin API](../api/features.md).