marceaudavid / agotapi

A Game of Thrones API built on node.js, express and mongodb

AGOTAPI

Introduction

Welcome on agotapi, a Game of Thrones API.

Installation

Local

Make sure git and node.js are installed on your computer. Then you can clone this repository :

git clone https://github.com/marceaudavid/agotapi.git
cd agotapi

Install the dependencies :

npm install

And launch the project :

node app.js --port=3000 --prettify=1

This command take two flags, port and prettify, port is used to defined the port on which the app is launched and prettify is used to set the number of space to prettify json.

If the database is empty you can populate it with the command below :

npm run seed

Docker

To lauch this project with Docker, make sure Docker is installed and clone this repository. Then replace the MongoDB connection string in mongo/db.js :

mongoose.connect("mongodb://mongo:27017/api");

Next you have to build the docker images :

docker-compose build

Finally you can run the container :

docker-compose up

Usage

Methods

This API allow GET, POST, PUT and DELETE request.

Example

Let's start by performing a GET request on one particular ressource :

https://agotapi.herokuapp.com/api/place/1

Here is the response :

{
  "_id": 1,
  "name": "Winterfell",
  "type": "Castle",
  "location": "The North",
  "rulers": "House Stark"
}

Filters

You can filter the set of ressources returned with query parameters :

https://agotapi.herokuapp.com/api/place/?type=Castle

Muliples paramaters are also supported :

https://agotapi.herokuapp.com/api/place/?type=Castle&name=Highgarden

Ressources

Characters

The character ressources is a set of the most important characters of the show.

URL : https://agotapi.herokuapp.com/api/character

URI endpoints	Methods allowed	Description
/api/character	GET, POST	Get all characters or the added character
/api/character/:id	GET, PUT, DELETE	Get the one specific character, the updated one or the deleted one

Attributes :

Name	Type	Required	Description
_id	Number	True	The character's id
name	Number	True	The character's firstname and lastname
gender	String	True	The character's gender (male or female)
born	String	False	The character's date of birth (BC : Before the Conquest, AC : After the Conquest)
origin	String	False	The character's place of birth
death	String	False	The character's date of deatch (null if the character is still alive)
status	String	True	The character's status (alive, deceased or ressurected)
culture	String	True	The character's culture
religion	String	False	The character's religion (null if unknown)
titles	Array	False	An array of the character's titles (null if the character does not own titles)
house	String	False	The character's house (null if the character is not noble)
father	String	False	The character's father (null if unknown)
mother	String	False	The character's mother (null if unknown)
spouse	Array	False	The character's spouse(s) (null if the character never married)
children	Array	False	The character's children (null if the character does not have children)
siblings	Array	False	The character's sibling(s) (null if the character is only child or if the siblings are unknown)
lovers	Array	False	The character's lover(s) (null if the character does not have lovers)
seasons	Array	True	An array of season's number in which the character appeared
actor	String	True	The actor who played this character

Houses

The house ressources is a set of the most well-known houses of the game of thrones universe.

URL : https://agotapi.herokuapp.com/api/house

URI endpoints	Methods allowed	Description
/api/house	GET, POST	Get all houses or the added house
/api/house/:id	GET, PUT, DELETE	Get the one specific house, the updated one or the deleted one

Attributes :

Name	Type	Required	Description
_id	Number	True	The house's id
name	String	True	The house's name
sigil	String	True	The house's heraldry description
words	String	True	The house's words (e.g "Winter is Coming")
seat	String	True	The house's traditional seat
region	String	True	The house's native region
vassals	Array	False	The house's traditionnal vassals (null if the house does not have vassals)
founder	String	False	The house's founder (null if unknown)

Places

The place ressources is a set of the most well-known places of the game of thrones world.

URL : https://agotapi.herokuapp.com/api/place

URI endpoints	Methods allowed	Description
/api/place	GET, POST	Get all places or the added place
/api/place/:id	GET, PUT, DELETE	Get the one specific place, the updated one or the deleted one

Attributes :

Name	Type	Required	Description
_id	Number	True	The place's id
name	String	True	The place's name
type	String	True	The place's type (Castle, City or City-State)
location	String	True	The place's region
ruler	String	False	The place's ruler (null if unknown)

Quotes

The quote ressources is a set of the best quotes of the show's character.

URL : https://agotapi.herokuapp.com/api/quote

URI endpoints	Methods allowed	Description
api/quote	GET, POST	Get all places or the added place
api/quote/:id	GET, PUT, DELETE	Get the one specific place, the updated one or the deleted one
api/quote/random	GET	Get a random quote
api/quote/random/view	GET	Get a random quote with a nice UI

Attributes :

Name	Type	Required	Description
_id	Number	True	The quote's id
quote	String	True	The quote itself
from	String	True	The character who says the quote
to	String	False	His interlocutor (null if unknown)
season	Number	True	The quote's season
episode	Number	True	The quote's episode

Test

You can test the request with Insomnia. The insomnia.json file already contains all the preconfigured request

About

Game of Thrones and all associated names are copyrights owned by HBO Inc.

This API is specifically based on the television show.

All the data has been freely collected from open sources such as Game of Thrones Wiki.

agotapi's Issues

API down

Hey, I've been tinkering with the api and it's down in the last few hours. Any idea why?
Thank you!