From 9ec3409fff77653a8199c1dcb9d5b2113fb45261 Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Wed, 27 Apr 2022 11:04:17 +0200 Subject: [PATCH] docs: add more Api information + add disable toggle info --- .../docs/api/admin/feature-toggles-api-v2.md | 121 ++++++++++++++---- 1 file changed, 96 insertions(+), 25 deletions(-) diff --git a/website/docs/api/admin/feature-toggles-api-v2.md b/website/docs/api/admin/feature-toggles-api-v2.md index 669b093cf9..0b7ce64b70 100644 --- a/website/docs/api/admin/feature-toggles-api-v2.md +++ b/website/docs/api/admin/feature-toggles-api-v2.md @@ -2,8 +2,15 @@ id: feature-toggles-v2 title: /api/admin/projects/:projectId --- +import ApiRequest from '@site/src/components/ApiRequest' + +:::info +In order to access the admin API endpoints you need to identify yourself. Unless you're using the `none` authentication method, you'll need to [create an **admin** token](/user_guide/api-token) and add an Authorization header using the token. +::: + + +## Fetching Feature Toggles {#fetching-feature-toggles} -> In order to access the admin API endpoints you need to identify yourself. You'll need to [create an ADMIN token](/user_guide/api-token) and add an Authorization header using the token. **Available since Unleash v4.3** @@ -14,11 +21,14 @@ In this document we will guide you on how you can work with feature toggles and - A feature toggle can take different configuration, activation strategies, per environment. -> We will in this guide use [HTTPie](https://httpie.io) commands to show examples on how to interact with the API. +:::note +This document lists HTTP request data and [cURL](https://curl.se/) and [HTTPie](https://httpie.io) command examples for all endpoints. Further examples use HTTPie. +::: ### Get Project Overview {#fetching-project} -`http://localhost:4242/api/admin/projects/:projectId` + + This endpoint will give you an general overview of a project. It will return essential details about a project, in addition it will return all feature toggles and high level environment details per feature toggle. @@ -87,7 +97,8 @@ From the results we can see that we have received two feature toggles, _demo_, _ ### Get All Feature Toggles {#fetching-toggles} -`http://localhost:4242/api/admin/projects/:projectId/features` + + This endpoint will return all feature toggles and high level environment details per feature toggle for a given _projectId_ @@ -149,7 +160,7 @@ Authorization:$KEY ``` ### Create Feature Toggle {#create-toggle} -`http://localhost:4242/api/admin/projects/:projectId/features` + This endpoint will accept HTTP POST request to create a new feature toggle for a given _projectId_ @@ -207,7 +218,7 @@ Possible Errors: ### Get Feature Toggle {#get-toggle} -`http://localhost:4242/api/admin/projects/:projectId/features/:featureName` + This endpoint will return the feature toggles with the defined name and _projectId_. We will also see the list of environments and all activation strategies configured per environment. @@ -259,7 +270,7 @@ Possible Errors: ### Update Feature Toggle {#update-toggle} -`http://localhost:4242/api/admin/projects/:projectId/features/:featureName` + This endpoint will accept HTTP PUT request to update the feature toggle metadata. @@ -296,7 +307,8 @@ Some fields is not possible to change via this endpoint: ## Patch Feature Toggle {#patch-toggle} -`http://localhost:4242/api/admin/projects/:projectId/features/:featureName` + + This endpoint will accept HTTP PATCH request to update the feature toggle metadata. @@ -332,16 +344,16 @@ Some fields is not possible to change via this endpoint: - lastSeen -### Clone Feature Toggle {#create-toggle} +### Clone Feature Toggle {#clone-toggle} -`http://localhost:4242/api/admin/projects/:projectId/features/:featureName/clone` + -This endpoint will accept HTTP POST request to clone an existing feature toggle with all strategies and variants. It is not possible to clone archived feature toggles. The newly created feature toggle will be disabled for all environments. +This endpoint will accept HTTP POST request to clone an existing feature toggle with all strategies and variants. When cloning a toggle, you **must** provide a new name for it. You can not clone archived feature toggles. The newly created feature toggle will be disabled for all environments. **Example Query** ```bash -echo '{ "name": "newName" }' | \ +echo '{ "name": "DemoNew" }' | \ http POST http://localhost:4242/api/admin/projects/default/features/Demo/clone \ Authorization:$KEY` ``` @@ -388,9 +400,9 @@ Possible Errors: ### Archive Feature Toggle {#archive-toggle} -`http://localhost:4242/api/admin/projects/:projectId/features/:featureName` + -This endpoint will accept HTTP PUT request to update the feature toggle metadata. +This endpoint will accept HTTP DELETE requests to archive a feature toggle. **Example Query** @@ -414,7 +426,13 @@ Transfer-Encoding: chunked ### Add strategy to Feature Toggle {#add-strategy} -`http://localhost:4242/api/admin/projects/:projectId/features/:featureName/environments/:environment/strategies` + This endpoint will allow you to add a new strategy to a feature toggle in a given environment. @@ -450,6 +468,14 @@ Authorization:$KEY ### Update strategy configuration {#update-strategy} + + **Example Query** ```bash @@ -482,6 +508,8 @@ Authorization:$KEY ## Patch strategy configuration {#patch-strategy} + + **Example Query** ```bash @@ -509,6 +537,8 @@ Authorization:$KEY ### Delete strategy from Feature Toggle {#delete-strategy} + + **Example Query** ```bash @@ -528,7 +558,11 @@ Transfer-Encoding: chunked Vary: Accept-Encoding ``` -### Enable environment for Feature Toggle {#enable-env} +## Enabling and disabling toggles + +### Enable Feature Toggle in an Environment {#enable-env} + + **Example Query** @@ -551,10 +585,46 @@ Possible Errors: - _409 Conflict_ - You can not enable the environment before it has strategies. + +### Disable Feature Toggle in an Environment {#disable-env} + + + +**Example Query** + +```bash +http POST http://localhost:4242/api/admin/projects/default/features/demo/environments/development/off Authorization:$KEY --json +``` + +**Example response:** + +``` +HTTP/1.1 200 OK +Access-Control-Allow-Origin: * +Connection: keep-alive +Date: Tue, 07 Sep 2021 20:49:51 GMT +Keep-Alive: timeout=60 +Transfer-Encoding: chunked +``` + + ## Feature Variants ### Put variants for Feature Toggle {#update-variants} + + This overwrites the current variants for the feature toggle specified in the :featureName parameter. The backend will validate the input for the following invariants @@ -610,6 +680,12 @@ Content-Type: application/json; charset=utf-8 ### PATCH variants for a feature toggle + + **Example Query** ```bash @@ -654,9 +730,7 @@ You can add and remove users to a project using the `/api/admin/projects/:projec ### Add a user to a project -``` http -POST /api/admin/projects/:projectId/users/:userId/roles/:roleId -``` + This will add a user to a project and give the user a specified role within that project. @@ -704,9 +778,8 @@ Authorization:$KEY ### Change a user's role in a project -``` http -PUT /api/admin/projects/:projectId/users/:userId/roles/:roleId -``` + + This will change the user's project role to the role specified by `:roleId`. If the user has not been added to the project, nothing happens. @@ -753,9 +826,7 @@ Authorization:$KEY ### Remove a user from a project -``` http -DELETE /api/admin/projects/:projectId/users/:userId/roles/:roleId -``` + This removes the specified role from the user in the project. Because users can only have one role in a project, this effectively removes the user from the project. The user _must_ have the role indicated by the `:roleId` URL parameter for the request to succeed.