━━━━━━ ❖ ━━━━━━

---

❖ Information

AvatarAPI, is a free API serving quotes from Avatar: The Last Airbender. The quotes are sourced from AvatarQuotes and the endpoints are available at https://avatarquotes.xyz/api/{endpoint} (See Usage for the different endpoints)

---

❖ Usage

AvatarAPI has a few different endpoints for different needs but the usage is relatively the same for all of them. The examples use httpie but anything that can make GET requests can be used as well

❖ Fetch 5 random quotes

Endpoint: /api/quotes

$ http GET https://avatarquotes.xyz/api/quotes

{
    "num": 5,
    "quotes": [
        {
            "quote": "...",
            "character": "...",
            "nation": "...",
            "bending": "...",
            "episode": "...",
            "book": "...",
        },
        "...4 more"
    ]
}

❖ Fetch 5 random quotes from any given column

Endpoints:

• /api/quotes/character
• /api/quotes/nation
• /api/quotes/bending
• /api/quotes/episode
• /api/quotes/book

$ http GET https://avatarquotes.xyz/api/quotes/character value==Aang

{
    "num": 5,
    "quotes": [
        {
            "quote": "...",
            "character": "Aang",
            "nation": "...",
            "bending": "...",
            "episode": "...",
            "book": "...",
        },
        "...4 more"
    ]
}

All of the endpoints above require the value parameter, which is case sensitive

There is also an optional num parameter that can be used to specify how many quotes you'd like. Quotes can be in the range [1, 255]

❖ Fetch all valid values for any given column

Endpoints:

• /api/all/character
• /api/all/nation
• /api/all/bending
• /api/all/episode
• /api/all/book

$ http GET https://avatarquotes.xyz/api/all/bending

{
    "num": 6,
    "values": [
        "Water",
        "None",
        "Fire",
        "All",
        "Air",
        "Earth"
    ]
}

These endpoints can be helpful if you're trying to use the quotes endpoints but can't get the value right

❖ The response.num field

The response from all of the endpoints includes the response.num field, which simply specifies the number of quotes returned. A natural question to ask is "Well why is that needed, shouldn't it just be 5 in the default case, or equal to num in case the num parameter was passed in?"

The answer is "well yes but no".

For example, some characters like Koh only have 2 quotes. So even without the num parameter, we run into some issues. This is why the API just returns as many quotes it can and updates the response.num field in the case that num is too large for the given request.

The response.num field exists as a sanity check. Users can confirm that they got the number of quotes they requested, or implement special logic in case it's different.

---

❖ Rate Limiting

AvatarAPI currently allows 5 requests per minute from a given IP address. In case you desire more, feel free to take a look at the Self Hosting section.

---

❖ Self Hosting

AvatarAPI is relatively easy to self-host. The only requirements are Docker, Git and pretty much any webserver, for example: nginx

❖ Clone repo with submodules and cd into it

$ git clone --recurse-submodules https://github.com/dotzenith/AvatarAPI.rs.git
$ cd AvatarAPI

❖ Build docker image

$ docker build -t avatarapi:latest .

❖ Run the container

$ docker run -p 3000:3000 -d --name avatarapi avatarapi:latest

❖ Set up a reverse proxy

After the step above, set up a reverse proxy using a webserver of your choice and enjoy your very own AvatarAPI :)

---

❖ What's New?

0.2.0 - Added additional checks for num param to ensure it's not 0

---