UsersController

struct UsersController : 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

Finding Other Users

  • GET /api/v3/users/find/:username

    Retrieves a user’s UserHeader using either an ID (UUID string) or a username.

    This endpoint is of limited utility, but is included for the case of obtaining a user’s ID from a username. If you have an ID and want the associated username, use the more efficient /api/v3/users/ID endpoint instead.

    Note

    Because a username can be changed, there is no guarantee that a once-valid username will result in a successful return, even though the User itself does exist.

    Throws

    404 error if no match is found.

    Declaration

    Swift

    func findHandler(_ req: Request) throws -> UserHeader

    Parameters

    STRING

    in URL path. The userID or username to search for.

    Return Value

    UserHeader containing the user’s ID, username, displayName and userImage.

    Show on GitHub

  • GET /api/v3/users/:userID

    Retrieves the specified user’s UserHeader info.

    This endpoint provides one-off retrieval of the user information appropriate for a header on posted content – the user’s ID, current generated .displayedName, and filename of their current profile image.

    For bulk data retrieval, see the ClientController endpoints.

    Throws

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

    Declaration

    Swift

    func headerHandler(_ req: Request) throws -> UserHeader

    Parameters

    userID

    in URL path. The userID to search for.

    Return Value

    UserHeader containing the user’s ID, .displayedName and profile image filename.

    Show on GitHub
  • profileHandler(_:) Asynchronous

    GET /api/v3/users/ID/profile

    Retrieves the specified user’s profile, as a ProfilePublicData object.

    Throws

    404 error if the profile is not available. A 5xx response should be reported as a likely bug, please and thank you.

    Declaration

    Swift

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

    Parameters

    userID

    in URL path. The userID to search for.

    Return Value

    ProfilePublicData containing the displayable properties of the specified user’s profile.

    Show on GitHub

  • GET /api/v3/users/match/allnames/STRING

    Retrieves the first 10 User.userSearch values containing the specified substring, returning an array of UserHeader structs.. The intended use for this endpoint is to help isolate a particular user in an auto-complete type scenario, by searching all of the .displayName, .username and .realName profile fields.

    Compare to /api/v3/user/match/username/STRING, which searches just .username and returns an array of just strings.

    Note

    If the search substring contains “unsafe” characters, they must be url encoded. Unicode characters are supported. A substring comprised only of whitespace is disallowed. A substring of “@” or “(@” is explicitly disallowed to prevent single-step username harvesting.

    For bulk .userSearch data retrieval, see the ClientController endpoints.

    Throws

    403 error if the search term is not permitted.

    Declaration

    Swift

    func matchAllNamesHandler(_ req: Request) async throws -> [UserHeader]

    Parameters

    STRING

    in URL path. The search string to use. Must be at least 2 characters long.

    Return Value

    An array of UserHeader values of all matching users.

    Show on GitHub

  • GET /api/v3/users/match/username/STRING

    Retrieves all usernames containing the specified substring, returning an array of @username strings. The intended use for this endpoint is to help isolate a particular user in an auto-complete type scenario.

    Note

    An @ is prepended to each returned matching username as a convenience, but should never be included in the search itself. No base username can contain an @, thus there would never be a match.

    Declaration

    Swift

    func matchUsernameHandler(_ req: Request) async throws -> [String]

    Parameters

    STRING

    in URL path. The search string to use. Must be at least 2 characters long.

    Return Value

    An array of String containng all matching usernames as “@username” strings.

    Show on GitHub

Actions Taken on Other Users

  • noteCreateHandler(_:) Asynchronous

    POST /api/v3/users/ID/note

    Saves a UserNote associated with the specified user and the current user.

    Throws

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

    Declaration

    Swift

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

    Parameters

    userID

    in URL path. The user to associate with the note.
    requestBody

    NoteCreateData struct containing the text of the note.

    Return Value

    NoteData containing the newly created note.

    Show on GitHub
  • noteDeleteHandler(_:) Asynchronous

    POST /api/v3/users/ID/note/delete DELETE /api/v3/users/ID/note

    Deletes an existing UserNote associated with the specified user’s profile and the current user.

    Throws

    400 error if there is no existing note on the profile. A 5xx response should be reported as a likely bug, please and thank you.

    Declaration

    Swift

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

    Parameters

    userID

    in URL path. Specifies the target of the note to be deleted.

    Return Value

    204 No Content on success.

    Show on GitHub
  • noteHandler(_:) Asynchronous

    GET /api/v3/users/ID/note

    Retrieves an existing UserNote associated with the specified user’s profile and the current user.

    Note

    In order to support the editing of a note in contexts other than when actively viewing a profile, the contents of profile.note cannot be used to determine if there is an exiting associated UserNote, since it is possible for a valid note to contain no text at any given time. Use this GET endpoint prior to attempting a POST to it.

    Throws

    400 error if there is no existing note on the profile. A 5xx response should be reported as a likely bug, please and thank you.

    Declaration

    Swift

    func noteHandler(_ req: Request) async throws -> NoteData

    Parameters

    userID

    in URL path. The user the note is attached to.

    Return Value

    NoteEditData containing the note’s ID and text.

    Show on GitHub
  • reportHandler(_:) Asynchronous

    POST /api/v3/users/ID/report

    Creates a Report regarding the specified user’s profile, either the text fields or the avatar image.

    Note

    The accompanying report message is optional on the part of the submitting user, but the ReportData is mandatory in order to allow one. If there is no message, send an empty string in the .message field.

    Declaration

    Swift

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

    Parameters

    requestBody

    ReportData containing an optional accompanying message

    Return Value

    201 Created on success.

    Show on GitHub

Blocks and Mutes

  • blocksHandler(_:) Asynchronous

    GET /api/v3/users/blocks

    Returns a list of the user’s currently blocked users as an array of UserHeader objects. If the user is a sub-account, the parent user’s blocks are returned.

    Throws

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

    Declaration

    Swift

    func blocksHandler(_ req: Request) async throws -> [UserHeader]

    Return Value

    Array of UserHeader containing the currently blocked users.

    Show on GitHub
  • blockHandler(_:) Asynchronous

    POST /api/v3/users/:userID/block

    Blocks the specified User. The blocking user and any sub-accounts will not be able to see posts from the blocked User or any of their associated sub-accounts, and vice versa. This affects all forms of communication, public and private, as well as user searches.

    Only the specified user is added to the block list, so as not to explicitly expose the ownership of any other accounts the blocked user may be using. The blocking of any associated user accounts is handled under the hood.

    Users with an .accessLevel of .moderator or higher may not be blocked. Attempting to block a moderator account directly will produce an error. A block applied to an alt account of a moderator will be accepted, but will not include the moderator in the set of blocked accounts. Similarly, moderators can block accounts, which has no effect on their moderator account but applies bidirectional blocks between their (non-moderator) alt accounts and the blocked accounts.

    Throws

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

    Declaration

    Swift

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

    Parameters

    userID

    in URL path. The userID to block.

    Return Value

    201 Created on success, 200 OK if user already in block list.

    Show on GitHub
  • unblockHandler(_:) Asynchronous

    POST /api/v3/users/ID/unblock

    Removes a block of the specified User and all sub-accounts by the current user and all associated accounts.

    Throws

    400 error if the specified user was not currently blocked. A 5xx response should be reported as a likely bug, please and thank you.

    Declaration

    Swift

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

    Parameters

    userID

    in URL path. The user to unblock.

    Return Value

    204 No Content on success.

    Show on GitHub
  • mutesHandler(_:) Asynchronous

    GET /api/v3/users/mutes

    Returns a list of the user’s currently muted users.

    Throws

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

    Declaration

    Swift

    func mutesHandler(_ req: Request) async throws -> [UserHeader]

    Return Value

    Array of UserHeader containing the currently muted users.

    Show on GitHub
  • muteHandler(_:) Asynchronous

    POST /api/v3/users/ID/mute

    Mutes the specified User for the current user. The muting user will not see public posts from the muted user. A mute does not affect what is or is not visible to the muted user. A mute does not affect private communication channels.

    A mute does not mute any associated sub-accounts of the muted User, nor is it applied to any of the muting user’s associated accounts. It is very much just this currently logged-in username muting that one username.

    Any user can be muted, including users with privileged .accessLevel. Such users are not muted, however, when posting from role accounts. That is, a .moderator can post as @moderator and it is visible to all users, period.

    Throws

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

    Declaration

    Swift

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

    Parameters

    userID

    in URL path. The userID to mute.

    Return Value

    201 Created on success.

    Show on GitHub
  • unmuteHandler(_:) Asynchronous

    POST /api/v3/users/ID/unmute

    Removes a mute of the specified User by the current user.

    Throws

    400 error if the specified user was not currently muted. A 5xx response should be reported as a likely bug, please and thank you.

    Declaration

    Swift

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

    Parameters

    userID

    in URL path. The user to unmute.

    Return Value

    204 No Content on success.

    Show on GitHub
  • favoritesHandler(_:) Asynchronous

    GET /api/v3/users/favorites

    Returns a list of the user’s currently favorited users.

    Throws

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

    Declaration

    Swift

    func favoritesHandler(_ req: Request) async throws -> [UserHeader]

    Return Value

    An array of UserHeader containing the currently favorited users.

    Show on GitHub
  • favoriteAddHandler(_:) Asynchronous

    POST /api/v3/users/:user_ID/favorite

    Favorites the specified User for the current user. Favoriting is a way to short-list friends for easy retrieval when using various Twitarr features.

    Throws

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

    Declaration

    Swift

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

    Parameters

    userID

    in URL path. The userID to favorite.

    Return Value

    201 Created on success.

    Show on GitHub

  • POST /api/v3/users/:user_ID/unfavorite

    Removes a favorite of the specified User by the current user.

    Throws

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

    Declaration

    Swift

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

    Parameters

    userID

    in URL path. The user to unfavorite.

    Return Value

    204 No Content on success.

    Show on GitHub

User Role Management

  • getUsersWithRole(_:) Asynchronous

    GET /api/v3/forum/userrole/:user_role

    Returns a list of all users that have the given role. Currently, caller must have the shutternautmanager role to call this, and can only query the shutternaut role.

    Throws

    badRequest if the caller isn’t a shutternaut manager, or the user role param isn’t shutternaut.

    Declaration

    Swift

    func getUsersWithRole(_ req: Request) async throws -> [UserHeader]

    Return Value

    Array of UserHeader. Array may be empty if nobody has this role yet.

    Show on GitHub
  • addRoleForUser(_:) Asynchronous

    POST /api/v3/forum/userrole/:user_role/addrole/:user_id

    Adds the given role to the given user’s role list. Currently, caller must have the shutternautmanager role to call this, and can only give a user the shutternaut role.

    Throws

    badRequest if the target user already has the role, or if the caller role/role being set are invalid.

    Declaration

    Swift

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

    Return Value

    200 OK if the user now has the given role.

    Show on GitHub
  • removeRoleForUser(_:) Asynchronous

    POST /api/v3/admin/userrole/:user_role/removerole/:user_id

    Removes the given role from the target user’s role list. Currently, caller must have the shutternautmanager role to call this, and can only remove the shutternaut role from a user’s role list.

    Throws

    badRequest if the target user isn’t a Shutternaut Manager, the role being set isn’t Shutternaut. Does not error if the target user already doesn’t have the role.

    Declaration

    Swift

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

    Return Value

    200 OK if the user was demoted successfully.

    Show on GitHub

Helper Functions

  • Updates the cache values for all accounts involved in a block removal. The currently blocked user and any associated accounts are removed from all blocking user’s associated accounts’ blocks caches, and vice versa.

    Throws

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

    Declaration

    Swift

    func removeBlockFromCache(by requester: User, of blockedUser: User, on req: Request) async throws

    Parameters

    requester

    The User removing the block.
    user

    The User currently being blocked.
    req

    The incoming Request, which provides the EventLoop on which this must run.

    Return Value

    Void.

    Show on GitHub

  • Updates the cache values for all accounts involved in a block. Blocked user and any associated accounts are added to all blocking user’s associated accounts’ blocks caches, and vice versa.

    Throws

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

    Declaration

    Swift

    func addBlockToCache(requestedBy requester: User, blocking blockedUserID: UUID, on req: Request) async throws

    Parameters

    requester

    The User requesting the block.
    user

    The User being blocked.
    req

    The incoming Request, which provides the EventLoop on which this must run.

    Return Value

    Void.

    Show on GitHub