ImageController

struct ImageController : APIRouteCollection
Show on GitHub

  • Required. Registers routes to the incoming router.

    Declaration

    Swift

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

  • GET /api/v3/image/full/STRING

    Returns a user-created image previously uploaded to the server. This includes images in Twitarr posts, ForumPosts, FezPosts, User Avatars, and Daily Theme images. Even though the path for this API call says ‘full’, images may be downsized when uploaded (currently, images get downsized to a max edge length of 2048).

    Image filenames should have a form of: UUIDString.typeExtension where the UUIDString matches the output of UUID().string and typeExtension matches one of : “bmp”, “gif”, “jpg”, “png”, “tiff”, “wbmp”, “webp”. Example: F818D809-AAB9-4C92-8AAD-6AE483C8AB82.jpg The thumb and full versions of this call return differently-sized versions of the same image when called with the same filename.

    User Avatar Images: UserHeader.image will be nil for a user that has not set an avatar image; clients should display a default avatar image instead. Or, clients may call the /api/v3/image/user/ endpoints instead–these endpoints return identicon images for users that have not set custom images for themselves.

    Throws

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

    Declaration

    Swift

    func getImage_FullHandler(_ req: Request) throws -> Response

    Parameters

    STRING

    A reference to the image, returned from another API call.

    Return Value

    Image data

    Show on GitHub

  • GET /api/v3/image/thumb/STRING

    Returns a user-created image thumbnail previously uploaded to the server. This includes images in Twitarr posts, ForumPosts, FezPosts, User Avatars, and Daily Theme images. The exact size of the thumbnail may vary based on the usage given at upload time.

    Image filenames should have a form of: UUIDString.typeExtension where the UUIDString matches the output of UUID().string and typeExtension matches one of : “bmp”, “gif”, “jpg”, “png”, “tiff”, “wbmp”, “webp”. Example: F818D809-AAB9-4C92-8AAD-6AE483C8AB82.jpg. The thumb and full versions of this call return differently-sized versions of the same image when called with the same filename.

    User Avatar Images: UserHeader.image will be nil for a user that has not set an avatar image; clients should display a default avatar image instead. Or, clients may call the /api/v3/image/user/ endpoints instead–these endpoints return identicon images for users that have not set custom images for themselves.

    Throws

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

    Declaration

    Swift

    func getImage_ThumbnailHandler(_ req: Request) throws -> Response

    Parameters

    STRING

    A reference to the image, returned from another API call.

    Return Value

    Image data

    Show on GitHub

  • GET /api/v3/image/archive/STRING

    Returns an archived user-created image previously uploaded to the server, and then previously deleted/replaced. This includes images in Twitarr posts, ForumPosts, FezPosts, User Avatars, and Daily Theme images. Archived images are only accessible by Moderators and above.

    Image filenames should have a form of: UUIDString.typeExtension where the UUIDString matches the output of UUID().string and typeExtension matches one of : “bmp”, “gif”, “jpg”, “png”, “tiff”, “wbmp”, “webp”. Example: F818D809-AAB9-4C92-8AAD-6AE483C8AB82.jpg. The thumb and full versions of this call return differently-sized versions of the same image when called with the same filename.

    Throws

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

    Declaration

    Swift

    func getImage_ArchivedHandler(_ req: Request) throws -> Response

    Parameters

    STRING

    A reference to the image, returned from another API call.

    Return Value

    Image data

    Show on GitHub

  • GET /api/v3/image/user/full/:userID GET /api/v3/image/user/thumb/:userID

    Gets the avatar image for the given user. If the user has a custom avatar, result is the same as if you called /api/v3/image/<thumb|full>/<user.userImage> If the user has no custom avatar, returns a 40x40 Identicon image specific to the given userID.

    Note: This method is a convenience for clients that do their own image caching. For clients that rely on Cache-Control headers, it’s better to call either the custom image or user identicon call instead; those calls can set a long-term cache expiry and this method cannot. Said differently, /api/v3/image/thumb/:filename only changes its result if the file is mod-deleted, and if that happens the user’s userImage field updates. Similarly, api/v3/image/user/identicon/:userID will always return the same result for the same userID parameter. This method returns a different image for the same URL whenever the user updates their profile image, therefore we can’t set cache headers as aggressively.

    Barring severe errors, this method will always return an image–either a user’s custom avatar or their default identicon. A consequence of this is that you cannot tell whether a user has a custom avatar set or not when calling this method.

    This method is optional. If you don’t want the server-generated identicons for your client, you can create your own and know when to use them instead of user-created avatars, as the user’s userImage will be nil if they have no custom avatar.

    Throws

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

    Declaration

    Swift

    func getUserAvatarHandler(_ req: Request) throws -> Response

    Parameters

    ID

    A userID value, in the URL path.

    Return Value

    Image data, or 304 notModified if client’s ETag matches.

    Show on GitHub

  • GET /api/v3/image/user/identicon/ID

    Returns a user’s identicon avatar image, even if that user has a custom avatar set. Meant for use in User Profile edit flows, to show a user what their default identicon will look like even when a custom avatar is set.

    Please don’t use this method to show identicons for all users everywhere. Users like their custom avatars.

    Throws

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

    Declaration

    Swift

    func getUserIdenticonHandler(_ req: Request) throws -> Response

    Parameters

    ID

    A userID value, in the URL path.

    Return Value

    Image data, or 304 notModified if client’s ETag matches.

    Show on GitHub

Utilities

  • Declaration

    Swift

    func getUserUploadedImage(_ req: Request, sizeGroup: ImageSizeGroup, imageFilename: String? = nil) throws -> Response
    Show on GitHub

  • Creates an identicon image from the given user’s userID.

    Created images are 40x40 PNG palette-based images, averaging ~200 bytes in size. Random inputs into the generator come from the Xoshiro random number generator, seeded with a (very poor) hash of the user’s userID value. Because of this seeding, the algorithm repeatedly produces the same image for the same userID value.

    From testing, this method can generate about 10000 icons / second on a single thread. This should be fast enough so that we don’t need to store and retrieve generated images; we may as well just generate them on-demand.

    Declaration

    Swift

    func generateIdenticon(for userID: UUID) throws -> Data
    Show on GitHub