From f92d86061a34998fcf7ec2f1554b28a5ac7178e6 Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Tue, 1 Feb 2022 13:21:16 +0100 Subject: [PATCH 1/9] docs(chore): improve syntax highlighting and formatting of code bits Use `bash` instead of `sh` for nicer highlighting by prism. I've also broken large json blobs over multiple lines. --- .../docs/api/admin/feature-toggles-api-v2.md | 95 +++++++++++++------ 1 file changed, 65 insertions(+), 30 deletions(-) diff --git a/website/docs/api/admin/feature-toggles-api-v2.md b/website/docs/api/admin/feature-toggles-api-v2.md index f329396275..e52c8da374 100644 --- a/website/docs/api/admin/feature-toggles-api-v2.md +++ b/website/docs/api/admin/feature-toggles-api-v2.md @@ -24,7 +24,10 @@ This endpoint will give you an general overview of a project. It will return ess **Example Query** -`http GET http://localhost:4242/api/admin/projects/default Authorization:$KEY` +```bash +http GET http://localhost:4242/api/admin/projects/default Authorization:$KEY +``` + **Example response:** @@ -90,7 +93,11 @@ This endpoint will return all feature toggles and high level environment details **Example Query** -`http GET http://localhost:4242/api/admin/projects/default/features Authorization:$KEY` +``` bash +http GET http://localhost:4242/api/admin/projects/default/features \ +Authorization:$KEY +``` + **Example response:** @@ -162,7 +169,8 @@ This endpoint accepts the following toggle options: ```bash echo '{"name": "demo2", "description": "A new feature toggle"}' | \ -http POST http://localhost:4242/api/admin/projects/default/features Authorization:$KEY` +http POST http://localhost:4242/api/admin/projects/default/features \ +Authorization:$KEY` ``` @@ -205,8 +213,9 @@ This endpoint will return the feature toggles with the defined name and _project **Example Query** -```sh -http GET http://localhost:4242/api/admin/projects/default/features/demo Authorization:$KEY` +```bash +http GET http://localhost:4242/api/admin/projects/default/features/demo \ +Authorization:$KEY` ``` **Example response:** @@ -256,8 +265,10 @@ This endpoint will accept HTTP PUT request to update the feature toggle metadata **Example Query** -```sh -echo '{"name": "demo", "description": "An update feature toggle", "type": "kill-switch"}' | http PUT http://localhost:4242/api/admin/projects/default/features/demo Authorization:$KEY` +```bash +echo '{"name": "demo", "description": "An update feature toggle", "type": "kill-switch"}' | \ +http PUT http://localhost:4242/api/admin/projects/default/features/demo \ +Authorization:$KEY` ``` @@ -291,8 +302,10 @@ This endpoint will accept HTTP PATCH request to update the feature toggle metada **Example Query** -```sh -echo '[{"op": "replace", "path": "/description", "value": "patched desc"}]' | http PATCH http://localhost:4242/api/admin/projects/default/features/demo Authorization:$KEY` +```bash +echo '[{"op": "replace", "path": "/description", "value": "patched desc"}]' | \ +http PATCH http://localhost:4242/api/admin/projects/default/features/demo \ +Authorization:$KEY` ``` @@ -327,8 +340,10 @@ This endpoint will accept HTTP POST request to clone an existing feature toggle **Example Query** -```sh -echo '{ "name": "newName" }' | http POST http://localhost:4242/api/admin/projects/default/features/Demo/clone Authorization:$KEY` +```bash +echo '{ "name": "newName" }' | \ +http POST http://localhost:4242/api/admin/projects/default/features/Demo/clone \ +Authorization:$KEY` ``` @@ -379,21 +394,21 @@ This endpoint will accept HTTP PUT request to update the feature toggle metadata **Example Query** -```sh -http DELETE http://localhost:4242/api/admin/projects/default/features/demo Authorization:$KEY` +```bash +http DELETE http://localhost:4242/api/admin/projects/default/features/demo \ +Authorization:$KEY` ``` **Example response:** -```sh +``` HTTP/1.1 202 Accepted Access-Control-Allow-Origin: * Connection: keep-alive Date: Wed, 08 Sep 2021 20:09:21 GMT Keep-Alive: timeout=60 Transfer-Encoding: chunked - ``` @@ -405,9 +420,17 @@ This endpoint will allow you to add a new strategy to a feature toggle in a give **Example Query** -```sh - echo '{"name": "flexibleRollout", "parameters": { "rollout": 20, "groupId": "demo", "stickiness": "default" }}' | \ - http POST http://localhost:4242/api/admin/projects/default/features/demo/environments/production/strategies Authorization:$KEY +```bash +echo '{"name": "flexibleRollout", + "parameters": { + "rollout": 20, + "groupId": "demo", + "stickiness": "default" + } + }' | \ +http POST \ +http://localhost:4242/api/admin/projects/default/features/demo/environments/production/strategies \ +Authorization:$KEY ``` **Example response:** @@ -429,9 +452,17 @@ This endpoint will allow you to add a new strategy to a feature toggle in a give **Example Query** -```sh -echo '{"name": "flexibleRollout", "parameters": { "rollout": 25, "groupId": "demo","stickiness": "default" }}' | \ -http PUT http://localhost:4242/api/admin/projects/default/features/demo/environments/production/strategies/77bbe972-ffce-49b2-94d9-326593e2228e Authorization:$KEY +```bash +echo '{"name": "flexibleRollout", + "parameters": { + "rollout": 25, + "groupId": "demo", + "stickiness": "default" + } + }' | \ +http PUT \ +http://localhost:4242/api/admin/projects/default/features/demo/environments/production/strategies/77bbe972-ffce-49b2-94d9-326593e2228e \ +Authorization:$KEY ``` **Example response:** @@ -453,9 +484,11 @@ http PUT http://localhost:4242/api/admin/projects/default/features/demo/environm **Example Query** -```sh +```bash echo '[{"op": "replace", "path": "/parameters/rollout", "value": 50}]' | \ -http PATCH http://localhost:4242/api/admin/projects/default/features/demo/environments/production/strategies/ea5404e5-0c0d-488c-93b2-0a2200534827 Authorization:$KEY +http PATCH \ +http://localhost:4242/api/admin/projects/default/features/demo/environments/production/strategies/ea5404e5-0c0d-488c-93b2-0a2200534827 \ +Authorization:$KEY ``` **Example response:** @@ -478,13 +511,13 @@ http PATCH http://localhost:4242/api/admin/projects/default/features/demo/enviro **Example Query** -```sh +```bash http DELETE http://localhost:4242/api/admin/projects/default/features/demo/environments/production/strategies/77bbe972-ffce-49b2-94d9-326593e2228e Authorization:$KEY ``` **Example response:** -```sh +``` HTTP/1.1 200 OK Access-Control-Allow-Origin: * Connection: keep-alive @@ -499,13 +532,13 @@ Vary: Accept-Encoding **Example Query** -```sh +```bash http POST http://localhost:4242/api/admin/projects/default/features/demo/environments/development/on Authorization:$KEY --json ``` **Example response:** -```sh +``` HTTP/1.1 200 OK Access-Control-Allow-Origin: * Connection: keep-alive @@ -549,7 +582,7 @@ http PUT http://localhost:4242/api/admin/projects/default/features/demo/variants **Example response:** -```sh +```bash HTTP/1.1 200 OK Access-Control-Allow-Origin: * Connection: keep-alive @@ -579,13 +612,15 @@ Content-Type: application/json; charset=utf-8 **Example Query** -```sh +```bash echo '[{"op": "add", "path": "/1", "value": { "name": "new-variant", "weightType": "fix", "weight": 200 }}]' | \ -http PATCH http://localhost:4242/api/admin/projects/default/features/demo/variants Authorization:$KEY +http PATCH \ +http://localhost:4242/api/admin/projects/default/features/demo/variants \ +Authorization:$KEY ``` ** Example Response ** From 01f7293e2e5d6223e578e40c7e339484856cf0c5 Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Tue, 1 Feb 2022 15:20:18 +0100 Subject: [PATCH 2/9] docs: add description of the project users/roles endpoint --- .../docs/api/admin/feature-toggles-api-v2.md | 128 ++++++++++++++++++ 1 file changed, 128 insertions(+) diff --git a/website/docs/api/admin/feature-toggles-api-v2.md b/website/docs/api/admin/feature-toggles-api-v2.md index e52c8da374..411dc618ff 100644 --- a/website/docs/api/admin/feature-toggles-api-v2.md +++ b/website/docs/api/admin/feature-toggles-api-v2.md @@ -646,3 +646,131 @@ Authorization:$KEY ] } ``` + + +## Manage project users and roles + +You can add and remove users to a project using the `/api/admin/projects/:projectId/users/:userId/roles/:roleId` endpoint. When adding or removing users, you must also provide the ID for the role to give them (when adding) or the ID of the role they currently have (when removing). + +There is no way to update a user's role directly at the moment. Instead, if you want to change a user's role, first remove the user from the project and then add them back with the desired role. + +### 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. + +#### URL parameters + +| Parameter | Type | Description | Example value | +|-------------|---------|-----------------------------------------------------------------------|-------------------| +| `userId` | integer | The ID of the user you want to add to the project. | `1` | +| `projectId` | string | The id of the project to add the user to. | `"MyCoolProject"` | +| `roleId` | integer | The id of the role you want to assign to the new user in the project. | `7` | + + +#### Responses + +
+Responses data + +##### 200 OK + +The user was added to the project with the specified role. + +``` json +{ } +``` + +##### 400 Bad Request + +The user already exists in the project and cannot be added again: + +``` json +[ + { + "msg": "User already has access to project=" + } +] +``` + +
+ +#### Example query + +The following query would add the user with ID 42 to the _MyCoolProject_ project and give them the role with ID 13. + +```bash +http POST \ +http://localhost:4242/api/admin/projects/MyCoolProject/users/42/roles/13 \ +Authorization:$KEY +``` + +### Remove a user from a project + +``` http +DELETE /api/admin/projects/:projectId/users/:userId/roles/:roleId +``` + +This will remove the specified from user from the project. The user _must_ have the role indicated by the `:roleId` URL parameter for the request to succeed. + +#### URL parameters + +| Parameter | Type | Description | Example value | +|-------------|---------|-----------------------------------------------------------------------|-------------------| +| `userId` | integer | The ID of the user you want to remove from the project. | `1` | +| `projectId` | string | The id of the project to remove the user from. | `"MyCoolProject"` | +| `roleId` | integer | The current role the of the user you want to remove from the project. | `7` | + +#### Responses + +
+Responses data + +:::caution +If you provide the wrong role id for the user, but there is another user in the same project with the role you provided, you'll get a 200 OK response indicating success, but the user will not be removed. +::: + +##### 200 OK + +The user has been removed from the project. + +``` json +{ } +``` + +##### 400 Bad Request + +No user with the current role exists in the project: + + +``` json +[ + { + "msg": "Couldn't find roleId= on project=" + } +] +``` + +You tried to remove the only user with the role `owner` in the project: + +``` json +[ + { + "msg": "A project must have at least one owner." + } +] +``` + +
+ +#### Example query + +The following query would remove the user with ID 42 and role ID 13 from the _MyCoolProject_ project. +```bash +http DELETE \ +http://localhost:4242/api/admin/projects/MyCoolProject/users/42/roles/13 \ +Authorization:$KEY +``` From 81c6ef2d6ef66f4b95fd0a282cf8c76682f94d4e Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Tue, 1 Feb 2022 15:25:40 +0100 Subject: [PATCH 3/9] chore: align url parameters table. --- website/docs/api/admin/feature-toggles-api-v2.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/website/docs/api/admin/feature-toggles-api-v2.md b/website/docs/api/admin/feature-toggles-api-v2.md index 411dc618ff..8af81c3c3c 100644 --- a/website/docs/api/admin/feature-toggles-api-v2.md +++ b/website/docs/api/admin/feature-toggles-api-v2.md @@ -666,9 +666,9 @@ This will add a user to a project and give the user a specified role within that | Parameter | Type | Description | Example value | |-------------|---------|-----------------------------------------------------------------------|-------------------| -| `userId` | integer | The ID of the user you want to add to the project. | `1` | -| `projectId` | string | The id of the project to add the user to. | `"MyCoolProject"` | -| `roleId` | integer | The id of the role you want to assign to the new user in the project. | `7` | +| `userId` | integer | The ID of the user you want to add to the project. | `1` | +| `projectId` | string | The id of the project to add the user to. | `"MyCoolProject"` | +| `roleId` | integer | The id of the role you want to assign to the new user in the project. | `7` | #### Responses From 92349b5561d945a4b7106ed53b6ffd71f53227c2 Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Wed, 23 Feb 2022 10:36:50 +0100 Subject: [PATCH 4/9] Apply suggestions from code review Co-authored-by: Christopher Kolstad --- website/docs/api/admin/feature-toggles-api-v2.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/api/admin/feature-toggles-api-v2.md b/website/docs/api/admin/feature-toggles-api-v2.md index 8af81c3c3c..32cea43f3d 100644 --- a/website/docs/api/admin/feature-toggles-api-v2.md +++ b/website/docs/api/admin/feature-toggles-api-v2.md @@ -714,7 +714,7 @@ Authorization:$KEY DELETE /api/admin/projects/:projectId/users/:userId/roles/:roleId ``` -This will remove the specified from user from the project. The user _must_ have the role indicated by the `:roleId` URL parameter for the request to succeed. +This will remove the specified user from the project. The user _must_ have the role indicated by the `:roleId` URL parameter for the request to succeed. #### URL parameters From e84b8f30e1c189f776ae0ec5529f8f243682b07f Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Wed, 23 Feb 2022 10:39:13 +0100 Subject: [PATCH 5/9] docs: add correct return values for role deletion endpoints. --- website/docs/api/admin/feature-toggles-api-v2.md | 12 ++---------- 1 file changed, 2 insertions(+), 10 deletions(-) diff --git a/website/docs/api/admin/feature-toggles-api-v2.md b/website/docs/api/admin/feature-toggles-api-v2.md index 32cea43f3d..62bceb58a3 100644 --- a/website/docs/api/admin/feature-toggles-api-v2.md +++ b/website/docs/api/admin/feature-toggles-api-v2.md @@ -678,11 +678,7 @@ This will add a user to a project and give the user a specified role within that ##### 200 OK -The user was added to the project with the specified role. - -``` json -{ } -``` +The user was added to the project with the specified role. This response has no body. ##### 400 Bad Request @@ -735,11 +731,7 @@ If you provide the wrong role id for the user, but there is another user in the ##### 200 OK -The user has been removed from the project. - -``` json -{ } -``` +The user has been removed from the project. This response has no body. ##### 400 Bad Request From 9da796eb90ac674c0d2dde3648cab2654721e05e Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Wed, 23 Feb 2022 10:50:02 +0100 Subject: [PATCH 6/9] docs: add details for change role endpoint. --- .../docs/api/admin/feature-toggles-api-v2.md | 95 ++++++++++++++++++- 1 file changed, 93 insertions(+), 2 deletions(-) diff --git a/website/docs/api/admin/feature-toggles-api-v2.md b/website/docs/api/admin/feature-toggles-api-v2.md index 62bceb58a3..a4b4d5c325 100644 --- a/website/docs/api/admin/feature-toggles-api-v2.md +++ b/website/docs/api/admin/feature-toggles-api-v2.md @@ -652,8 +652,6 @@ Authorization:$KEY You can add and remove users to a project using the `/api/admin/projects/:projectId/users/:userId/roles/:roleId` endpoint. When adding or removing users, you must also provide the ID for the role to give them (when adding) or the ID of the role they currently have (when removing). -There is no way to update a user's role directly at the moment. Instead, if you want to change a user's role, first remove the user from the project and then add them back with the desired role. - ### Add a user to a project ``` http @@ -704,6 +702,55 @@ http://localhost:4242/api/admin/projects/MyCoolProject/users/42/roles/13 \ 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. + +#### URL parameters + +| Parameter | Type | Description | Example value | +|-------------|---------|------------------------------------------------------|-------------------| +| `userId` | integer | The ID of the user whose role you want to update. | `1` | +| `projectId` | string | The id of the relevant project. | `"MyCoolProject"` | +| `roleId` | integer | The role ID of the role you wish to assign the user. | `7` | + + +#### Responses + +
+Responses data + +##### 200 OK + +The user's role has been successfully changed. This response has no body. + +##### 400 Bad Request + +You tried to change the role of only user with the `owner` role in the project: + +``` json +[ + { + "msg": "A project must have at least one owner." + } +] +``` + +
+ +#### Example query + +The following query would change the role of the user with ID 42 the role with ID 13 in the _MyCoolProject_ project. +```bash +http PUT \ +http://localhost:4242/api/admin/projects/MyCoolProject/users/42/roles/13 \ +Authorization:$KEY +``` + ### Remove a user from a project ``` http @@ -720,6 +767,50 @@ This will remove the specified user from the project. The user _must_ have the r | `projectId` | string | The id of the project to remove the user from. | `"MyCoolProject"` | | `roleId` | integer | The current role the of the user you want to remove from the project. | `7` | + +#### Responses + +
+Responses data + +##### 200 OK + +The user has been removed from the project. This response has no body. + +##### 400 Bad Request + +No user with the current role exists in the project: + + +``` json +[ + { + "msg": "Couldn't find roleId= on project=" + } +] +``` + +You tried to remove the only user with the role `owner` in the project: + +``` json +[ + { + "msg": "A project must have at least one owner." + } +] +``` + +
+ +#### Example query + +The following query would remove the user with ID 42 and role ID 13 from the _MyCoolProject_ project. +```bash +http DELETE \ +http://localhost:4242/api/admin/projects/MyCoolProject/users/42/roles/13 \ +Authorization:$KEY +``` + #### Responses
From 38ed3816a89d08c13e4aa923705b51ec2952afc2 Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Thu, 3 Mar 2022 14:17:43 +0100 Subject: [PATCH 7/9] docs: Remove doubled section and clarify role removal --- .../docs/api/admin/feature-toggles-api-v2.md | 51 +------------------ 1 file changed, 2 insertions(+), 49 deletions(-) diff --git a/website/docs/api/admin/feature-toggles-api-v2.md b/website/docs/api/admin/feature-toggles-api-v2.md index a4b4d5c325..78e22b43cb 100644 --- a/website/docs/api/admin/feature-toggles-api-v2.md +++ b/website/docs/api/admin/feature-toggles-api-v2.md @@ -757,7 +757,7 @@ Authorization:$KEY DELETE /api/admin/projects/:projectId/users/:userId/roles/:roleId ``` -This will remove the specified user from the project. The user _must_ have the role indicated by the `:roleId` URL parameter for the request to succeed. +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. #### URL parameters @@ -775,54 +775,7 @@ This will remove the specified user from the project. The user _must_ have the r ##### 200 OK -The user has been removed from the project. This response has no body. - -##### 400 Bad Request - -No user with the current role exists in the project: - - -``` json -[ - { - "msg": "Couldn't find roleId= on project=" - } -] -``` - -You tried to remove the only user with the role `owner` in the project: - -``` json -[ - { - "msg": "A project must have at least one owner." - } -] -``` - -
- -#### Example query - -The following query would remove the user with ID 42 and role ID 13 from the _MyCoolProject_ project. -```bash -http DELETE \ -http://localhost:4242/api/admin/projects/MyCoolProject/users/42/roles/13 \ -Authorization:$KEY -``` - -#### Responses - -
-Responses data - -:::caution -If you provide the wrong role id for the user, but there is another user in the same project with the role you provided, you'll get a 200 OK response indicating success, but the user will not be removed. -::: - -##### 200 OK - -The user has been removed from the project. This response has no body. +The no longer has the specified role in the project. If the user had this role prior to this API request, they will have been removed from the project. This response has no body. ##### 400 Bad Request From c9dd60e1ea3b8af34fe8b8ea967de07631da6112 Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Fri, 4 Mar 2022 08:43:28 +0100 Subject: [PATCH 8/9] Apply suggestions from code review Co-authored-by: Christopher Kolstad --- website/docs/api/admin/feature-toggles-api-v2.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/website/docs/api/admin/feature-toggles-api-v2.md b/website/docs/api/admin/feature-toggles-api-v2.md index 78e22b43cb..9cd4b6272f 100644 --- a/website/docs/api/admin/feature-toggles-api-v2.md +++ b/website/docs/api/admin/feature-toggles-api-v2.md @@ -730,7 +730,7 @@ The user's role has been successfully changed. This response has no body. ##### 400 Bad Request -You tried to change the role of only user with the `owner` role in the project: +You tried to change the role of the only user with the `owner` role in the project: ``` json [ @@ -775,7 +775,7 @@ This removes the specified role from the user in the project. Because users can ##### 200 OK -The no longer has the specified role in the project. If the user had this role prior to this API request, they will have been removed from the project. This response has no body. +The user no longer has the specified role in the project. If the user had this role prior to this API request, they will have been removed from the project. This response has no body. ##### 400 Bad Request From 4705fe22cc574afc3476cbd32df83a9ef6073d21 Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Fri, 4 Mar 2022 10:41:24 +0100 Subject: [PATCH 9/9] docs: remove error payload that no longer applies. --- website/docs/api/admin/feature-toggles-api-v2.md | 11 ----------- 1 file changed, 11 deletions(-) diff --git a/website/docs/api/admin/feature-toggles-api-v2.md b/website/docs/api/admin/feature-toggles-api-v2.md index 9cd4b6272f..669b093cf9 100644 --- a/website/docs/api/admin/feature-toggles-api-v2.md +++ b/website/docs/api/admin/feature-toggles-api-v2.md @@ -779,17 +779,6 @@ The user no longer has the specified role in the project. If the user had this r ##### 400 Bad Request -No user with the current role exists in the project: - - -``` json -[ - { - "msg": "Couldn't find roleId= on project=" - } -] -``` - You tried to remove the only user with the role `owner` in the project: ``` json