Managing Avatars on the Platform

This topic includes information about managing avatars on the platform, including:

Resources that Have Avatars on the Platform

The platform supports upload of an image for use as an avatar for the following resource types:

  • APIs
  • Apps
  • Groups
  • Business Organizations
  • Users

Supported File Types and File Size

Supported image files must be no more than 4MB in size, and must be one of these supported image types:

  • JPG
  • GIF
  • BMP
  • PNG

Working With Resource Images

The Dropbox service provides operations for uploading images to the platform. Working with images might include such activities as uploading an image, cropping it, and saving the cropped portion as the avatar for a resource.

The table below shows the sequence of operations to upload a user avatar.

Use this Dropbox operation... HTTP Verb To complete this step...
POST /api/dropbox/pictures POST Upload the image to the Dropbox.
PUT api/dropbox/pictures/{PictureID} PUT Specifies the display and crop dimensions.
PUT /api/users/{UserID} (for a user; corresponding operation for other assets) PUT Updates the profile with the new image information.

The services that support managing these various resources include operations that allow you to add, update, or delete avatars or get avatar information:

Notes:

  • When uploading an image to Dropbox, the image size will be 512 * 512 by default before saving the image.

  • The Crop Picture API crops the image based on the value of 512 in Dropbox.

  • The Crop Picture API is optional. But in versions prior to 2022.1.2, you need to call this API regardless. The recommended dimensions to call the Crop Picture API without an actual cropping is 512.

Managing Caching for Avatars

Because many different resources, such as APIs, apps, and users, can have a different avatar, it's possible that a platform resource, such as an API's Board page with many comments and notifications, might include many different images. For maximum efficiency, avatars can be cached.

Whenever the avatar for a resource is changed, the URL is updated. An updated image will always have a different URL. This means that you can cache avatars indefinitely without risk that you might be referencing an outdated avatar.

Usage Note: Difference Between getAvatar and getDefaultAvatar

There are two operations available for retrieving the avatar associated with a resource, with one key difference between them:

  • GET /api/{service}/{ID}/avatar (getDefaultAvatar): This operation simply returns the avatar for the resource, such as app, API, or user.
  • GET api/{service}/{ID}/avatars/{AvatarVersionID}.png (getAvatar): Each time a new avatar is set up for a resource, the platform assigns an AvatarVersionID. If the avatar is changed, the new avatar has a new AvatarVersionID. By specifying the AvatarVersionID, you can retrieve the avatar for a resource even if it isn't the current avatar.

Process Flow: Example

Let's say a user, Jane Mead, adds an avatar to her user profile. She then decides to change the image; she removes the existing avatar and adds a different one. This process flow uses the following operations:

  1. User uploads an image to the Community Manager developer portal: POST /api/dropbox/pictures. Image is saved to the Dropbox and PictureID is returned.
  2. Image is retrieved for user to crop: GET /api/dropbox/pictures/{PictureID}.
  3. User crops picture: PUT /api/dropbox/pictures/{PictureID}. Cropped image is saved to database and PictureID is returned (same PictureID).
  4. Cropped image is retrieved for use: GET /api/users/UserID/avatar.
  5. User record is updated: PUT /api/users/{UserID}.
  6. Updated user record is retrieved: GET /api/users/{UserID}.
  7. User deletes avatar: DELETE api/{service}/{ID}/picture.
  8. User record is updated: PUT /api/users/{UserID}.
  9. Updated user record is retrieved: GET /api/users/{UserID}.
  10. User uploads a second image from disk: steps 1-6 above are repeated.

File upload example using Postman

For an example of uploading an avatar using the Postman client application, see Managing Multipart/Form-Data Uploads: Dropbox Service: Add Picture.