Clean up admin api docs (#7361)

pull/7332/head
Andrew Morgan 2020-04-28 20:06:03 +01:00 committed by GitHub
parent 04dd7d182d
commit c58ae367d8
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 43 additions and 18 deletions

1
changelog.d/7361.doc Normal file
View File

@ -0,0 +1 @@
Clarify endpoint usage in the users admin api documentation.

View File

@ -33,12 +33,22 @@ with a body of:
including an ``access_token`` of a server admin. including an ``access_token`` of a server admin.
The parameter ``displayname`` is optional and defaults to ``user_id``. The parameter ``displayname`` is optional and defaults to the value of
The parameter ``threepids`` is optional. ``user_id``.
The parameter ``avatar_url`` is optional.
The parameter ``admin`` is optional and defaults to 'false'. The parameter ``threepids`` is optional and allows setting the third-party IDs
The parameter ``deactivated`` is optional and defaults to 'false'. (email, msisdn) belonging to a user.
The parameter ``password`` is optional. If provided the user's password is updated and all devices are logged out.
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. If the user already exists then optional parameters default to the current value.
List Accounts List Accounts
@ -51,16 +61,25 @@ The api is::
GET /_synapse/admin/v2/users?from=0&limit=10&guests=false GET /_synapse/admin/v2/users?from=0&limit=10&guests=false
including an ``access_token`` of a server admin. 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 ``from`` is optional but used for pagination, denoting the
The parameter ``user_id`` can be used to select only users with user ids that offset in the returned results. This should be treated as an opaque value and
contain this value. not explicitly set to anything other than the return value of ``next_token``
The parameter ``guests=false`` can be used to exclude guest users, from a previous call.
default is to include guest users.
The parameter ``deactivated=true`` can be used to include deactivated users, The parameter ``limit`` is optional but is used for pagination, denoting the
default is to exclude deactivated users. maximum number of items to return in this call. Defaults to ``100``.
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 ``user_id`` is optional and filters to only users with user IDs
that contain this value.
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.
A JSON body is returned with the following shape:
.. code:: json .. code:: json
@ -73,7 +92,7 @@ It returns a JSON body like the following:
"admin": 0, "admin": 0,
"user_type": null, "user_type": null,
"deactivated": 0, "deactivated": 0,
"displayname": <User One>, "displayname": "<User One>",
"avatar_url": null "avatar_url": null
}, { }, {
"name": "<user_id2>", "name": "<user_id2>",
@ -82,7 +101,7 @@ It returns a JSON body like the following:
"admin": 1, "admin": 1,
"user_type": null, "user_type": null,
"deactivated": 0, "deactivated": 0,
"displayname": <User Two>, "displayname": "<User Two>",
"avatar_url": "<avatar_url>" "avatar_url": "<avatar_url>"
} }
], ],
@ -90,6 +109,11 @@ It returns a JSON body like the following:
"total": 200 "total": 200
} }
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 Query Account
============= =============