23971 Proposed API and schema changes (#25013)

## For #25034 ### API changes: [this PR diff](https://github.com/fleetdm/fleet/pull/25013/files) ("available_teams" change is adding missing documentation for current API behavior) ### schema changes: - new col in `users` table, `settings`, type `json`. Defaults to `{}`. New setting, `hidden_host_columns`, added or updated on first relevant API call per user. ### semantics - **null** `"hidden_host_columns"` field means "not yet set, use defaults": `{"settings":{"hidden_host_columns": null}}` - **included and empty** `"hidden_host_columns"` field means "no columns hidden, show all columns in the UI": `{"settings":{"hidden_host_columns": []}}` ### Updates 1/7/25 per discussion with @rachaelshaw @lucasmrod @sgress454: - Optional query param `include_ui_settings=true` included with `GET`s to `/me` or `/users/:id` will trigger considering the API call to be a contributor API call, giving more flexibility for future changes. Note that this is the first time we have one endpoint that can be conditionally considered a contributor endpoint depending on how it is called. --------- Co-authored-by: Jacob Shandling <jacob@fleetdm.com>
2025-03-10 10:17:57 -07:00
parent 13003cf5fc
commit 1268036c1f
2 changed files with 107 additions and 1 deletions
@@ -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.

@@ -4258,3 +4259,101 @@ Content-Disposition: attachment
 Content-Length: <length>
 Body: <blob>
 ```
+## 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"]},
+}
+```
@@ -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"
+    }
+  ],
 }
 ```