Move raw API and event schemas into /data directory
Historical note: this was originally a series of several commits, spread out over several weeks. They have been squashed together to make `git annotate` work properly. The original commits were: * 91ab3934 <Will> 2021-01-25 21:16:42 -0800 Add raw API end event schemas into /data directory * aae22f47 <Will> 2021-01-25 21:33:06 -0800 Remove non-data files * 1092d4ca <Will> 2021-01-26 20:41:33 -0800 Add data-compatiuble extension (.yaml) to all data files that currently omit one * 21060109 <Will> 2021-01-26 20:57:28 -0800 Remove symlink to event-schemas, and update openAPI schema paths accordingly * 4f633845 <Travis Ralston> 2021-04-12 21:54:54 -0600 Fix event schema examples too * 301c7b2f <Will> 2021-02-05 10:15:42 -0800 Restore docs describing OpenAPI extensions that we use
This commit is contained in:
Will
Richard van der Hoff
parent
a26c352d78
commit
00c6a866e2
327 changed files with 82 additions and 10822 deletions
637
data/api/client-server/registration.yaml
Normal file
637
data/api/client-server/registration.yaml
Normal file
|
|
@ -0,0 +1,637 @@
|
|||
# Copyright 2016 OpenMarket Ltd
|
||||
#
|
||||
# Licensed under the Apache License, Version 2.0 (the "License");
|
||||
# you may not use this file except in compliance with the License.
|
||||
# You may obtain a copy of the License at
|
||||
#
|
||||
# http://www.apache.org/licenses/LICENSE-2.0
|
||||
#
|
||||
# Unless required by applicable law or agreed to in writing, software
|
||||
# distributed under the License is distributed on an "AS IS" BASIS,
|
||||
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
# See the License for the specific language governing permissions and
|
||||
# limitations under the License.
|
||||
swagger: '2.0'
|
||||
info:
|
||||
title: "Matrix Client-Server Registration API"
|
||||
version: "1.0.0"
|
||||
host: localhost:8008
|
||||
schemes:
|
||||
- https
|
||||
- http
|
||||
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
|
||||
consumes:
|
||||
- application/json
|
||||
produces:
|
||||
- application/json
|
||||
paths:
|
||||
"/register":
|
||||
post:
|
||||
summary: Register for an account on this homeserver.
|
||||
description: |-
|
||||
This API endpoint uses the `User-Interactive Authentication API`_, except in
|
||||
the cases where a guest account is being registered.
|
||||
|
||||
Register for an account on this homeserver.
|
||||
|
||||
There are two kinds of user account:
|
||||
|
||||
- `user` accounts. These accounts may use the full API described in this specification.
|
||||
|
||||
- `guest` accounts. These accounts may have limited permissions and may not be supported by all servers.
|
||||
|
||||
If registration is successful, this endpoint will issue an access token
|
||||
the client can use to authorize itself in subsequent requests.
|
||||
|
||||
If the client does not supply a ``device_id``, the server must
|
||||
auto-generate one.
|
||||
|
||||
The server SHOULD register an account with a User ID based on the
|
||||
``username`` provided, if any. Note that the grammar of Matrix User ID
|
||||
localparts is restricted, so the server MUST either map the provided
|
||||
``username`` onto a ``user_id`` in a logical manner, or reject
|
||||
``username``\s which do not comply to the grammar, with
|
||||
``M_INVALID_USERNAME``.
|
||||
|
||||
Matrix clients MUST NOT assume that localpart of the registered
|
||||
``user_id`` matches the provided ``username``.
|
||||
|
||||
The returned access token must be associated with the ``device_id``
|
||||
supplied by the client or generated by the server. The server may
|
||||
invalidate any access token previously associated with that device. See
|
||||
`Relationship between access tokens and devices`_.
|
||||
|
||||
When registering a guest account, all parameters in the request body
|
||||
with the exception of ``initial_device_display_name`` MUST BE ignored
|
||||
by the server. The server MUST pick a ``device_id`` for the account
|
||||
regardless of input.
|
||||
|
||||
Any user ID returned by this API must conform to the grammar given in the
|
||||
`Matrix specification <../appendices.html#user-identifiers>`_.
|
||||
operationId: register
|
||||
parameters:
|
||||
- in: query
|
||||
name: kind
|
||||
type: string
|
||||
# swagger-UI overrides the default with the example, so better make the
|
||||
# example the default.
|
||||
x-example: user
|
||||
required: false
|
||||
default: user
|
||||
enum:
|
||||
- guest
|
||||
- user
|
||||
description: The kind of account to register. Defaults to ``user``.
|
||||
- in: body
|
||||
name: body
|
||||
required: true
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
auth:
|
||||
description: |-
|
||||
Additional authentication information for the
|
||||
user-interactive authentication API. Note that this
|
||||
information is *not* used to define how the registered user
|
||||
should be authenticated, but is instead used to
|
||||
authenticate the ``register`` call itself.
|
||||
allOf:
|
||||
- "$ref": "definitions/auth_data.yaml"
|
||||
username:
|
||||
type: string
|
||||
description: |-
|
||||
The basis for the localpart of the desired Matrix ID. If omitted,
|
||||
the homeserver MUST generate a Matrix ID local part.
|
||||
example: cheeky_monkey
|
||||
password:
|
||||
type: string
|
||||
description: The desired password for the account.
|
||||
example: ilovebananas
|
||||
device_id:
|
||||
type: string
|
||||
description: |-
|
||||
ID of the client device. If this does not correspond to a
|
||||
known client device, a new device will be created. The server
|
||||
will auto-generate a device_id if this is not specified.
|
||||
example: GHTYAJCE
|
||||
initial_device_display_name:
|
||||
type: string
|
||||
description: |-
|
||||
A display name to assign to the newly-created device. Ignored
|
||||
if ``device_id`` corresponds to a known device.
|
||||
example: Jungle Phone
|
||||
inhibit_login:
|
||||
type: boolean
|
||||
description: |-
|
||||
If true, an ``access_token`` and ``device_id`` should not be
|
||||
returned from this call, therefore preventing an automatic
|
||||
login. Defaults to false.
|
||||
example: false
|
||||
responses:
|
||||
200:
|
||||
description: The account has been registered.
|
||||
examples:
|
||||
application/json: {
|
||||
"user_id": "@cheeky_monkey:matrix.org",
|
||||
"access_token": "abc123",
|
||||
"device_id": "GHTYAJCE"
|
||||
}
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
user_id:
|
||||
type: string
|
||||
description: |-
|
||||
The fully-qualified Matrix user ID (MXID) that has been registered.
|
||||
|
||||
Any user ID returned by this API must conform to the grammar given in the
|
||||
`Matrix specification <../appendices.html#user-identifiers>`_.
|
||||
access_token:
|
||||
type: string
|
||||
description: |-
|
||||
An access token for the account.
|
||||
This access token can then be used to authorize other requests.
|
||||
Required if the ``inhibit_login`` option is false.
|
||||
home_server:
|
||||
type: string
|
||||
description: |-
|
||||
The server_name of the homeserver on which the account has
|
||||
been registered.
|
||||
|
||||
**Deprecated**. Clients should extract the server_name from
|
||||
``user_id`` (by splitting at the first colon) if they require
|
||||
it. Note also that ``homeserver`` is not spelt this way.
|
||||
device_id:
|
||||
type: string
|
||||
description: |-
|
||||
ID of the registered device. Will be the same as the
|
||||
corresponding parameter in the request, if one was specified.
|
||||
Required if the ``inhibit_login`` option is false.
|
||||
required: ['user_id']
|
||||
400:
|
||||
description: |-
|
||||
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_INVALID_USERNAME`` : The desired user ID is not a valid user name.
|
||||
* ``M_EXCLUSIVE`` : The desired user ID is in the exclusive namespace
|
||||
claimed by an application service.
|
||||
|
||||
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.
|
||||
|
||||
Homeservers 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.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "M_USER_IN_USE",
|
||||
"error": "Desired user ID is already taken."
|
||||
}
|
||||
schema:
|
||||
"$ref": "definitions/errors/error.yaml"
|
||||
401:
|
||||
description: |-
|
||||
The homeserver requires additional authentication information.
|
||||
schema:
|
||||
"$ref": "definitions/auth_response.yaml"
|
||||
403:
|
||||
description: |-
|
||||
The homeserver does not permit registering the account. This response
|
||||
can be used to identify that a particular ``kind`` of account is not
|
||||
allowed, or that registration is generally not supported by the homeserver.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "M_FORBIDDEN",
|
||||
"error": "Registration is disabled"
|
||||
}
|
||||
schema:
|
||||
"$ref": "definitions/errors/error.yaml"
|
||||
429:
|
||||
description: This request was rate-limited.
|
||||
schema:
|
||||
"$ref": "definitions/errors/rate_limited.yaml"
|
||||
tags:
|
||||
- User data
|
||||
"/register/email/requestToken":
|
||||
post:
|
||||
summary: Begins the validation process for an email to be used during registration.
|
||||
description: |-
|
||||
The homeserver must check that the given email address is **not**
|
||||
already associated with an account on this homeserver. The homeserver
|
||||
should validate the email itself, either by sending a validation email
|
||||
itself or by using a service it has control over.
|
||||
operationId: requestTokenToRegisterEmail
|
||||
parameters:
|
||||
- in: body
|
||||
name: body
|
||||
required: true
|
||||
schema:
|
||||
$ref: "definitions/request_email_validation.yaml"
|
||||
responses:
|
||||
200:
|
||||
description: |-
|
||||
An email has been sent to the specified address. Note that this
|
||||
may be an email containing the validation token or it may be
|
||||
informing the user of an error.
|
||||
schema:
|
||||
$ref: "definitions/request_token_response.yaml"
|
||||
403:
|
||||
description: The homeserver does not permit the address to be bound.
|
||||
schema:
|
||||
$ref: "definitions/errors/error.yaml"
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "M_THREEPID_DENIED",
|
||||
"error": "Third party identifier is not allowed"
|
||||
}
|
||||
400:
|
||||
description: |-
|
||||
Part of the request was invalid. This may include one of the following error codes:
|
||||
|
||||
* ``M_THREEPID_IN_USE`` : The email address is already registered to an account on this server.
|
||||
However, if the homeserver has the ability to send email, it is recommended that the server
|
||||
instead send an email to the user with instructions on how to reset their password.
|
||||
This prevents malicious parties from being able to determine if a given email address
|
||||
has an account on the homeserver in question.
|
||||
* ``M_SERVER_NOT_TRUSTED`` : The ``id_server`` parameter refers to an identity server
|
||||
that is not trusted by this homeserver.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "M_THREEPID_IN_USE",
|
||||
"error": "The specified address is already in use"
|
||||
}
|
||||
schema:
|
||||
"$ref": "definitions/errors/error.yaml"
|
||||
"/register/msisdn/requestToken":
|
||||
post:
|
||||
summary: Requests a validation token be sent to the given phone number for the purpose of registering an account
|
||||
description: |-
|
||||
The homeserver must check that the given phone number is **not**
|
||||
already associated with an account on this homeserver. The homeserver
|
||||
should validate the phone number itself, either by sending a validation
|
||||
message itself or by using a service it has control over.
|
||||
operationId: requestTokenToRegisterMSISDN
|
||||
parameters:
|
||||
- in: body
|
||||
name: body
|
||||
required: true
|
||||
schema:
|
||||
$ref: "definitions/request_msisdn_validation.yaml"
|
||||
responses:
|
||||
200:
|
||||
description: |-
|
||||
An SMS message has been sent to the specified phone number. Note
|
||||
that this may be an SMS message containing the validation token or
|
||||
it may be informing the user of an error.
|
||||
schema:
|
||||
$ref: "definitions/request_token_response.yaml"
|
||||
403:
|
||||
description: The homeserver does not permit the address to be bound.
|
||||
schema:
|
||||
$ref: "definitions/errors/error.yaml"
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "M_THREEPID_DENIED",
|
||||
"error": "Third party identifier is not allowed"
|
||||
}
|
||||
400:
|
||||
description: |-
|
||||
Part of the request was invalid. This may include one of the following error codes:
|
||||
|
||||
* ``M_THREEPID_IN_USE`` : The phone number is already registered to an account on this server.
|
||||
However, if the homeserver has the ability to send SMS message, it is recommended that the server
|
||||
instead send an SMS message to the user with instructions on how to reset their password.
|
||||
This prevents malicious parties from being able to determine if a given phone number
|
||||
has an account on the homeserver in question.
|
||||
* ``M_SERVER_NOT_TRUSTED`` : The ``id_server`` parameter refers to an identity server
|
||||
that is not trusted by this homeserver.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "M_THREEPID_IN_USE",
|
||||
"error": "The specified address is already in use"
|
||||
}
|
||||
schema:
|
||||
"$ref": "definitions/errors/error.yaml"
|
||||
"/account/password":
|
||||
post:
|
||||
summary: "Changes a user's password."
|
||||
description: |-
|
||||
Changes the password for an account on this homeserver.
|
||||
|
||||
This API endpoint uses the `User-Interactive Authentication API`_ to
|
||||
ensure the user changing the password is actually the owner of the
|
||||
account.
|
||||
|
||||
An access token should be submitted to this endpoint if the client has
|
||||
an active session.
|
||||
|
||||
The homeserver may change the flows available depending on whether a
|
||||
valid access token is provided. The homeserver SHOULD NOT revoke the
|
||||
access token provided in the request. Whether other access tokens for
|
||||
the user are revoked depends on the request parameters.
|
||||
security:
|
||||
- accessToken: []
|
||||
operationId: changePassword
|
||||
parameters:
|
||||
- in: body
|
||||
name: body
|
||||
required: true
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
new_password:
|
||||
type: string
|
||||
description: The new password for the account.
|
||||
example: "ihatebananas"
|
||||
logout_devices:
|
||||
type: boolean
|
||||
description: |-
|
||||
Whether the user's other access tokens, and their associated devices, should be
|
||||
revoked if the request succeeds. Defaults to true.
|
||||
|
||||
When ``false``, the server can still take advantage of `the soft logout method <#soft-logout>`_
|
||||
for the user's remaining devices.
|
||||
example: true
|
||||
auth:
|
||||
description: |-
|
||||
Additional authentication information for the user-interactive authentication API.
|
||||
allOf:
|
||||
- "$ref": "definitions/auth_data.yaml"
|
||||
required: ["new_password"]
|
||||
responses:
|
||||
200:
|
||||
description: The password has been changed.
|
||||
examples:
|
||||
application/json: {}
|
||||
schema:
|
||||
type: object
|
||||
401:
|
||||
description: |-
|
||||
The homeserver requires additional authentication information.
|
||||
schema:
|
||||
"$ref": "definitions/auth_response.yaml"
|
||||
429:
|
||||
description: This request was rate-limited.
|
||||
schema:
|
||||
"$ref": "definitions/errors/rate_limited.yaml"
|
||||
tags:
|
||||
- User data
|
||||
"/account/password/email/requestToken":
|
||||
post:
|
||||
summary: Requests a validation token be sent to the given email address for the purpose of resetting a user's password
|
||||
description: |-
|
||||
The homeserver must check that the given email address **is
|
||||
associated** with an account on this homeserver. This API should be
|
||||
used to request validation tokens when authenticating for the
|
||||
``/account/password`` endpoint.
|
||||
|
||||
This API's parameters and response are identical to that of the
|
||||
|/register/email/requestToken|_ endpoint, except that
|
||||
``M_THREEPID_NOT_FOUND`` may be returned if no account matching the
|
||||
given email address could be found. The server may instead send an
|
||||
email to the given address prompting the user to create an account.
|
||||
``M_THREEPID_IN_USE`` may not be returned.
|
||||
|
||||
The homeserver should validate the email itself, either by sending a
|
||||
validation email itself or by using a service it has control over.
|
||||
|
||||
|
||||
.. |/register/email/requestToken| replace:: ``/register/email/requestToken``
|
||||
|
||||
.. _/register/email/requestToken: #post-matrix-client-%CLIENT_MAJOR_VERSION%-register-email-requesttoken
|
||||
operationId: requestTokenToResetPasswordEmail
|
||||
parameters:
|
||||
- in: body
|
||||
name: body
|
||||
required: true
|
||||
schema:
|
||||
$ref: "definitions/request_email_validation.yaml"
|
||||
responses:
|
||||
200:
|
||||
description: An email was sent to the given address.
|
||||
schema:
|
||||
$ref: "definitions/request_token_response.yaml"
|
||||
403:
|
||||
description: |-
|
||||
The homeserver does not allow the third party identifier as a
|
||||
contact option.
|
||||
schema:
|
||||
$ref: "definitions/errors/error.yaml"
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "M_THREEPID_DENIED",
|
||||
"error": "Third party identifier is not allowed"
|
||||
}
|
||||
400:
|
||||
description: |-
|
||||
The referenced third party identifier is not recognised by the
|
||||
homeserver, or the request was invalid. The error code ``M_SERVER_NOT_TRUSTED``
|
||||
can be returned if the server does not trust/support the identity server
|
||||
provided in the request.
|
||||
schema:
|
||||
$ref: "definitions/errors/error.yaml"
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "M_THREEPID_NOT_FOUND",
|
||||
"error": "Email not found"
|
||||
}
|
||||
"/account/password/msisdn/requestToken":
|
||||
post:
|
||||
summary: Requests a validation token be sent to the given phone number for the purpose of resetting a user's password.
|
||||
description: |-
|
||||
The homeserver must check that the given phone number **is
|
||||
associated** with an account on this homeserver. This API should be
|
||||
used to request validation tokens when authenticating for the
|
||||
``/account/password`` endpoint.
|
||||
|
||||
This API's parameters and response are identical to that of the
|
||||
|/register/msisdn/requestToken|_ endpoint, except that
|
||||
``M_THREEPID_NOT_FOUND`` may be returned if no account matching the
|
||||
given phone number could be found. The server may instead send the SMS
|
||||
to the given phone number prompting the user to create an account.
|
||||
``M_THREEPID_IN_USE`` may not be returned.
|
||||
|
||||
The homeserver should validate the phone number itself, either by sending a
|
||||
validation message itself or by using a service it has control over.
|
||||
|
||||
.. |/register/msisdn/requestToken| replace:: ``/register/msisdn/requestToken``
|
||||
|
||||
.. _/register/msisdn/requestToken: #post-matrix-client-%CLIENT_MAJOR_VERSION%-register-email-requesttoken
|
||||
operationId: requestTokenToResetPasswordMSISDN
|
||||
parameters:
|
||||
- in: body
|
||||
name: body
|
||||
required: true
|
||||
schema:
|
||||
$ref: "definitions/request_msisdn_validation.yaml"
|
||||
responses:
|
||||
200:
|
||||
description: An SMS message was sent to the given phone number.
|
||||
schema:
|
||||
$ref: "definitions/request_token_response.yaml"
|
||||
403:
|
||||
description: |-
|
||||
The homeserver does not allow the third party identifier as a
|
||||
contact option.
|
||||
schema:
|
||||
$ref: "definitions/errors/error.yaml"
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "M_THREEPID_DENIED",
|
||||
"error": "Third party identifier is not allowed"
|
||||
}
|
||||
400:
|
||||
description: |-
|
||||
The referenced third party identifier is not recognised by the
|
||||
homeserver, or the request was invalid. The error code ``M_SERVER_NOT_TRUSTED``
|
||||
can be returned if the server does not trust/support the identity server
|
||||
provided in the request.
|
||||
schema:
|
||||
$ref: "definitions/errors/error.yaml"
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "M_THREEPID_NOT_FOUND",
|
||||
"error": "Phone number not found"
|
||||
}
|
||||
"/account/deactivate":
|
||||
post:
|
||||
summary: "Deactivate a user's account."
|
||||
description: |-
|
||||
Deactivate the user's account, removing all ability for the user to
|
||||
login again.
|
||||
|
||||
This API endpoint uses the `User-Interactive Authentication API`_.
|
||||
|
||||
An access token should be submitted to this endpoint if the client has
|
||||
an active session.
|
||||
|
||||
The homeserver may change the flows available depending on whether a
|
||||
valid access token is provided.
|
||||
|
||||
Unlike other endpoints, this endpoint does not take an ``id_access_token``
|
||||
parameter because the homeserver is expected to sign the request to the
|
||||
identity server instead.
|
||||
security:
|
||||
- accessToken: []
|
||||
operationId: deactivateAccount
|
||||
parameters:
|
||||
- in: body
|
||||
name: body
|
||||
required: true
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
auth:
|
||||
description: |-
|
||||
Additional authentication information for the user-interactive authentication API.
|
||||
allOf:
|
||||
- $ref: "definitions/auth_data.yaml"
|
||||
id_server:
|
||||
type: string
|
||||
description: |-
|
||||
The identity server to unbind all of the user's 3PIDs from.
|
||||
If not provided, the homeserver MUST use the ``id_server``
|
||||
that was originally use to bind each identifier. If the
|
||||
homeserver does not know which ``id_server`` that was,
|
||||
it must return an ``id_server_unbind_result`` of
|
||||
``no-support``.
|
||||
example: "example.org"
|
||||
responses:
|
||||
200:
|
||||
description: The account has been deactivated.
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
id_server_unbind_result:
|
||||
type: string
|
||||
enum:
|
||||
- "success"
|
||||
- "no-support"
|
||||
description: |-
|
||||
An indicator as to whether or not the homeserver was able to unbind
|
||||
the user's 3PIDs from the identity server(s). ``success`` indicates
|
||||
that all identifiers have been unbound from the identity server while
|
||||
``no-support`` indicates that one or more identifiers failed to unbind
|
||||
due to the identity server refusing the request or the homeserver
|
||||
being unable to determine an identity server to unbind from. This
|
||||
must be ``success`` if the homeserver has no identifiers to unbind
|
||||
for the user.
|
||||
example: "success"
|
||||
required:
|
||||
- id_server_unbind_result
|
||||
401:
|
||||
description: |-
|
||||
The homeserver requires additional authentication information.
|
||||
schema:
|
||||
"$ref": "definitions/auth_response.yaml"
|
||||
429:
|
||||
description: This request was rate-limited.
|
||||
schema:
|
||||
"$ref": "definitions/errors/rate_limited.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."
|
||||
}
|
||||
schema:
|
||||
"$ref": "definitions/errors/error.yaml"
|
||||
429:
|
||||
description: This request was rate-limited.
|
||||
schema:
|
||||
"$ref": "definitions/errors/rate_limited.yaml"
|
||||
tags:
|
||||
- User data
|
||||
Loading…
Add table
Add a link
Reference in a new issue