dotzenith / AvatarAPI

A free API serving quotes from Avatar: The Last Airbender

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

This is no longer maintained

I fell for the "rewrite it in rust" meme, see: AvatarAPI.rs

❖ Information

AvatarAPI, simply put, 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

❖ /api/quotes

Fetches 10 random quotes

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

{
    "num": 10,
    "quotes": [
        {
            "Quote": "...",
            "Character": "...",
            "Nation": "...",
            "Bending": "...",
            "Episode": "...",
            "Book": "...",
        },
        "...9 more"
    ]
}

❖ /api/quotes/character

Fetches 10 random quotes from a given character

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

{
    "num": 10,
    "quotes": [
        {
            "Quote": "...",
            "Character": "Aang",
            "Nation": "...",
            "Bending": "...",
            "Episode": "...",
            "Book": "...",
        },
        "...9 more"
    ]
}

Allowed values for character name

"Katara", "Sokka", "Zuko", "Merchant woman", "Aang",
"Fisherman's wife", "Fisherman", "Jee", "Iroh", "Tashi", "Pasang",
"Gyatso", "Ozai", "Yue", "Pakku", "Oh", "Pirate captain",
"Cabbage merchant", "Gan Jin tribesman", "Zhang leader",
"Gan Jin leader", "Canyon guide", "Hakoda", "Bato", "Chey",
"Jeong Jeong", "Bumi", "Jet", "Kanna", "Southern Water Tribe girl",
"Mechanist", "Haru", "Guard", "Tyro", "Captain", "Warden", "Suki",
"Meng", "Wu", "Zhao", "Kay-fon", "Senlin Village leader",
"Earthbender captain", "Great Fire Sage", "Shyu", "Roku", "Arnook",
"Hahn", "Koh", "Chong", "Lily", "Song", "Tho", "Huu", "Due",
"Tong", "Kyoshi", "Zei", "Toph", "Wan Shi Tong", "Ticket lady",
"Ying", "Smellerbee", "jet", "Azula", "Fong", "Kuei",
"Guru Pathik", "Ty Lee", "Mai", "Kenji", "Macmu-Ling", "Joo Dee",
"Long Feng", "General Sung", "Pong", "Yu", "The Boulder", "Yung",
"Iio", "Lee", "Gansu", "Ursa", "Kwan", "Piandao", "Kuruk",
"Yangchen", "Lion Turtle", "Hama", "Momo", "Appa"

❖ /api/quotes/nation

Fetches 10 random quotes by characters from a given nation

$ http GET https://avatarquotes.xyz/api/quotes/nation name==Fire

{
    "num": 10,
    "quotes": [
        {
            "Quote": "...",
            "Character": "...",
            "Nation": "Fire",
            "Bending": "...",
            "Episode": "...",
            "Book": "...",
        },
        "...9 more"
    ]
}

Allowed values for nation name

"Water", "Earth", "Fire", "Air", "None"

Some characters like Guru Pathik, don't belong to a specific nation, thus the addition of "None"

❖ /api/quotes/bending

Fetches 10 random quotes by characters with a given bending style

$ http GET https://avatarquotes.xyz/api/quotes/bending bending==Earth

{
    "num": 10,
    "quotes": [
        {
            "Quote": "...",
            "Character": "...",
            "Nation": "...",
            "Bending": "Earth",
            "Episode": "...",
            "Book": "...",
        },
        "...9 more"
    ]
}

Allowed values for bending type

"Water", "Earth", "Fire", "Air", "None", "All"

Characters like Sokka have bending type "None", while characters like Aang have bending type "All"

❖ /api/quotes/episode

Fetches 10 random quotes from a given episode

$ http GET https://avatarquotes.xyz/api/quotes/episode title==Imprisoned

{
    "num": 10,
    "quotes": [
        {
            "Quote": "...",
            "Character": "...",
            "Nation": "...",
            "Bending": "...",
            "Episode": "Imprisoned",
            "Book": "...",
        },
        "...9 more"
    ]
}

Allowed values for episode title

"The Storm", "The Waterbending Master", "The Waterbending Scroll",
"The Great Divide", "Bato of the Water Tribe", "The Deserter",
"The King of Omashu", "Jet", "The Avatar Returns",
"The Northern Air Temple", "The Boy in the Iceberg", "Imprisoned",
"The Warriors of Kyoshi", "The Fortuneteller",
"The Southern Air Temple",
"Winter Solstice Part 1: The Spirit World",
"Winter Solstice Part 2: Avatar Roku",
"The Siege of the North, Part 1", "The Siege of the North, Part 2",
"The Blue Spirit", "The Cave of Two Lovers", "The Swamp",
"Avatar Day", "The Library", "The Serpent's Pass",
"The Avatar State", "The Guru", "The Tales of Ba Sing Se",
"Lake Laogai", "Bitter Work", "The Earth King", "The Drill",
"City of Walls and Secrets", "The Blind Bandit", "The Chase",
"The Crossroads of Destiny", "Return to Omashu",
"Appa's Lost Days", "The Desert", "Zuko Alone",
"The Firebending Masters", "The Awakening", "The Headband",
"The Western Air Temple", "The Runaway",
"The Day of Black Sun, Part 1: The Invasion", "The Beach",
"The Boiling Rock, Part 2",
"Sozin's Comet, Part 2: The Old Masters", "The Painted Lady",
"Sozin's Comet, Part 4: Avatar Aang",
"Sozin's Comet, Part 1: The Phoenix King", "The Puppetmaster",
"The Boiling Rock, Part 1", "Nightmares and Daydreams",
"The Avatar and The Fire Lord",
"The Day of Black Sun, Part 2: The Eclipse",
"Sozin's Comet, Part 3: Into the Inferno", "Sokka's Master",
"The Southern Raiders", "The Ember Island Players"

❖ /api/quotes/book

Fetches 10 random quotes from a given book

$ http GET https://avatarquotes.xyz/api/quotes/book title==Water

{
    "num": 10,
    "quotes": [
        {
            "Quote": "...",
            "Character": "...",
            "Nation": "...",
            "Bending": "...",
            "Episode": "...",
            "Book": "Water",
        },
        "...9 more"
    ]
}

Allowed values for book title

"Water", "Earth", "Fire"

❖ Using the num url parameter

All of the endpoints above support an optional url parameter of num to specify the number of quotes to return

$ http GET https://avatarquotes.xyz/api/quotes num==5

{
    "num": 5,
    "quotes": [
        {
            "Quote": "...",
            "Character": "...",
            "Nation": "...",
            "Bending": "...",
            "Episode": "...",
            "Book": "...",
        },
        "...4 more"
    ]
}

num can take on the values 1 <= num <= 25

❖ 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 10 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 endpoint.

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 100 requests per hour 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.git
$ cd AvatarAPI

❖ Build docker image

$ docker build -t avatarapi:latest .

❖ Run the container

$ docker run -p 5000:5000 -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.2 - Added docs endpoint

---