From 669b8dd43551a60064308442acce74094bfde00d Mon Sep 17 00:00:00 2001 From: Benjamin Ludewig Date: Fri, 15 Mar 2019 15:39:26 +0100 Subject: [PATCH] chore: update import/export documentation --- docs/api/admin/state-api.md | 136 ++++++++++++++++++++++++++++++++++++ docs/import-export.md | 22 +++--- website/sidebars.json | 6 +- 3 files changed, 153 insertions(+), 11 deletions(-) create mode 100644 docs/api/admin/state-api.md diff --git a/docs/api/admin/state-api.md b/docs/api/admin/state-api.md new file mode 100644 index 0000000000..0976df2e89 --- /dev/null +++ b/docs/api/admin/state-api.md @@ -0,0 +1,136 @@ +--- +id: state +title: /api/admin/state +--- + +### Export Feature Toggles & Strategies + +`GET: http://unleash.host.com/api/admin/state/export` + +The api endpoint `/api/admin/state/export` will export feature-toggles and strategies as json by default.\ +You can customize the export with queryparameters: + +| Parameter | Default | Description | +| -------------- | ------- | --------------------------------------------------- | +| format | `json` | Export format, either `json` or `yaml` | +| download | `false` | If the exported data should be downloaded as a file | +| featureToggles | `true` | Include feature-toggles in the exported data | +| strategies | `true` | Include strategies in the exported data | + +**Example response:** + +`GET /api/admin/state/export?format=yaml&featureToggles=1&strategies=1` + +```yaml +version: 1 +features: + - name: Feature.A + description: lorem ipsum + enabled: false + strategies: + - name: default + parameters: {} + variants: + - name: variant1 + weight: 50 + - name: variant2 + weight: 50 + - name: Feature.B + description: lorem ipsum + enabled: true + strategies: + - name: ActiveForUserWithId + parameters: + userIdList: '123,221,998' + - name: GradualRolloutRandom + parameters: + percentage: '10' + variants: [] +strategies: + - name: country + description: Enable feature for certain countries + parameters: + - name: countries + type: list + description: List of countries + required: true +``` + +### Import Feature Toggles & Strategies + +`POST: http://unleash.host.com/api/admin/state/import` + +You can import feature-toggles and strategies by POSTing to the `/api/admin/state/import` endpoint.\ +You can either send the data as JSON in the POST-body or send a `file` parameter with `multipart/form-data` (YAML files are also accepted here). + +Specify the `drop` query parameter, if you want the database to be cleaned before import (all strategies and features will be removed). + +> You should never use this in production environments. + +Success: `202 Accepted`\ +Error: `400 Bad Request` + +**Example body:** + +```json +{ + "version": 1, + "features": [ + { + "name": "Feature.A", + "description": "lorem ipsum", + "enabled": false, + "strategies": [ + { + "name": "default", + "parameters": {} + } + ], + "variants": [ + { + "name": "variant1", + "weight": 50 + }, + { + "name": "variant2", + "weight": 50 + } + ] + }, + { + "name": "Feature.B", + "description": "lorem ipsum", + "enabled": true, + "strategies": [ + { + "name": "ActiveForUserWithId", + "parameters": { + "userIdList": "123,221,998" + } + }, + { + "name": "GradualRolloutRandom", + "parameters": { + "percentage": "10" + } + } + ], + "variants": [] + } + ], + "strategies": [ + { + "name": "country", + "description": "Enable feature for certain countries", + "parameters": [ + { + "name": "countries", + "type": "list", + "description": "List of countries", + "required": true + } + ] + } + ] +} +``` diff --git a/docs/import-export.md b/docs/import-export.md index ab25a8a135..b5d4d80d85 100644 --- a/docs/import-export.md +++ b/docs/import-export.md @@ -3,12 +3,13 @@ id: import_export title: Import & Export --- +_since v3.3.0_ + Unleash supports import and export of feature-toggles and strategies at startup and during runtime. The import mechanism will guarantee that all imported features will be non-archived, as well as updates to strategies and features are included in the event history. -All import mechanisms support a `drop` parameter which will clean the database before import (all strategies and features will be removed).\ -**You should never use this in production environments.** +All import mechanisms support a `drop` parameter which will clean the database before import (all strategies and features will be removed). -_since v3.3.0_ +> You should never use this in production environments. ## Runtime import & export @@ -27,8 +28,9 @@ unleash.start({...}) }); ``` -If you want the database to be cleaned before import (all strategies and features will be removed), set the `dropBeforeImport` parameter.\ -**You should never use this in production environments.** +If you want the database to be cleaned before import (all strategies and features will be removed), set the `dropBeforeImport` parameter. + +> You should never use this in production environments. ### API Export @@ -53,8 +55,9 @@ For example if you want to download all feature-toggles as yaml: You can import feature-toggles and strategies by POSTing to the `/api/admin/state/import` endpoint (keep in mind this will require authentication).\ You can either send the data as JSON in the POST-body or send a `file` parameter with `multipart/form-data` (YAML files are also accepted here). -If you want the database to be cleaned before import (all strategies and features will be removed), specify a `drop` query parameter.\ -**You should never use this in production environments.** +If you want the database to be cleaned before import (all strategies and features will be removed), specify a `drop` query parameter. + +> You should never use this in production environments. Example usage: @@ -79,8 +82,9 @@ You can import a json or yaml file via the configuration option `importFile`. Example usage: `unleash-server --databaseUrl ... --importFile export.yml`. -If you want the database to be cleaned before import (all strategies and features will be removed), specify the `dropBeforeImport` option.\ -**You should never use this in production environments.** +If you want the database to be cleaned before import (all strategies and features will be removed), specify the `dropBeforeImport` option. + +> You should never use this in production environments. Example usage: `unleash-server --databaseUrl ... --importFile export.yml --dropBeforeImport`. diff --git a/website/sidebars.json b/website/sidebars.json index 3863308707..0ea7e8dd48 100644 --- a/website/sidebars.json +++ b/website/sidebars.json @@ -13,7 +13,8 @@ "Developer Guide": [ "developer_guide", "database_schema", - "database_backup" + "database_backup", + "import_export" ], "Guides": ["guides/google_auth", "guides/custom_activation_strategy"] }, @@ -27,7 +28,8 @@ "api/admin/features", "api/admin/strategies", "api/admin/metrics", - "api/admin/events" + "api/admin/events", + "api/admin/state" ], "Internal": ["api/internal"] }