From 895bf98196dbce761b499bb1d14ad9f66a0c9f3f Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Tue, 28 Apr 2020 18:04:45 +0100 Subject: [PATCH 1/4] Clean up user admin api docs --- docs/admin_api/user_admin_api.rst | 56 ++++++++++++++++++++++--------- 1 file changed, 40 insertions(+), 16 deletions(-) diff --git a/docs/admin_api/user_admin_api.rst b/docs/admin_api/user_admin_api.rst index 9ce10119ff5e..fb8ff70da60b 100644 --- a/docs/admin_api/user_admin_api.rst +++ b/docs/admin_api/user_admin_api.rst @@ -33,12 +33,22 @@ with a body of: including an ``access_token`` of a server admin. -The parameter ``displayname`` is optional and defaults to ``user_id``. -The parameter ``threepids`` is optional. -The parameter ``avatar_url`` is optional. -The parameter ``admin`` is optional and defaults to 'false'. -The parameter ``deactivated`` is optional and defaults to 'false'. -The parameter ``password`` is optional. If provided the user's password is updated and all devices are logged out. +The parameter ``displayname`` is optional and defaults to the value of +``user_id``. + +The parameter ``threepids`` is optional and allows setting the third-party IDs +(email, msisdn) belonging to a user. + +The parameter ``avatar_url`` is optional. Must be a [MXC +URI](https://matrix.org/docs/spec/client_server/r0.6.0#matrix-content-mxc-uris). + +The parameter ``admin`` is optional and defaults to ``false``. + +The parameter ``deactivated`` is optional and defaults to ``false``. + +The parameter ``password`` is optional. If provided, the user's password is +updated and all devices are logged out. + If the user already exists then optional parameters default to the current value. List Accounts @@ -51,16 +61,25 @@ The api is:: GET /_synapse/admin/v2/users?from=0&limit=10&guests=false including an ``access_token`` of a server admin. -The parameters ``from`` and ``limit`` are required only for pagination. -By default, a ``limit`` of 100 is used. -The parameter ``user_id`` can be used to select only users with user ids that -contain this value. -The parameter ``guests=false`` can be used to exclude guest users, -default is to include guest users. -The parameter ``deactivated=true`` can be used to include deactivated users, -default is to exclude deactivated users. -If the endpoint does not return a ``next_token`` then there are no more users left. -It returns a JSON body like the following: + +The parameter ``from`` is optional but used for pagination, denoting the +offset in the returned results. This should be treated as an opaque value and +not explicitly set to anything other than the return value of ``next_token`` +from a previous call. + +The parameter ``limit`` is optional but is used for pagination, denoting the +maximum number of items to return in this call. Defaults to ``100``. + +The parameter ``user_id`` is optional and filters to only users with user IDs +that contain this value. + +The parameter ``guests`` is optional and if ``true`` will **exclude** guest users. +Defaults to ``false`` to include guest users. + +The parameter ``deactivated`` is optional and if ``true`` will **include** deactivated users. +Defaults to ``false`` to exclude deactivated users. + +A JSON body is returned with the following shape: .. code:: json @@ -85,6 +104,11 @@ It returns a JSON body like the following: "next_token": "100" } +To paginate, check for ``next_token`` and if present, call the endpoint again +with ``from`` set to the value of ``next_token``. This will return a new page. + +If the endpoint does not return a ``next_token`` then there are no more users +to paginate through. Query Account ============= From 84654ae4c9f1bb986b4340a6dc54a278a4db3b04 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Tue, 28 Apr 2020 18:13:51 +0100 Subject: [PATCH 2/4] Add changelog --- changelog.d/7361.doc | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelog.d/7361.doc diff --git a/changelog.d/7361.doc b/changelog.d/7361.doc new file mode 100644 index 000000000000..b35dbc36eeb2 --- /dev/null +++ b/changelog.d/7361.doc @@ -0,0 +1 @@ +Clarify endpoint usage in the users admin api documentation. \ No newline at end of file From 372a453f27d9951a23f977d22cd7d1bf863d85ac Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Tue, 28 Apr 2020 18:20:34 +0100 Subject: [PATCH 3/4] Surround example displaynames in quotes --- docs/admin_api/user_admin_api.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/admin_api/user_admin_api.rst b/docs/admin_api/user_admin_api.rst index 096bffe62db9..cf7e7fb4100e 100644 --- a/docs/admin_api/user_admin_api.rst +++ b/docs/admin_api/user_admin_api.rst @@ -92,7 +92,7 @@ A JSON body is returned with the following shape: "admin": 0, "user_type": null, "deactivated": 0, - "displayname": , + "displayname": "", "avatar_url": null }, { "name": "", @@ -101,7 +101,7 @@ A JSON body is returned with the following shape: "admin": 1, "user_type": null, "deactivated": 0, - "displayname": , + "displayname": "", "avatar_url": "" } ], From bc4ee174ceae31d3086161ac73605df707d333ec Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Tue, 28 Apr 2020 18:26:35 +0100 Subject: [PATCH 4/4] fix guest parameter description as true is false and up is down --- docs/admin_api/user_admin_api.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/admin_api/user_admin_api.rst b/docs/admin_api/user_admin_api.rst index cf7e7fb4100e..859d7f99e7c8 100644 --- a/docs/admin_api/user_admin_api.rst +++ b/docs/admin_api/user_admin_api.rst @@ -73,8 +73,8 @@ maximum number of items to return in this call. Defaults to ``100``. The parameter ``user_id`` is optional and filters to only users with user IDs that contain this value. -The parameter ``guests`` is optional and if ``true`` will **exclude** guest users. -Defaults to ``false`` to include guest users. +The parameter ``guests`` is optional and if ``false`` will **exclude** guest users. +Defaults to ``true`` to include guest users. The parameter ``deactivated`` is optional and if ``true`` will **include** deactivated users. Defaults to ``false`` to exclude deactivated users.