From 15cdde3f49e174f65e1369235e600dff561503e3 Mon Sep 17 00:00:00 2001
From: Travis Ralston <travpc@gmail.com>
Date: Tue, 6 Mar 2018 13:16:07 -0700
Subject: [PATCH] Add GET /register/available

Adds https://github.com/matrix-org/matrix-doc/issues/911

Signed-off-by: Travis Ralston <travpc@gmail.com>
---
 api/client-server/registration.yaml | 60 +++++++++++++++++++++++++++++
 1 file changed, 60 insertions(+)

diff --git a/api/client-server/registration.yaml b/api/client-server/registration.yaml
index fd8f6832..b008f1b5 100644
--- a/api/client-server/registration.yaml
+++ b/api/client-server/registration.yaml
@@ -366,3 +366,63 @@ paths:
             "$ref": "definitions/error.yaml"
       tags:
         - User data
+  "/register/available":
+    get:
+      summary: Checks to see if a username is available on the server.
+      description: |-
+        Checks to see if a username is available, and valid, for the server.
+
+        The server should check to ensure that, at the time of the request, the
+        username requested is available for use. This includes verifying that an
+        application service has not claimed the username and that the username
+        fits the server's desired requirements (for example, a server could dictate
+        that it does not permit usernames with underscores).
+
+        Matrix clients may wish to use this API prior to attempting registration,
+        however the clients must also be aware that using this API does not normally
+        reserve the username. This can mean that the username becomes unavailable
+        between checking it's availability and attempting to register it.
+      operationId: checkUsernameAvailability
+      parameters:
+        - in: query
+          name: username
+          type: string
+          x-example: my_cool_localpart
+          required: true
+          default: my_cool_localpart
+          description: The username to check the availability of.
+      responses:
+        200:
+          description: The username is available
+          examples:
+            application/json: {
+              "available": true
+            }
+          schema:
+            type: object
+            properties:
+              available:
+                type: boolean
+                description: |-
+                  A flag to indicate that the username is available. This should always
+                  be ``true`` when the server replies with 200 OK.
+        400:
+          description: |-
+            Part of the request was invalid or the username is not available. This may 
+            include one of the following error codes:
+
+            * ``M_USER_IN_USE`` : The desired username is already taken.
+            * ``M_INVALID_USERNAME`` : The desired username is not a valid user name.
+            * ``M_EXCLUSIVE`` : The desired username is in the exclusive namespace
+              claimed by an application service.
+          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"
+      tags:
+        - User data