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
  • 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
  • TIFF
  • 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.

Below is a suggested implementation that uses several of the Dropbox operations, in sequence, to complete these tasks.

Use this Dropbox operation... HTTP Verb To complete this step...
POST /api/dropbox/pictures POST Upload the image to the Dropbox.
GET dropbox/pictures/{pictureId} GET Get the image so the cropping feature can display it.
PUT dropbox/pictures/{pictureId} PUT Update the image with only the selected part.
GET dropbox/pictures/{pictureId} GET Get the cropped image so it can be displayed as the avatar for the resource.

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

Back to top

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.

Back to top

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 {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.

Back to top

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 from disk: POST /api/dropbox/pictures. Image is saved to database 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 {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.

Back to top

Related Topics