From eca98af89693ec09eb68c8ab7f230d9852606367 Mon Sep 17 00:00:00 2001 From: Kegan Dougal Date: Thu, 15 Oct 2015 16:38:12 +0100 Subject: [PATCH 1/3] Swaggerify /register endpoint Need to move registration/login/auth sections around once #94 lands. --- api/client-server/v2_alpha/registration.yaml | 95 ++++++++++++++++++++ specification/1-client_server_api.rst | 49 ++-------- 2 files changed, 102 insertions(+), 42 deletions(-) create mode 100644 api/client-server/v2_alpha/registration.yaml diff --git a/api/client-server/v2_alpha/registration.yaml b/api/client-server/v2_alpha/registration.yaml new file mode 100644 index 00000000..ad591206 --- /dev/null +++ b/api/client-server/v2_alpha/registration.yaml @@ -0,0 +1,95 @@ +swagger: '2.0' +info: + title: "Matrix Client-Server v2 Registration API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https + - http +basePath: /_matrix/client/api/v2_alpha +consumes: + - application/json +produces: + - application/json +paths: + "/register": + post: + summary: Register for an account on this homeserver. + description: |- + Register for an account on this homeserver. + parameters: + - in: body + name: body + schema: + type: object + example: |- + { + "username": "cheeky_monkey", + "password": "ilovebananas", + "bind_email": false + } + properties: + bind_email: + type: boolean + description: |- + If true, the server binds the email used for authentication to + the Matrix ID with the ID Server. + username: + type: string + description: |- + The local part of the desired Matrix ID. If omitted, + the homeserver MUST generate a Matrix ID local part. + password: + type: string + description: The desired password for the account. + required: ["password"] + responses: + 200: + description: The account has been registered. + examples: + application/json: |- + { + "user_id": "@cheeky_monkey:matrix.org", + "access_token": "abc123", + "home_server": "matrix.org", + "refresh_token": "def456" + } + schema: + type: object + properties: + user_id: + type: string + description: The fully-qualified Matrix ID that has been registered. + access_token: + type: string + description: |- + An access token for the account. + This access token can then be used to authorize other requests. + The access token may expire at some point, and if so, it SHOULD come with a ``refresh_token``. + There is no specific error message to indicate that a request has failed because + an access token has expired; instead, if a client has reason to believe its + access token is valid, and it receives an auth error, they should attempt to + refresh for a new token on failure, and retry the request with the new token. + refresh_token: + type: string + # TODO: Work out how to linkify /tokenrefresh + description: |- + (optional) A ``refresh_token`` may be exchanged for a new ``access_token`` using the /tokenrefresh API endpoint. + home_server: + type: string + description: The hostname of the Home Server on which the account has been registered. + 400: + description: |- + Part of the request was invalid. For example, this user ID may be taken. This may + be returned at any stage of the registration process, including after authentication + if the requested user ID was registered whilst the client was performing authentication. + examples: + application/json: |- + { + "errcode": "M_USER_IN_USE", + "error": "Desired user ID is already taken." + } + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/error.yaml" diff --git a/specification/1-client_server_api.rst b/specification/1-client_server_api.rst index a63c114a..84de17da 100644 --- a/specification/1-client_server_api.rst +++ b/specification/1-client_server_api.rst @@ -1001,52 +1001,17 @@ member's state, by making a request to } -Registration ------------- -This section refers to API Version 2. These API calls currently use the prefix -``/_matrix/client/v2_alpha``. - -Registering for a user account is done using the request:: - - POST $V2PREFIX/register +Account operations +------------------ +Registration +~~~~~~~~~~~~ This API endpoint uses the User-Interactive Authentication API. -This API endpoint does not require an access token. -The body of the POST request is a JSON object containing: +{{v2_registration_http_api}} -username - Optional. This is the local part of the desired Matrix ID. If omitted, the - Home Server must generate a Matrix ID local part. -password - Required. The desired password for the account. -bind_email - Optional. If ``true``, the server binds the email used for authentication to - the Matrix ID with the ID Server. - -On success, this returns a JSON object with keys: - -user_id - The fully-qualified Matrix ID that has been registered. -access_token - An access token for the new account. -home_server - The hostname of the Home Server on which the account has been registered. - -This endpoint may also return the following error codes: - -M_USER_IN_USE - If the Matrix ID is already in use -M_EXCLUSIVE - If the requested Matrix ID is in the exclusive namespace of an application - service. - -Home Servers MUST perform the relevant checks and return these codes before -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. - -Old V1 API docs: |register|_ +Login +~~~~~ {{login_http_api}} From e0fe3c42c8cb58c994396310279a18b9fa8b9f01 Mon Sep 17 00:00:00 2001 From: Kegan Dougal Date: Fri, 16 Oct 2015 14:19:00 +0100 Subject: [PATCH 2/3] Review comments --- api/client-server/v2_alpha/registration.yaml | 12 +++++++++--- specification/1-client_server_api.rst | 2 +- 2 files changed, 10 insertions(+), 4 deletions(-) diff --git a/api/client-server/v2_alpha/registration.yaml b/api/client-server/v2_alpha/registration.yaml index ad591206..9973d0b4 100644 --- a/api/client-server/v2_alpha/registration.yaml +++ b/api/client-server/v2_alpha/registration.yaml @@ -80,9 +80,15 @@ paths: description: The hostname of the Home Server on which the account has been registered. 400: description: |- - Part of the request was invalid. For example, this user ID may be taken. This may - be returned at any stage of the registration process, including after authentication - if the requested user ID was registered whilst the client was performing authentication. + Part of the request was invalid. This may include one of the following error codes: + + * ``M_USER_IN_USE`` : The desired user ID is already taken. + * ``M_EXCLUSIVE`` : The desired user ID is in the exclusive namespace + claimed by an application service. + + This errors may be returned at any stage of the registration process, + including after authentication if the requested user ID was registered + whilst the client was performing authentication. examples: application/json: |- { diff --git a/specification/1-client_server_api.rst b/specification/1-client_server_api.rst index 84de17da..331f951a 100644 --- a/specification/1-client_server_api.rst +++ b/specification/1-client_server_api.rst @@ -1006,7 +1006,7 @@ Account operations Registration ~~~~~~~~~~~~ -This API endpoint uses the User-Interactive Authentication API. +This API endpoint uses the `User-Interactive Authentication API`_. {{v2_registration_http_api}} From f450fc1db6adb9cb76925e90aff8f3782081bb07 Mon Sep 17 00:00:00 2001 From: Kegan Dougal Date: Mon, 19 Oct 2015 13:32:43 +0100 Subject: [PATCH 3/3] Typo --- api/client-server/v2_alpha/registration.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/client-server/v2_alpha/registration.yaml b/api/client-server/v2_alpha/registration.yaml index 9973d0b4..5222b3f3 100644 --- a/api/client-server/v2_alpha/registration.yaml +++ b/api/client-server/v2_alpha/registration.yaml @@ -86,7 +86,7 @@ paths: * ``M_EXCLUSIVE`` : The desired user ID is in the exclusive namespace claimed by an application service. - This errors may be returned at any stage of the registration process, + These errors may be returned at any stage of the registration process, including after authentication if the requested user ID was registered whilst the client was performing authentication. examples: