UsersController Structure Reference

registerRoutes(_:)
Required. Registers routes to the incoming router.
Declaration
Swift

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

Finding Other Users


                    
                    
                    findHandler(_:)

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


                    
                    
                    headerHandler(_:)

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


                    
                    
                    matchAllNamesHandler(_:)

Asynchronous

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.

URL Query Parameters:

?favorers=BOOLEAN Show only resulting users that have favorited the requesting user.

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


                    
                    
                    matchUsernameHandler(_:)

Asynchronous

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

Favorites

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


                    
                    
                    favoriteRemoveHandler(_:)

Asynchronous

POST /api/v3/users/:user_ID/unfavorite DELETE /api/v3/users/:user_id/favorite

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


                    
                    
                    removeBlockFromCache(by:of:on:)

Asynchronous

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


                    
                    
                    addBlockToCache(requestedBy:blocking:on:)

Asynchronous

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