From d7029d89b4dab2b6fee3167475dfa697229870ca Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Mon, 25 Apr 2022 21:49:00 +0200 Subject: [PATCH 1/6] docs: Add deprecation notices to features v1 todo: still need to add a couple links --- website/docs/api/admin/feature-toggles-api.md | 89 ++++++++++++++++--- 1 file changed, 75 insertions(+), 14 deletions(-) diff --git a/website/docs/api/admin/feature-toggles-api.md b/website/docs/api/admin/feature-toggles-api.md index 948a795960c..6bca9852522 100644 --- a/website/docs/api/admin/feature-toggles-api.md +++ b/website/docs/api/admin/feature-toggles-api.md @@ -3,11 +3,23 @@ id: features title: /api/admin/features --- -> 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. +:::caution Deprecation notice +This API was deprecated as part of the v4.3 release and will be removed in v5.0. See [the project-based API (/api/admin/projects/:projectId)](./feature-toggles-api-v2.md) instead. +::: -**This API was deprecated as part of the v4.3 release and will be removed in v5.0. See [/api/admin/projects/:projectId](/api/admin/feature-toggles-v2) instead.** + -### Fetching Feature Toggles {#fetching-feature-toggles} + +:::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} + +:::caution Deprecation notice +This endpoint is deprecated. Please use the [project-based endpoint to fetch all toggles](./feature-toggles-api-v2.md#fetching-toggles) instead. +::: `GET: http://unleash.host.com/api/admin/features` @@ -75,7 +87,7 @@ This endpoint is the one all admin ui should use to fetch all available feature } ``` -#### Filter feature toggles {#filter-feature-toggles} +### Filter feature toggles {#filter-feature-toggles} Supports three params for now @@ -95,7 +107,11 @@ To filter for any feature belonging to project `myproject` use Response format is the same as `api/admin/features` -### Fetch specific feature toggle {#fetch-specific-feature-toggle} +## Fetch specific feature toggle {#fetch-specific-feature-toggle} + +:::caution Deprecation notice +This endpoint is deprecated. Please use the [project-based endpoint to fetch specific toggles](./feature-toggles-api-v2.md#get-toggle) instead. +::: `GET: http://unleash.host.com/api/admin/features/:featureName` @@ -119,7 +135,12 @@ Used to fetch details about a specific featureToggle. This is mostly provded to } ``` -### Create a new Feature Toggle {#create-a-new-feature-toggle} +## Create a new Feature Toggle {#create-a-new-feature-toggle} + +:::caution Deprecation notice +This endpoint is deprecated. Please use the [project-based endpoint to create feature toggles](./feature-toggles-api-v2.md#create-toggle) instead. +::: + `POST: http://unleash.host.com/api/admin/features/` @@ -150,7 +171,12 @@ Used by the admin-dashboard to create a new feature toggles. Returns 200-response if the feature toggle was created successfully. -### Update a Feature Toggle {#update-a-feature-toggle} +## Update a Feature Toggle {#update-a-feature-toggle} + +:::caution Deprecation notice +This endpoint is deprecated. Please use the [project-based endpoint to update a feature toggle](./feature-toggles-api-v2.md#update-toggle) instead. +::: + `PUT: http://unleash.host.com/api/admin/features/:toggleName` @@ -177,7 +203,13 @@ Used by the admin dashboard to update a feature toggles. The name has to match a Returns 200-response if the feature toggle was updated successfully. -### Tag a Feature Toggle {#tag-a-feature-toggle} +## Tag a Feature Toggle {#tag-a-feature-toggle} + +:::caution Deprecation notice + +This endpoint is deprecated. Please use the [project-based endpoint to tag a feature toggle](./feature-toggles-api-v2.md#fetching-toggles) instead. +::: + `POST https://unleash.host.com/api/admin/features/:featureName/tags` @@ -203,7 +235,13 @@ If the tuple (type, value) does not already exist, it will be added to the list - Returns _404-NOT-FOUND_ if the `type` was not found -### Remove a tag from a Feature Toggle {#remove-a-tag-from-a-feature-toggle} +## Remove a tag from a Feature Toggle {#remove-a-tag-from-a-feature-toggle} + +:::caution Deprecation notice + +This endpoint is deprecated. Please use the [project-based endpoint to remove tags from a toggle](./feature-toggles-api-v2.md#fetching-toggles) instead. +::: + `DELETE https://unleash.host.com/api/admin/features/:featureName/tags/:type/:value` @@ -218,13 +256,23 @@ Removes the specified tag from the `(type, value)` tuple from the Feature Toggle - Returns 404 if the tag does not exist - Returns 500 if the database could not be reached -### Archive a Feature Toggle {#archive-a-feature-toggle} +## Archive a Feature Toggle {#archive-a-feature-toggle} + +:::caution Deprecation notice +This endpoint is deprecated. Please use the [project-based endpoint to archive toggles](./feature-toggles-api-v2.md#archive-toggle) instead. +::: + `DELETE: http://unleash.host.com/api/admin/features/:toggleName` Used to archive a feature toggle. A feature toggle can never be totally be deleted, but can be archived. This is a design decision to make sure that a old feature toggle does not suddenly reappear because someone else is re-using the same name. -### Enable a Feature Toggle {#enable-a-feature-toggle} +## Enable a Feature Toggle {#enable-a-feature-toggle} + +:::caution Deprecation notice +This endpoint is deprecated. Please use the [project-based endpoint to enable feature toggles](./feature-toggles-api-v2.md#where?) instead. +::: + `POST: http://unleash.host.com/api/admin/features/:featureName/toggle/on` @@ -253,7 +301,11 @@ None } ``` -### Disable a Feature Toggle {#disable-a-feature-toggle} +## Disable a Feature Toggle {#disable-a-feature-toggle} + +:::caution Deprecation notice +This endpoint is deprecated. Please use the [project-based endpoint to disable feature toggles](./feature-toggles-api-v2.md#where?) instead. +::: `POST: http://unleash.host.com/api/admin/features/:featureName/toggle/off` @@ -283,7 +335,12 @@ None } ``` -### Mark a Feature Toggle as "stale" {#mark-a-feature-toggle-as-stale} +## Mark a Feature Toggle as "stale" {#mark-a-feature-toggle-as-stale} + +:::caution Deprecation notice +This endpoint is deprecated. Please use the [project-based endpoint to patch a feature toggle and mark it as stale](./feature-toggles-api-v2.md#patch-toggle) instead. +::: + `POST: http://unleash.host.com/api/admin/features/:featureName/stale/on` @@ -313,7 +370,11 @@ None } ``` -### Mark a Feature Toggle as "active" {#mark-a-feature-toggle-as-active} +## Mark a Feature Toggle as "active" {#mark-a-feature-toggle-as-active} + +:::caution Deprecation notice +This endpoint is deprecated. Please use the [project-based endpoint to patch a feature toggle and mark it as not stale](./feature-toggles-api-v2.md#patch-toggle) instead. +::: `POST: http://unleash.host.com/api/admin/features/:featureName/stale/off` From 9a0226d15883191b481a6cd88bd89486019b4f16 Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Tue, 26 Apr 2022 16:19:34 +0200 Subject: [PATCH 2/6] docs: remove deprecation notices for tags. --- website/docs/api/admin/feature-toggles-api.md | 14 +------------- 1 file changed, 1 insertion(+), 13 deletions(-) diff --git a/website/docs/api/admin/feature-toggles-api.md b/website/docs/api/admin/feature-toggles-api.md index 6bca9852522..a6e6799de03 100644 --- a/website/docs/api/admin/feature-toggles-api.md +++ b/website/docs/api/admin/feature-toggles-api.md @@ -4,7 +4,7 @@ title: /api/admin/features --- :::caution Deprecation notice -This API was deprecated as part of the v4.3 release and will be removed in v5.0. See [the project-based API (/api/admin/projects/:projectId)](./feature-toggles-api-v2.md) instead. +Most of this API was deprecated as part of the v4.3 release and will be removed in v5.0. You should use [the project-based API (/api/admin/projects/:projectId)](./feature-toggles-api-v2.md) instead. The deprecated endpoints are marked as such in the document below. ::: @@ -205,12 +205,6 @@ Returns 200-response if the feature toggle was updated successfully. ## Tag a Feature Toggle {#tag-a-feature-toggle} -:::caution Deprecation notice - -This endpoint is deprecated. Please use the [project-based endpoint to tag a feature toggle](./feature-toggles-api-v2.md#fetching-toggles) instead. -::: - - `POST https://unleash.host.com/api/admin/features/:featureName/tags` Used to tag a feature @@ -237,12 +231,6 @@ If the tuple (type, value) does not already exist, it will be added to the list ## Remove a tag from a Feature Toggle {#remove-a-tag-from-a-feature-toggle} -:::caution Deprecation notice - -This endpoint is deprecated. Please use the [project-based endpoint to remove tags from a toggle](./feature-toggles-api-v2.md#fetching-toggles) instead. -::: - - `DELETE https://unleash.host.com/api/admin/features/:featureName/tags/:type/:value` Removes the specified tag from the `(type, value)` tuple from the Feature Toggle's list of tags. From 65da8a845aff2845774dffa1b4e87f4562a56e77 Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Wed, 27 Apr 2022 10:55:33 +0200 Subject: [PATCH 3/6] feat: update ApiRequest to accept POST w/o payloads --- website/src/components/ApiRequest/ApiRequest.stories.jsx | 7 +++++++ website/src/components/ApiRequest/index.tsx | 6 +++++- 2 files changed, 12 insertions(+), 1 deletion(-) diff --git a/website/src/components/ApiRequest/ApiRequest.stories.jsx b/website/src/components/ApiRequest/ApiRequest.stories.jsx index 4c177e42d7c..a50ce3a2a16 100644 --- a/website/src/components/ApiRequest/ApiRequest.stories.jsx +++ b/website/src/components/ApiRequest/ApiRequest.stories.jsx @@ -31,6 +31,13 @@ POST.args = { title: 'Create a feature toggle with impression data enabled. (example)', }; +export const POSTWithoutPayload = Template.bind({}); +POSTWithoutPayload.args = { + verb: 'post', + url: 'api/admin/projects//features//environments//on', + title: 'Disable a toggle in an env.', +}; + export const PUT = Template.bind({}); PUT.args = { verb: 'put', diff --git a/website/src/components/ApiRequest/index.tsx b/website/src/components/ApiRequest/index.tsx index 4727dd91fce..84fa595a32d 100644 --- a/website/src/components/ApiRequest/index.tsx +++ b/website/src/components/ApiRequest/index.tsx @@ -68,6 +68,9 @@ curl -H "Content-Type: application/json" \\ <${baseUrl}>/${url}` ).trim(); + const httpieBlockFormatSpecifier = + verbUpper === 'POST' && !prettyPayload ? '--json' : ''; + const httpieBlock = ( payload ? `echo '${prettyPayload}' \\ @@ -77,7 +80,8 @@ curl -H "Content-Type: application/json" \\ : ` http ${verbUpper} \\ <${baseUrl}>/${url} \\ - Authorization:<${authToken}>`.trim() + Authorization:<${authToken}> \\ + ${httpieBlockFormatSpecifier}`.trim() ).trim(); return ( From 9ec3409fff77653a8199c1dcb9d5b2113fb45261 Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Wed, 27 Apr 2022 11:04:17 +0200 Subject: [PATCH 4/6] 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 669b093cf95..0b7ce64b70f 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. From 5d0ed34b66cccd57bffc627cd4050f4970e826d9 Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Wed, 27 Apr 2022 11:05:15 +0200 Subject: [PATCH 5/6] chore: remove code leftover code --- website/docs/api/admin/feature-toggles-api.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/website/docs/api/admin/feature-toggles-api.md b/website/docs/api/admin/feature-toggles-api.md index a6e6799de03..c75535657ea 100644 --- a/website/docs/api/admin/feature-toggles-api.md +++ b/website/docs/api/admin/feature-toggles-api.md @@ -7,8 +7,6 @@ title: /api/admin/features Most of this API was deprecated as part of the v4.3 release and will be removed in v5.0. You should use [the project-based API (/api/admin/projects/:projectId)](./feature-toggles-api-v2.md) instead. The deprecated endpoints are marked as such in the document below. ::: - - :::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. From 75719a02978965aaa283d895f44aa1c2c2ae7ed2 Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Wed, 27 Apr 2022 11:09:04 +0200 Subject: [PATCH 6/6] docs: link to the correct new endpoints in the features v2 API --- website/docs/api/admin/feature-toggles-api.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/website/docs/api/admin/feature-toggles-api.md b/website/docs/api/admin/feature-toggles-api.md index c75535657ea..04f4d094111 100644 --- a/website/docs/api/admin/feature-toggles-api.md +++ b/website/docs/api/admin/feature-toggles-api.md @@ -256,7 +256,7 @@ Used to archive a feature toggle. A feature toggle can never be totally be delet ## Enable a Feature Toggle {#enable-a-feature-toggle} :::caution Deprecation notice -This endpoint is deprecated. Please use the [project-based endpoint to enable feature toggles](./feature-toggles-api-v2.md#where?) instead. +This endpoint is deprecated. Please use the [project-based endpoint to enable feature toggles](./feature-toggles-api-v2.md#enable-env) instead. ::: @@ -290,7 +290,7 @@ None ## Disable a Feature Toggle {#disable-a-feature-toggle} :::caution Deprecation notice -This endpoint is deprecated. Please use the [project-based endpoint to disable feature toggles](./feature-toggles-api-v2.md#where?) instead. +This endpoint is deprecated. Please use the [project-based endpoint to disable feature toggles](./feature-toggles-api-v2.md#disable-env) instead. ::: `POST: http://unleash.host.com/api/admin/features/:featureName/toggle/off`