From 6edafe6b604af71b4e9ed7b79e5c0d69888bffa9 Mon Sep 17 00:00:00 2001 From: Jacob Shandling Date: Wed, 25 Dec 2024 18:17:45 -0800 Subject: [PATCH 1/6] add missing doc for existing API behavior --- docs/REST API/rest-api.md | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/docs/REST API/rest-api.md b/docs/REST API/rest-api.md index a8f27e1db01..9f6b1101c55 100644 --- a/docs/REST API/rest-api.md +++ b/docs/REST API/rest-api.md @@ -297,7 +297,7 @@ Resets a user's password. Which user is determined by the password reset token u Retrieves the user data for the authenticated user. -`GET /api/v1/fleet/me` +`GET /api/v1/**fleet**/me` #### Example @@ -321,7 +321,14 @@ Retrieves the user data for the authenticated user. "gravatar_url": "", "sso_enabled": false, "teams": [] - } + }, + "available_teams" : [ + { + "id": 1, + "name": "Workstations", + "description": "Employee workstations" + } + ] } ``` From e938969a3ca88a28e31cad28069518f82aeaaf7c Mon Sep 17 00:00:00 2001 From: Jacob Shandling Date: Wed, 25 Dec 2024 18:27:33 -0800 Subject: [PATCH 2/6] add proposed changes for this work --- docs/REST API/rest-api.md | 28 ++++++++++++++++++++++++++-- 1 file changed, 26 insertions(+), 2 deletions(-) diff --git a/docs/REST API/rest-api.md b/docs/REST API/rest-api.md index 9f6b1101c55..cab74710487 100644 --- a/docs/REST API/rest-api.md +++ b/docs/REST API/rest-api.md @@ -299,9 +299,15 @@ Retrieves the user data for the authenticated user. `GET /api/v1/**fleet**/me` +#### Parameters + +| Name | Type | In | Description | +|:------------------- |:------- |:----- |:------------------------------------------------| +| include_ui_settings | boolean | query | Include the user's ui settings (default: false) | + #### Example -`GET /api/v1/fleet/me` +`GET /api/v1/fleet/me?include_ui_settings=true` ##### Default response @@ -328,7 +334,25 @@ Retrieves the user data for the authenticated user. "name": "Workstations", "description": "Employee workstations" } - ] + ], + "ui_settings": { + "hidden_hosts_table_columns": [ + "hostname", + "computer_name", + "device_mapping", + "primary_mac", + "public_ip", + "cpu_type", + "mdm.server_url", + "mdm.enrollment_status", + "memory", + "uptime", + "uuid", + "seen_time", + "hardware_model", + "hardware_serial", + ] + } } ``` From 953c19407adce40d0a645c9aa413930c513dc668 Mon Sep 17 00:00:00 2001 From: Jacob Shandling Date: Fri, 27 Dec 2024 18:14:34 -0800 Subject: [PATCH 3/6] updates --- docs/REST API/rest-api.md | 54 +++++++++++++++++++++++++++++++++------ 1 file changed, 46 insertions(+), 8 deletions(-) diff --git a/docs/REST API/rest-api.md b/docs/REST API/rest-api.md index cab74710487..57bce860e6d 100644 --- a/docs/REST API/rest-api.md +++ b/docs/REST API/rest-api.md @@ -297,13 +297,13 @@ Resets a user's password. Which user is determined by the password reset token u Retrieves the user data for the authenticated user. -`GET /api/v1/**fleet**/me` +`GET /api/v1/fleet/me` #### Parameters | Name | Type | In | Description | |:------------------- |:------- |:----- |:------------------------------------------------| -| include_ui_settings | boolean | query | Include the user's ui settings (default: false) | +| include_settings | boolean | query | Include the user's settings (default: false) | #### Example @@ -335,7 +335,7 @@ Retrieves the user data for the authenticated user. "description": "Employee workstations" } ], - "ui_settings": { + "settings": { "hidden_hosts_table_columns": [ "hostname", "computer_name", @@ -11170,13 +11170,14 @@ Returns all information about a specific user. #### Parameters -| Name | Type | In | Description | -| ---- | ------- | ---- | ---------------------------- | -| id | integer | path | **Required**. The user's id. | +| Name | Type | In | Description | +| ---------------- | ------- | -----| --------------------------------------------- | +| id | integer | path | **Required**. The user's id. | +| include_settings | boolean | query | Include the user's settings (default: false) | #### Example -`GET /api/v1/fleet/users/2` +`GET /api/v1/fleet/users/2?include_settings=true` ##### Default response @@ -11197,6 +11198,24 @@ Returns all information about a specific user. "global_role": "admin", "api_only": false, "teams": [] + }, + "settings": { + "hidden_hosts_table_columns": [ + "hostname", + "computer_name", + "device_mapping", + "primary_mac", + "public_ip", + "cpu_type", + "mdm.server_url", + "mdm.enrollment_status", + "memory", + "uptime", + "uuid", + "seen_time", + "hardware_model", + "hardware_serial", + ] } } ``` @@ -11236,6 +11255,7 @@ Returns all information about a specific user. | new_password| string | body | The user's new password. | | global_role | string | body | The role assigned to the user. In Fleet 4.0.0, 3 user roles were introduced (`admin`, `maintainer`, and `observer`). If `global_role` is specified, `teams` cannot be specified. | | teams | array | body | _Available in Fleet Premium_. The teams and respective roles assigned to the user. Should contain an array of objects in which each object includes the team's `id` and the user's `role` on each team. In Fleet 4.0.0, 3 user roles were introduced (`admin`, `maintainer`, and `observer`). If `teams` is specified, `global_role` cannot be specified. | +| settings | object | body | Optional user-specific settings. #### Example @@ -11246,7 +11266,25 @@ Returns all information about a specific user. ```json { "name": "Jane Doe", - "global_role": "admin" + "global_role": "admin", + "settings": { + "hidden_hosts_table_columns": [ + "hostname", + "computer_name", + "device_mapping", + "primary_mac", + "public_ip", + "cpu_type", + "mdm.server_url", + "mdm.enrollment_status", + "memory", + "uptime", + "uuid", + "seen_time", + "hardware_model", + "hardware_serial", + ] + } } ``` From cfb420bea715ced9a8a8a76375e32fb1a3b9da11 Mon Sep 17 00:00:00 2001 From: Jacob Shandling Date: Fri, 3 Jan 2025 11:13:20 -0800 Subject: [PATCH 4/6] update example url --- docs/REST API/rest-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/REST API/rest-api.md b/docs/REST API/rest-api.md index 57bce860e6d..716b6f144e7 100644 --- a/docs/REST API/rest-api.md +++ b/docs/REST API/rest-api.md @@ -307,7 +307,7 @@ Retrieves the user data for the authenticated user. #### Example -`GET /api/v1/fleet/me?include_ui_settings=true` +`GET /api/v1/fleet/me?include_settings=true` ##### Default response From 77a293806bba81ff3293ea662e4d70f8e9d0c7af Mon Sep 17 00:00:00 2001 From: Jacob Shandling Date: Tue, 7 Jan 2025 11:53:35 -0800 Subject: [PATCH 5/6] remove contributor-only functionality from rest-api docs --- docs/REST API/rest-api.md | 74 ++++----------------------------------- 1 file changed, 6 insertions(+), 68 deletions(-) diff --git a/docs/REST API/rest-api.md b/docs/REST API/rest-api.md index 716b6f144e7..8ef899c796c 100644 --- a/docs/REST API/rest-api.md +++ b/docs/REST API/rest-api.md @@ -299,15 +299,9 @@ Retrieves the user data for the authenticated user. `GET /api/v1/fleet/me` -#### Parameters - -| Name | Type | In | Description | -|:------------------- |:------- |:----- |:------------------------------------------------| -| include_settings | boolean | query | Include the user's settings (default: false) | - #### Example -`GET /api/v1/fleet/me?include_settings=true` +`GET /api/v1/fleet/me` ##### Default response @@ -335,24 +329,6 @@ Retrieves the user data for the authenticated user. "description": "Employee workstations" } ], - "settings": { - "hidden_hosts_table_columns": [ - "hostname", - "computer_name", - "device_mapping", - "primary_mac", - "public_ip", - "cpu_type", - "mdm.server_url", - "mdm.enrollment_status", - "memory", - "uptime", - "uuid", - "seen_time", - "hardware_model", - "hardware_serial", - ] - } } ``` @@ -11170,14 +11146,13 @@ Returns all information about a specific user. #### Parameters -| Name | Type | In | Description | -| ---------------- | ------- | -----| --------------------------------------------- | -| id | integer | path | **Required**. The user's id. | -| include_settings | boolean | query | Include the user's settings (default: false) | +| Name | Type | In | Description | +| ---- | ------- | ---- | ---------------------------- | +| id | integer | path | **Required**. The user's id. | #### Example -`GET /api/v1/fleet/users/2?include_settings=true` +`GET /api/v1/fleet/users/2` ##### Default response @@ -11198,24 +11173,6 @@ Returns all information about a specific user. "global_role": "admin", "api_only": false, "teams": [] - }, - "settings": { - "hidden_hosts_table_columns": [ - "hostname", - "computer_name", - "device_mapping", - "primary_mac", - "public_ip", - "cpu_type", - "mdm.server_url", - "mdm.enrollment_status", - "memory", - "uptime", - "uuid", - "seen_time", - "hardware_model", - "hardware_serial", - ] } } ``` @@ -11255,7 +11212,6 @@ Returns all information about a specific user. | new_password| string | body | The user's new password. | | global_role | string | body | The role assigned to the user. In Fleet 4.0.0, 3 user roles were introduced (`admin`, `maintainer`, and `observer`). If `global_role` is specified, `teams` cannot be specified. | | teams | array | body | _Available in Fleet Premium_. The teams and respective roles assigned to the user. Should contain an array of objects in which each object includes the team's `id` and the user's `role` on each team. In Fleet 4.0.0, 3 user roles were introduced (`admin`, `maintainer`, and `observer`). If `teams` is specified, `global_role` cannot be specified. | -| settings | object | body | Optional user-specific settings. #### Example @@ -11266,25 +11222,7 @@ Returns all information about a specific user. ```json { "name": "Jane Doe", - "global_role": "admin", - "settings": { - "hidden_hosts_table_columns": [ - "hostname", - "computer_name", - "device_mapping", - "primary_mac", - "public_ip", - "cpu_type", - "mdm.server_url", - "mdm.enrollment_status", - "memory", - "uptime", - "uuid", - "seen_time", - "hardware_model", - "hardware_serial", - ] - } + "global_role": "admin" } ``` From a1a3d1e8e471a0547c72ef668aa464f869d0c4ee Mon Sep 17 00:00:00 2001 From: Jacob Shandling Date: Thu, 9 Jan 2025 13:49:57 -0800 Subject: [PATCH 6/6] Add contributor documentation for new query param funcitonality --- docs/Contributing/API-for-contributors.md | 99 +++++++++++++++++++++++ 1 file changed, 99 insertions(+) diff --git a/docs/Contributing/API-for-contributors.md b/docs/Contributing/API-for-contributors.md index f90663de317..35a736f52c2 100644 --- a/docs/Contributing/API-for-contributors.md +++ b/docs/Contributing/API-for-contributors.md @@ -12,6 +12,7 @@ - [Setup](#setup) - [Scripts](#scripts) - [Software](#software) +- [Users](#users) > These endpoints are used by the Fleet UI, Fleet Desktop, and `fleetctl` clients and frequently change to reflect current functionality. @@ -4197,3 +4198,101 @@ Content-Disposition: attachment Content-Length: Body: ``` +## Users + +### Update user-specific UI settings + +`PATCH /api/v1/fleet/users/:id` + +#### Parameters + +| Name | Type | In | Description | +| --------- | ------ | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| settings | object | body | The updated user settings. | + +#### Example + +`PATCH /api/v1/fleet/users/1` +```json +{ + "hidden_host_columns": ["hostname"] +} +``` + +##### Default response +* Note that user settings are *not* included in this response. See below `GET`s for how to get user settings. +`Status: 200` +```json +{ + "user": { + "created_at": "2025-01-08T01:04:23Z", + "updated_at": "2025-01-09T00:08:19Z", + "id": 1, + "name": "Sum Bahdee", + "email": "sum@org.com", + "force_password_reset": false, + "gravatar_url": "", + "sso_enabled": false, + "mfa_enabled": false, + "global_role": "admin", + "api_only": false, + "teams": [] + } +} +``` + +### Include settings when getting a user + +`GET /api/v1/fleet/users/:id?include_ui_settings=true` + +Use of `include_ui_settings=true` is considered the contributor API functionality – without that +param, this endpoint is considered a documented REST API endpoint + +#### Parameters + +| Name | Type | In | Description | +| ------------------- | ------ | ----- | --------------------------------------------------------------------------------------------------| +| include_ui_settings | bool | query | If `true`, will include the user's settings in the response. For now, this is a single ui setting. + +#### Example + +`GET /api/v1/fleet/users/2/?include_ui_settings=true` + +##### Default response + +`Status: 200` +```json +{ + "user": {...}, + "available_teams": {...} + "settings": {"hidden_host_columns": ["hostname"]}, +} +``` + +### Include settings when getting current user + +`GET /api/v1/fleet/me/?include_ui_settings=true` + +Use of `include_ui_settings=true` is considered the contributor API functionality – without that +param, this endpoint is considered a documented REST API endpoint + +#### Parameters + +| Name | Type | In | Description | +| ------------------- | ------ | ----- | --------------------------------------------------------------------------------------------------| +| include_ui_settings | bool | query | If `true`, will include the user's settings in the response. For now, this is a single ui setting. + +#### Example + +`GET /api/v1/fleet/me?include_ui_settings=true` + +##### Default response + +`Status: 200` +```json +{ + "user": {...}, + "available_teams": {...} + "settings": {"hidden_host_columns": ["hostname"]}, +} +```