UserController

struct UserController : APIRouteCollection

The collection of /api/v3/user/* route endpoints and handler functions related to a user’s own data.

Separating these from the endpoints related to users in general helps make for a cleaner collection, since use of User.parameter in the paths here can be avoided entirely.

Show on GitHub

Properties

  • An array of words used to generate random phrases.

    Declaration

    Swift

    static let words: [String]
    Show on GitHub

  • Required. Registers routes to the incoming router.

    Declaration

    Swift

    func registerRoutes(_ app: Application) throws
    Show on GitHub

Open Access Handlers

  • createHandler(_:) Asynchronous

    POST /api/v3/user/create

    Creates a new User account. Does not log the new user in. Route is open access.

    A CreatedUserData structure is returned on success, containing the new user’s ID, username and a generated recovery key.

    Note

    The CreatedUserData.recoveryKey is a random phrase used to recover an account in the case of a forgotten password. While it can be stored by a client, that essentially defeats its purpose (presumably the password would also already be stored). The intended client use is that it is displayed to the user upon successful creation, and the user is encouraged to take a screenshot or write it down before proceeding.

    Throws

    400 error if the username is an invalid format. 409 errpr if the username is not available.

    Declaration

    Swift

    func createHandler(_ req: Request) async throws -> Response

    Parameters

    requestBody

    Return Value

    CreatedUserData containing the newly created user’s ID, username, and a recovery key string.

    Show on GitHub

tokenAuthGroup Handlers (logged in)

  • verifyHandler(_:) Asynchronous

    POST /api/v3/user/verify

    Changes a User.accessLevel from .unverified to .verified on successful submission of a registration code. User must be logged in.

    NOTE: previously it was possible to create an account and NOT provide a Registration Code, creating an account with an access level of .unverified. We now require a registration code to create an account and all accounts are therefore already verified at creation time, meaning this method is not currently useful.

    Throws

    400 error if the user is already verified or the registration code is not a valid one. 409 error if the registration code has already been allocated to another user.

    Declaration

    Swift

    func verifyHandler(_ req: Request) async throws -> HTTPStatus

    Parameters

    requestBody

    Return Value

    HTTP status 200 on success.

    Show on GitHub
  • addHandler(_:) Asynchronous

    POST /api/v3/user/add

    Adds a new User sub-account to the current user’s primary account. You can create a new sub account while logged in on a sub account, but the new account is an sub of the primary account–there’s no nesting or tree structure.

    This method does not log in the newly created user. Users are limited to Settings.shared.maxAlternateAccounts alts, which is 6 by default.

    An AddedUserData structure is returned on success, containing the new user’s ID and username.

    Note

    API v3 supports a sub-account model, rather than the creation of individual accounts for multiple identities in prior versions. A sub-account inherits its parent user’s .accessLevel, .recoveryKey and .verification values. Each User requires use of its own Bearer Authentication token and must log in individually; multiple accounts can all be simultaneously logged in.

    Throws

    400 error if the username is an invalid format or password is not at least 6 characters. 403 error if the user is banned or currently quarantined. 409 errpr if the username is not available.

    Declaration

    Swift

    func addHandler(_ req: Request) async throws -> Response

    Parameters

    requestBody

    Return Value

    AddedUserData containing the newly created user’s ID and username.

    Show on GitHub

  • GET /api/v3/user/whoami

    Returns the current user’s .id, .username and whether they’re currently logged in.

    Declaration

    Swift

    func whoamiHandler(_ req: Request) throws -> CurrentUserData

    Return Value

    CurrentUserData containing the current user’s ID, username and logged in status.

    Show on GitHub
  • passwordHandler(_:) Asynchronous

    POST /api/v3/user/password

    Updates a user’s password to the supplied value, encrypted.

    Throws

    400 error if the supplied password is not at least 6 characters. 403 error if the user is a .client.

    Declaration

    Swift

    func passwordHandler(_ req: Request) async throws -> HTTPStatus

    Parameters

    requestBody

    UserPasswordData struct containing the user’s desired password.

    Return Value

    201 Created on success.

    Show on GitHub
  • usernameHandler(_:) Asynchronous

    POST /api/v3/user/username POST /api/v3/user/:userID/username – moderator use

    Changes a user’s username to the supplied value, if possible. /api/v3/user/username allows a user to change their own username, while /api/v3/user/:userID/username allows moderators to change the username of the indicated user.

    Throws

    400 error if the username is an invalid format. 403 error if you change username more than once per 20 hours (to prevent abuse). Or if the user is a .client. 409 error if the username is not available.

    Declaration

    Swift

    func usernameHandler(_ req: Request) async throws -> HTTPStatus

    Parameters

    requestBody

    UserUsernameData containing the user’s desired new username.

    Return Value

    201 Created on success.

    Show on GitHub

Profile

  • imageHandler(_:) Asynchronous

    POST /api/v3/user/image

    Sets the user’s profile image to the ImageUploadData uploaded in the HTTP body.

    • If the ImageUploadData contains image data in the image member, that data is processed, saved, and set to user’s new image
    • If the ImageUploadData contains a filename in the filename member, the user’s avatar is set to that image file on the server. We don’t check whether the file exists.

    • If both members are nil, the user’s avatar image is set to nil, which will cause the default image be returned.

    Throws

    A 5xx response should be reported as a likely bug, please and thank you.

    Declaration

    Swift

    func imageHandler(_ req: Request) async throws -> UserHeader

    Parameters

    requestBody

    ImageUploadData payload in the HTTP body.

    Return Value

    UserHeader containing the generated image identifier string.

    Show on GitHub
  • imageRemoveHandler(_:) Asynchronous

    POST /api/v3/user/image/remove DELETE /api/v3/user/image DELETE /api/v3/user/:userID/image

    Removes the user’s profile image from their User object. This generally reverts their user avatar image to a default or auto-generated image.

    The third form, that takes a userID in the URL path, is for moderators only.

    Throws

    A 5xx response should be reported as a likely bug, please and thank you.

    Declaration

    Swift

    func imageRemoveHandler(_ req: Request) async throws -> HTTPStatus

    Parameters

    userID

    in URL path. Only for the third form of the URL path, which is moderator-only.

    Return Value

    204 No Content on success.

    Show on GitHub
  • profileHandler(_:) Asynchronous

    GET /api/v3/user/profile

    Retrieves the user’s own profile data for editing, as a ProfilePublicData object.

    Note

    The .header.username and .header.displayName properties of the returned object are for display convenience only. A username must be changed using the POST /api/v3/user/username endpoint.

    Throws

    403 error if the user is banned. A 5xx response should be reported as a likely bug, please and thank you.

    Declaration

    Swift

    func profileHandler(_ req: Request) async throws -> ProfilePublicData

    Return Value

    ProfilePublicData containing the editable properties of the profile.

    Show on GitHub

  • POST /api/v3/user/profile POST /api/v3/user/:userID/profile - for moderator use

    Updates the user’s profile.

    Note

    All fields of the UserProfileUploadData structure being submitted must be present. While the properties of the profile itself are optional, the submitted values all replace the existing propety values. Submitting a value of "" resets its respective profile property to nil.

    Throws

    403 error if the user is banned.

    Declaration

    Swift

    func profileUpdateHandler(_ req: Request) async throws -> ProfilePublicData

    Parameters

    userID

    in URL path. Only for the second form of the URL path, which is moderator-only.
    requestBody

    Return Value

    ProfilePublicData containing the updated editable properties of the profile.

    Show on GitHub

Alertwords

  • POST /api/v3/user/alertwords/add/:alertword_string

    Adds a string to the user’s “Alert Keywords” barrel. The string is lowercased and stripped of punctuation before being added.

    Throws

    A 5xx response should be reported as a likely bug, please and thank you.

    Declaration

    Swift

    func alertwordsAddHandler(_ req: Request) async throws -> KeywordData

    Parameters

    STRING

    In URL path. The alert word to watch for.

    Return Value

    AlertKeywordData containing the updated contents of the barrel.

    Show on GitHub
  • alertwordsHandler(_:) Asynchronous

    GET /api/v3/user/alertwords

    Returns a list of the user’s current alert keywords in AlertKeywordData barrel format.

    Throws

    A 5xx response should be reported as a likely bug, please and thank you.

    Declaration

    Swift

    func alertwordsHandler(_ req: Request) async throws -> KeywordData

    Return Value

    AlertKeywordData containing the current alert keywords as an array of strings.

    Show on GitHub

  • POST /api/v3/user/alertwords/remove/STRING

    Removes a string from the user’s “Alert Keywords” barrel.

    Throws

    A 5xx response should be reported as a likely bug, please and thank you.

    Declaration

    Swift

    func alertwordsRemoveHandler(_ req: Request) async throws -> KeywordData

    Parameters

    STRING

    In URL path. The alert word to remove from the alertword list.

    Return Value

    AlertKeywordData containing the updated contents of the barrel.

    Show on GitHub

Mutewords

  • POST /api/v3/user/mutewords/add/STRING

    Adds a string to the user’s “Muted Keywords” barrel.

    Throws

    A 5xx response should be reported as a likely bug, please and thank you.

    Declaration

    Swift

    func mutewordsAddHandler(_ req: Request) async throws -> KeywordData

    Parameters

    STRING

    In URL path. The muteword to add.

    Return Value

    MuteKeywordData containing the updated contents of the barrel.

    Show on GitHub
  • mutewordsHandler(_:) Asynchronous

    GET /api/v3/user/mutewords

    Returns a list of the user’s currently muted keywords in named-list MuteKeywordData format.

    Throws

    A 5xx response should be reported as a likely bug, please and thank you.

    Declaration

    Swift

    func mutewordsHandler(_ req: Request) async throws -> KeywordData

    Return Value

    MuteKeywordData containing the current muting keywords as an array of strings.

    Show on GitHub

  • POST /api/v3/user/mutewords/remove/STRING

    Removes a string from the user’s “Muted Keywords” barrel.

    Throws

    A 5xx response should be reported as a likely bug, please and thank you.

    Declaration

    Swift

    func mutewordsRemoveHandler(_ req: Request) async throws -> KeywordData

    Parameters

    STRING

    In URL path. The muteword to remove.

    Return Value

    MuteKeywordData containing the updated contents of the barrel.

    Show on GitHub
  • notesHandler(_:) Asynchronous

    GET /api/v3/user/notes

    Retrieves all UserNote>s owned by the current user, as an array ofNoteData` objects.

    The NoteData object is intended to be display friendly, including fields for potential sorting, the ID of the profile which can be linked to, and the profile’s user in the familiar .displayedName format. The .noteID is included as well to support editing of notes outside of a profile-viewing context.

    Throws

    A 5xx response should be reported as a likely bug, please and thank you.

    Declaration

    Swift

    func notesHandler(_ req: Request) async throws -> [NoteData]

    Return Value

    An array of NoteData containing all of the user’s notes.

    Show on GitHub

Helper Functions

  • Generates a recovery key of 3 words randomly chosen from words array.

    Throws

    500 error if the randomizer fails.

    Declaration

    Swift

    static func generateRecoveryKey(on req: Request) throws -> String

    Parameters

    req

    The incoming Request, provided automatically.

    Return Value

    A recoveryKey string.

    Show on GitHub