From eca98af89693ec09eb68c8ab7f230d9852606367 Mon Sep 17 00:00:00 2001 From: Kegan Dougal Date: Thu, 15 Oct 2015 16:38:12 +0100 Subject: [PATCH] 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}}