User api review markup

.gitignore

@@ -118,10 +118,9 @@ docs/public/
 modules/**/generated/
 
 # PyCharm and Mac
-.idea
+.idea/*
 # Exception: share IntelliJ project dictionary so the team's
 # ThoughtSpot-specific terms don't show as spell-check typos.
-!.idea/
 !.idea/dictionaries/
 !.idea/dictionaries/*.xml
 .DS_store

REVIEW-MARKUP.md

@@ -0,0 +1,49 @@
+# Review markup — user-api v2 change
+
+**This branch (`user-api-review-markup`) must not be merged.** It exists only so
+reviewers can see, in the rendered docs preview, which blocks changed as part of
+the REST API v1 -> v2 user-api update.
+
+Content on this branch is identical to `user-api`; the only additions are
+`reviewChanged` roles and the stylesheet rule that draws them.
+
+## What it looks like
+
+Edited blocks get a purple bar in the left margin and a faint purple tint.
+Changed section headings also get a small `CHANGED` badge. Works in light and
+dark themes.
+
+## What is highlighted
+
+Blocks added since `773dbd06` (the last commit before this effort):
+
+| File | Marked blocks |
+|---|---|
+| `modules/ROOT/pages/user-api.adoc` | 20 — the page deprecation banner + all 19 per-endpoint DEPRECATED notes |
+| `modules/ROOT/pages/api-user-management.adoc` | 15 — new/rewritten sections, 2 admonitions, the restored v2 endpoint table |
+| `modules/ROOT/pages/partials/user-api-list.adoc` | 1 — the deprecation banner above the table |
+
+## What is NOT highlighted
+
+Three kinds of edit cannot carry a block-level marker:
+
+1. **The new "REST API v2 replacement" column** in `user-api-list.adoc`. A role
+   applies to a whole table, not one column. The banner above it is marked
+   instead; the column itself is self-evidently new.
+2. **`roles-api.adoc` and `roles.adoc`** (4 lines). These are an anchor rename,
+   `#_role_privileges` -> `#_role_categories_and_privileges`, inside existing
+   xrefs. Nothing about the rendered page changes, so there is nothing to show.
+3. **Prose reworded in place** inside otherwise-unchanged blocks — the marker is
+   per block, so a block is either flagged or not.
+
+For line-exact review, use the diff: `git diff 773dbd06..user-api -- '*.adoc'`
+
+## Removing it
+
+Preferred: delete the branch. Nothing here belongs in `user-api`.
+
+    git branch -D user-api-review-markup
+
+If you instead want to keep some of this branch, strip the markup first:
+
+    ./scripts/strip-review-markup.sh

modules/ROOT/pages/partials/user-api-list.adoc

@@ -1,69 +1,93 @@
 
 
+[IMPORTANT.reviewChanged]
+====
+All endpoints in this table belong to the deprecated REST API v1 framework. Use the REST API v2 replacement listed for each endpoint in new implementations. For more information, see xref:rest-api-v1v2-comparison.adoc[REST API v1 and v2 comparison].
+====
+
 [div tableContainer]
 --
-[width="100%" cols="2,1"]
+[width="100%" cols="2,1,2"]
 [options='header']
 |=====
-|API endpoint| Available from
+|API endpoint| Available from| REST API v2 replacement
 |`xref:user-api.adoc#create-user[**POST** /tspublic/v1/user/]` +
 Creates a user account. |ThoughtSpot Cloud [version noBackground]#ts7.jun.cl# +
 ThoughtSpot Software [version noBackground]#7.1.1#
+|`POST /api/rest/2.0/users/create`
 |`xref:user-api.adoc#activate-user[**POST** /tspublic/v1/user/activate]` +
 Activates a user account.|ThoughtSpot Cloud [version noBackground]#ts7.sep.cl# +
 ThoughtSpot Software [version noBackground]#7.2.1#
+|`POST /api/rest/2.0/users/activate`
 |`xref:user-api.adoc#update-user[*PUT* /tspublic/v1/user/{userid}]` +
 Modifies a user account.|ThoughtSpot Cloud [version noBackground]#ts7.aug.cl# +
 ThoughtSpot Software [version noBackground]#7.1.1#
+|`POST /api/rest/2.0/users/{user_identifier}/update`
 |`xref:user-api.adoc#addEmail[**PUT** /tspublic/v1/user/email]` +
 Modifies the email address of a user.|ThoughtSpot Cloud [version noBackground]#ts7.oct.cl# +
 ThoughtSpot Software [version noBackground]#7.2.1#
+|`POST /api/rest/2.0/users/{user_identifier}/update`
 |`xref:user-api.adoc#addOrg[*POST* /tspublic/v1/user/addtoorg]` +
 Adds one or several users to the specified Org.
 |ThoughtSpot Cloud [version noBackground]#8.10.0.cl# +
 ThoughtSpot Software [version noBackground]#Not available#
+|`POST /api/rest/2.0/users/{user_identifier}/update`
 
 |`xref:user-api.adoc#get-user-details[*GET* /tspublic/v1/user/]` +
 Gets details of the users in a ThoughtSpot system.|ThoughtSpot Cloud [version noBackground]#ts7.oct.cl# +
 ThoughtSpot Software [version noBackground]#7.1.1#
+|`POST /api/rest/2.0/users/search`
 |`xref:user-api.adoc#delete-user[*DELETE* /tspublic/v1/user/{userid}]` +
 Deletes a user account.|ThoughtSpot Cloud [version noBackground]#ts7.oct.cl# +
 ThoughtSpot Software [version noBackground]#7.1.1#
+|`POST /api/rest/2.0/users/{user_identifier}/delete`
 |`xref:user-api.adoc#user-list[*GET* /tspublic/v1/user/list]` +
 Gets all users, groups, and their inter-dependencies.|ThoughtSpot Cloud [version noBackground]#ts7.april.cl# +
 ThoughtSpot Software [version noBackground]#6.0.x#
+|`POST /api/rest/2.0/users/search` and `POST /api/rest/2.0/groups/search`
 |`xref:user-api.adoc#updatepreference-api[**POST** /tspublic/v1/user/updatepreference]` +
 Modifies a user profile.|ThoughtSpot Cloud [version noBackground]#ts7.jun.cl# +
 ThoughtSpot Software [version noBackground]#7.1.1#
+|`POST /api/rest/2.0/users/{user_identifier}/update`
 |`xref:user-api.adoc#transfer-ownership[**POST** /tspublic/v1/user/transfer/ownership]` +
 Transfers the ownership of objects from one user to another.|ThoughtSpot Cloud [version noBackground]#ts7.april.cl# +
 ThoughtSpot Software [version noBackground]#6.0.x#
+|`POST /api/rest/2.0/security/metadata/assign`
 |`xref:user-api.adoc#change-pwd[**POST** /tspublic/v1/user/updatepassword]` +
 Changes the password of a user account.|ThoughtSpot Cloud [version noBackground]#ts7.april.cl# +
 ThoughtSpot Software [version noBackground]#6.0.x#
+|`POST /api/rest/2.0/users/change-password`
 |`xref:user-api.adoc#resetpassword[**POST** /tspublic/v1/user/resetpassword]` +
 Resets the password of a user account.|ThoughtSpot Cloud [version noBackground]#ts7.sep.cl# +
 ThoughtSpot Software [version noBackground]#7.2.1#
+|`POST /api/rest/2.0/users/reset-password`
 |`xref:user-api.adoc#invalidate-user-session[**POST** /tspublic/v1/user/session/invalidate]` +
 Invalidates a user session.|ThoughtSpot Cloud [version noBackground]#ts7.sep.cl# +
 ThoughtSpot Software [version noBackground]#7.2.1#
+|`POST /api/rest/2.0/users/force-logout`
 |`xref:user-api.adoc#deactivate-user[**POST** /tspublic/v1/user/inactivate]` +
 Deactivates a user account.|ThoughtSpot Cloud [version noBackground]#ts7.sep.cl# +
 ThoughtSpot Software [version noBackground]#7.2.1#
+|`POST /api/rest/2.0/users/deactivate`
 |`xref:user-api.adoc#user-sync[**POST** /tspublic/v1/user/sync]` +
 Synchronizes user and group properties from an external database with the user data on ThoughtSpot.|ThoughtSpot Cloud [version noBackground]#ts7.april.cl# +
 ThoughtSpot Software [version noBackground]#6.0.x#
+|`POST /api/rest/2.0/users/import`
 |`xref:user-api.adoc#assignUserToGroups[**POST** /tspublic/v1/user/{userid}/groups]` +
 Assigns a user to the specified user groups.|ThoughtSpot Cloud [version noBackground]#ts7.oct.cl# +
 ThoughtSpot Software [version noBackground]#7.2.1#
+|`POST /api/rest/2.0/users/{user_identifier}/update`
 |`xref:user-api.adoc#getGroupsUser[**GET** /tspublic/v1/user/{userid}/groups]` +
 Gets details of the user groups associated with a specific user.|ThoughtSpot Cloud [version noBackground]#ts7.oct.cl# +
 ThoughtSpot Software [version noBackground]#7.2.1#
+|`POST /api/rest/2.0/users/search`
 |`xref:user-api.adoc#editGroupsforUser[**PUT** /tspublic/v1/user/{userid}/groups]` +
 Updates the user group data for a specific user.|ThoughtSpot Cloud [version noBackground]#ts7.oct.cl# +
 ThoughtSpot Software [version noBackground]#7.2.1#
+|`POST /api/rest/2.0/users/{user_identifier}/update`
 |`xref:user-api.adoc#removeUserGroupAssoc[**DELETE** /tspublic/v1/user/{userid}/groups]` +
 Removes a user from the specified user groups.|ThoughtSpot Cloud [version noBackground]#ts7.oct.cl# +
 ThoughtSpot Software [version noBackground]#7.2.1#
+|`POST /api/rest/2.0/users/{user_identifier}/update`
 |=====
 --

modules/ROOT/pages/roles-api.adoc

@@ -35,7 +35,7 @@ POST /tspublic/v1/role
 |Form parameter|Description
 |`name` |__String__. Name of the Role. The Role name string must be unique. Make sure the name string length does not exceed 48 characters.
 |`description`|__String__. Description of the Role. Make sure the description text does not exceed 124 characters.
-|`privileges`|__Array of strings__. A JSON array of xref:roles.adoc#_role_privileges[Role privileges].
+|`privileges`|__Array of strings__. A JSON array of xref:roles.adoc#_role_categories_and_privileges[Role privileges].
 |===
 
 === Example request
@@ -112,7 +112,7 @@ PUT /tspublic/v1/role/{role_identifier}
 |`role_identifier`|Path parameter|__String__. GUID of the role object to edit.
 |`name` |Form parameter|__String__. Name of the Role that you want to edit.
 |`description`|Form parameter|__String__. Description of the Role.
-|`privileges`|Form parameter|__Array of strings__. A JSON array of xref:roles.adoc#_role_privileges[Role privileges].
+|`privileges`|Form parameter|__Array of strings__. A JSON array of xref:roles.adoc#_role_categories_and_privileges[Role privileges].
 |===
 
 === Example request
@@ -193,7 +193,7 @@ POST /tspublic/v1/role/search
 
 NOTE: Cluster administrators with the `Super admin` Role can query Role objects for different Orgs. The cluster administrator can switch to an Org context via an API call to the `/tspublic/v1/session/orgs` endpoint, and then specify the Org name or ID in the API request.
 |`group_identifiers`|__Array of strings__. A JSON array of group names or GUIDs.
-|`privileges`|__Array of strings__. A JSON array of xref:roles.adoc#_role_privileges[Role privileges].
+|`privileges`|__Array of strings__. A JSON array of xref:roles.adoc#_role_categories_and_privileges[Role privileges].
 |===
 
 

modules/ROOT/pages/roles.adoc

@@ -36,7 +36,7 @@ This privilege grants administration permissions to manage users and groups on i
 * Authentication administration: __Can manage Authentication__
 * Application administration: __Can manage Application settings__
 
-For a complete list of Roles and privileges, see xref:roles.adoc#_role_privileges[Role categories and privileges].
+For a complete list of Roles and privileges, see xref:roles.adoc#_role_categories_and_privileges[Role categories and privileges].
 |====
 
 == Role assignment