Appwrites Avatars Service

So what is Avatars Service?
Appwrite is a self-hosted solution that provides developers with a set of easy-to-use and integrate REST APIs to manage their core backend needs. One such API service provided by Appwrites is the Avatar service. The avatar service helps you to complete standard tasks related to images, icons and avatars.

Okay, that sounds like something I need to use very often, could you please explain the use cases further?
Using the avatar service you can fetch country flags, browser icons, generate QR codes, get images from URL, get payment method logos, get favicon of any remote URL and so on...

Not only this, but this service also allows you to resize, crop and change the output image quality to get the best performance and visibility required in your project

Hmm, Sounds cool! But can you please explain me how to use it in my project?
Yeah sure I could explain it using some examples, do you want to learn using it for client based applications or using server side integrations?

Well, TEACH ME BOTH!

Okay so I’ll explain you a few examples in each scenario
Let’s start learning using it to build client based applications and websites. The first step is to setup appwrite web sdk, you can do it by following https://github.com/appwrite/sdk-for-web
I hope that you have read the page above. Anyways, I’ll start by initialising the sdk object using Appwrite server API endpoint and project id which can be found in your project settings page.

const sdk = new Appwrite();

sdk
    .setEndpoint('http://localhost/v1') // Your Appwrite Endpoint
    .setProject('455x34dfkj') // Your project ID;

Once we are done with this. We’ll begin with our first task. The task is to get the Credit Card icon for major banking providers.

Request Type:

GET	/v1/avatars/credit-cards/{code}

The credit card endpoint returns us the icon of the credit card provider.
An example request can be

let result  = sdk.avatars.getCreditCard(‘visa’);

result will contain a resource url of a png image.

We can also use width, height and quality arguments
The required argument code is be a string with possible values: amex, argencard, cabal, censosud, diners, discover, elo, hipercard, jcb, mastercard, naranja, targeta-shopping, union-china-pay, visa, mir, maestro

Whereas width, height and quality are optional integer arguments. The arguments width and height can contain an integer between 0 to 2000, default being 100. However, the argument quality can contain an integer between 0 to 100, default being 100.

Let’s Try another task

This time we’ll get a country flag instead.

Request Type:

GET	/v1/avatars/flags/{code}

This endpoint can be used to get different country flags. The argument receives a 2 letter country code. Just like in the previous example width, height and quality arguments can be used in this case aswell.
The required argument code is a string which denotes the country code in ISO Alpha-2 country code format

An example request can be

let result = sdk.avatars.getFlag(‘af’);

result contains resource URL containing image of flag in png format.

This last task we’ll be doing for the client integrated api requests will be to get QR code

Request Type:

GET	/v1/avatars/qr

This request converts plain text to a QR code image.
An example request can be

let result = sdk.avatars.getQR(‘[TEXT]’)

result contains resource URL containing image of qr code in png
There are a variety of optional query parameters to change the size and style of resulting image.

These are size, margin and download. size and margin are integer type arguments accepting integers in range 0 to 1000 and 0 to 10 respectively. The default value of size parameter is 400 whereas for margin is it 1.

The parameter download accepts a Boolean type value, which returns image with Content-Disposition: attachment headers for the browser to start downloading it. ‘0’ should be passed for no header and ‘1’ otherwise. Default value is set to ‘0’

PHEW! That was a lot, please tell me about Server integrated requests

Sure, I’ll teach through a few examples how to send requests using Server Integrated with Python SDK. To learn how to using Appwrite python SDK check this out https://github.com/appwrite/sdk-for-python

I hope that you have read it already. Let’s start by initialising our sdk

from appwrite.client import Client
from appwrite.services.users import Users

client = Client()

(client
  .set_endpoint('https://[HOSTNAME_OR_IP]/v1') # Your API Endpoint
  .set_project('5df5acd0d48c2') # Your project ID
  .set_key('919c2d18fb5d4...a2ae413da83346ad2') # Your secret API key
  .set_self_signed() # Use only on dev mode with a self-signed SSL cert
)

Initialize your SDK with Appwrite server API endpoint and project ID which can be found in the project settings page and the API secret key from project’s API keys section.
Make sure your API key is granted with access to the avatars.read permission scope
Once this is set, we’ll begin with our next task which is to get image from URL

Request Type:

GET	/v1/avatars/image

This endpoint can be used to fetch a remote image URL and crop it to the needed image size. This endpoint is especially useful in cases when you need to crop and display remote image in your app.

An example request can be:

avatars = Avatars(client)
result = avatars.get_image(‘https://example.com’)

result contains the image resource url

The required argument is url, which contains a string i.e. the Image URL which needs to be cropped

The other optional arguments which could be used are width and height, both integer type arguments which can be used to resize preview image width. They should contain integer between 0 to 2000

The other methods available are:

Get Favicon: /v1/avatars/favicon ExampleCode:

avatars = Avatars(client)

result = avatars.get_favicon('https://example.com')

Get User Initials /v1/avatars/initials Example Code:

avatars = Avatars(client)

result = avatars.get_initials()

This contains name,width, height,color,background arguments which are all optional

These were some examples which would help you understand how to use the appwrite avatars service using both client side and service side integrations. To know more you may read the documentation at https://appwrite.io/docs/client/avatars. Hope this would help you in understanding avatars service better