Merge pull request #1151 from turt2live/travis/username-availability

Add GET /register/available

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 its 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

changelogs/client_server.rst

@@ -32,6 +32,8 @@ Unreleased changes
     (`#1141 <https://github.com/matrix-org/matrix-doc/pull/1141>`_).
   - Add spec for ignoring users
     (`#1142 <https://github.com/matrix-org/matrix-doc/pull/1142>`_).
+  - Add the ``/register/available`` endpoint for username availability
+    (`#1151 <https://github.com/matrix-org/matrix-doc/pull/1151>`_).
 
 r0.3.0
 ======