From e6eb19c46115f1e324fa3c474341c627b4219cf9 Mon Sep 17 00:00:00 2001 From: Kegan Dougal Date: Wed, 14 Oct 2015 17:34:25 +0100 Subject: [PATCH] Review comments --- specification/1-client_server_api.rst | 37 +++++++++++++++++---------- 1 file changed, 24 insertions(+), 13 deletions(-) diff --git a/specification/1-client_server_api.rst b/specification/1-client_server_api.rst index 319fed91..ecd5a3e2 100644 --- a/specification/1-client_server_api.rst +++ b/specification/1-client_server_api.rst @@ -29,6 +29,9 @@ return with a status of 401 and the error code, ``M_MISSING_TOKEN`` or User-Interactive Authentication API ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. _sect:auth-api: + This section refers to API Version 2. Some API endpoints such as ``login`` or ``register`` require authentication that @@ -349,9 +352,11 @@ Registering for a user account is done using the request:: POST $V2PREFIX/register -This API endpoint uses the User-Interactive Authentication API. +This API endpoint uses the `User-Interactive Authentication API`_. This API endpoint does not require an access token. +.. _User-Interactive Authentication API: `sect:auth-api`_ + The body of the POST request is a JSON object containing: username @@ -371,6 +376,9 @@ access_token An access token for the new account. home_server The hostname of the Home Server on which the account has been registered. +refresh_token + A token that may be exchanged for a new ``access_token`` using the + ``/tokenrefresh`` API endpoint. This endpoint may also return the following error codes: @@ -381,10 +389,12 @@ M_EXCLUSIVE service. Home Servers MUST perform the relevant checks and return these codes before -performing User-Interactive Authentication, although they may also return +performing `User-Interactive Authentication`_, although they may also return them after authentication is completed if, for example, the requested user ID was registered whilst the client was performing authentication. +.. _User-Interactive Authentication: `sect:auth-api`_ + Old V1 API docs: |register|_ {{login_http_api}} @@ -414,8 +424,8 @@ The error code M_NOT_FOUND is returned if the user authenticated with a third party identifier but the Home Server could not find a matching account in its database. -Adding a Third Party Identifier -+++++++++++++++++++++++++++++++ +Adding Account Administrative Contact Information ++++++++++++++++++++++++++++++++++++++++++++++++++ This section refers to API Version 2. These API calls currently use the prefix ``/_matrix/client/v2_alpha``. @@ -423,18 +433,18 @@ Request:: POST $V2PREFIX/account/3pid -Used to add a third party identifier to the user's account. +Used to add contact information to the user's account. The body of the POST request is a JSON object containing: threePidCreds - An object containing third party identifier credentials. + An object containing contact information. bind Optional. A boolean indicating whether the Home Server should also bind this third party identifier to the account's matrix ID with the Identity Server. If supplied and true, the Home Server must bind the 3pid accordingly. -The third party identifier credentials object comprises: +The contact information object comprises: id_server The colon-separated hostname and port of the Identity Server used to @@ -452,8 +462,8 @@ May also return error codes: M_THREEPID_AUTH_FAILED If the credentials provided could not be verified with the ID Server. -Fetching Currently Associated Third Party Identifiers -+++++++++++++++++++++++++++++++++++++++++++++++++++++ +Fetching Currently Associated Contact Information ++++++++++++++++++++++++++++++++++++++++++++++++++ This section refers to API Version 2. These API calls currently use the prefix ``/_matrix/client/v2_alpha``. @@ -706,8 +716,8 @@ Pagination Pagination is the process of dividing a dataset into multiple discrete pages. Matrix makes use of pagination to allow clients to view extremely large datasets. These datasets are not limited to events in a room (for example clients may want -to paginate rooms in addition to events within those rooms). Regardless of *what* -is being paginated, there is a common underlying API which is used to +to paginate a list of rooms in addition to events within those rooms). Regardless +of *what* is being paginated, there is a common underlying API which is used to to give clients a consistent way of selecting subsets of a potentially changing dataset. Requests pass in ``from``, ``to``, ``dir`` and ``limit`` parameters which describe where to read from the stream. ``from`` and ``to`` are opaque @@ -800,13 +810,14 @@ Rooms Creation ~~~~~~~~ -The home server will create a ``m.room.create`` event when a room is created, +The home server will create an ``m.room.create`` event when a room is created, which serves as the root of the event graph for this room. This event also has a ``creator`` key which contains the user ID of the room creator. It will also generate several other events in order to manage permissions in this room. This includes: - - ``m.room.power_levels`` : Sets the power levels of users and required power levels. + - ``m.room.power_levels`` : Sets the power levels of users and required power + levels for various actions within the room such as sending events. - ``m.room.join_rules`` : Whether the room is "invite-only" or not. See `Room Events`_ for more information on these events. To create a room, a