Skip to content

Latest commit

 

History

History

flask

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
flaskr
flaskr
 
 
.gitignore
.gitignore
 
 
README.md
README.md
 
 
models.py
models.py
 
 
pip
pip
 
 
requirements.txt
requirements.txt
 
 
test_flaskr.py
test_flaskr.py
 
 
trivia.psql
trivia.psql
 
 

README.md

Full Stack Trivia API Backend documentation

Overview

This documentation is aimed to make you familiar with the work done on this API, how to interact with it's endpoints and what to expect as a response.

Table of contents

Getting Started

Installing Dependencies

Python 3.7

Follow instructions to install the latest version of python for your platform in the python docs

Virtual Environment

We recommend working within a virtual environment whenever using Python for projects. This keeps your dependencies for each project separate and organaized. Instructions for setting up a virual enviornment for your platform can be found in the python docs

PIP Dependencies

Once you have your virtual environment setup and running, install dependencies by naviging to the /backend directory and running:

pip install -r requirements.txt

This will install all of the required packages we selected within the requirements.txt file.

Key Dependencies

  • Flask is a lightweight backend microservices framework. Flask is required to handle requests and responses.

  • SQLAlchemy is the Python SQL toolkit and ORM we'll use handle the lightweight sqlite database. You'll primarily work in app.py and can reference models.py.

  • Flask-CORS is the extension we'll use to handle cross origin requests from our frontend server.

Database Setup

With Postgres running, restore a database using the trivia.psql file provided. From the backend folder in terminal run:

psql trivia < trivia.psql

Running the server

From within the backend directory first ensure you are working using your created virtual environment.

To run the server, execute:

cd flask
export FLASK_APP=flaskr
export FLASK_ENV=development
flask run

Setting the FLASK_ENV variable to development will detect file changes and restart the server automatically.

Setting the FLASK_APP variable to flaskr directs flask to use the flaskr directory and the __init__.py file to find the application.

Response Codes

Response Codes

200: Success
400: Bad request
404: Cannot be found
422: Unprocessable Entity 
50X: Server Error

Example Error Message

{
  "details": "404 Not Found: The requested URL was not found on the server. If you entered the URL manually please check your spelling and try again.", 
  "error": 404, 
  "message": "Not found", 
  "success": false
}

API Resources

Category Resource

Get categories

  • Description: Fetches a dictionary of categories in which the keys are the ids and the value is the corresponding string of the category.

  • Return: An object with a single key, categories, that contains a object of id: category_string key:value pairs.

  • URL: /categories

  • Method: GET

  • URL Params:

    Optional: page=<int>

  • Data Params: None

  • Success Response:

    • Code: 200

      Body (Click to expand) 
       {
  "categories": {
    "1": "Science", 
    "2": "Art", 
    "3": "Geography", 
    "4": "History", 
    "5": "Entertainment", 
    "6": "Sports"
  }
}

  • Sample Call:

      fetch("http://127.0.0.1:5000/categories")

Question Resource

Get questions

  • Description: Used to get all questions paginated.

  • Return: A list of questions paginated (10 per page), a list of categories, current category and total questions count.

  • URL: /questions

  • Method: GET

  • URL Params:

    Optional: page=<int>

  • Data Params: None

  • Success Response:

    • Code: 200

      Body (Click to expand) 
      {
  "categories": {
    "1": "Science",
    "2": "Art",
    "3": "Geography",
    "4": "History",
    "5": "Entertainment",
    "6": "Sports"
  },
  "current_category": 1,
  "questions": [
    {
      "answer": "Maya Angelou",
      "category": 4,
      "difficulty": 2,
      "id": 5,
      "question": "Whose autobiography is entitled 'I Know Why the Caged Bird Sings'?"
    },
    {
      "answer": "Muhammad Ali",
      "category": 4,
      "difficulty": 1,
      "id": 9,
      "question": "What boxer's original name is Cassius Clay?"
    },
    {
      "answer": "Tom Cruise",
      "category": 5,
      "difficulty": 4,
      "id": 4,
      "question": "What actor did author Anne Rice first denounce, then praise in the role of her beloved Lestat?"
    },
    {
      "answer": "Edward Scissorhands",
      "category": 5,
      "difficulty": 3,
      "id": 6,
      "question": "What was the title of the 1990 fantasy directed by Tim Burton about a young man with multi-bladed appendages?"
    },
    {
      "answer": "Brazil",
      "category": 6,
      "difficulty": 3,
      "id": 10,
      "question": "Which is the only team to play in every soccer World Cup tournament?"
    },
    {
      "answer": "Uruguay",
      "category": 6,
      "difficulty": 4,
      "id": 11,
      "question": "Which country won the first ever soccer World Cup in 1930?"
    },
    {
      "answer": "George Washington Carver",
      "category": 4,
      "difficulty": 2,
      "id": 12,
      "question": "Who invented Peanut Butter?"
    },
    {
      "answer": "Lake Victoria",
      "category": 3,
      "difficulty": 2,
      "id": 13,
      "question": "What is the largest lake in Africa?"
    },
    {
      "answer": "Agra",
      "category": 3,
      "difficulty": 2,
      "id": 15,
      "question": "The Taj Mahal is located in which Indian city?"
    },
    {
      "answer": "Escher",
      "category": 2,
      "difficulty": 1,
      "id": 16,
      "question": "Which Dutch graphic artist–initials M C was a creator of optical illusions?"
    }
  ],
  "total_questions": 35
}

  • Sample Call:

      fetch("http://127.0.0.1:5000/questions")

DELETE Questions

  • Description: Used to delete a question by it's id.

  • Return: Returns a dict with the value 'success' equals ture on success and false on failure.

  • URL: /questions/<question_id>

  • Method: DELETE

  • URL Params:

    Optional: None

  • Data Params: None

  • Success Response:

    • Code: 200

      Body (Click to expand) 
      { "success": true }

  • Failure Response:

    • Code: 404

      Body (Click to expand) 
      {
  "details": "404 Not Found: The requested URL was not found on the server. If you entered the URL manually please check your spelling and try again.",
  "error": 404,
  "message": "Not found",
  "success": false
}

  • Sample Call:

      fetch('http://127.0.0.1:5000/questions/30', {method: 'DELETE'})

Create Question

  • Description: Used to add new question to the DB.

  • Return: Returns a dict with the value 'success' equals ture on success and false on failure and 'question' holding the added question in case of success.

  • URL: /questions

  • Method: POST

  • URL Params:

    Optional: None

  • Data Params: Required:

    1. question: The question text.
    2. answer: The answer text.
    3. answer: The answer text.
    4. category: The question category id.
    5. category: The question difficulty level.

  • Success Response:

    • Code: 200

      Body (Click to expand) 
      {
  "question": {
    "answer": "sdf",
    "category": 4,
    "difficulty": 2,
    "id": 42,
    "question": "sdf"
  },
  "success": true
}

  • Sample Call:

      fetch("http://127.0.0.1:5000/questions", {
    "headers": {
      "content-type": "application/json"
    },
    "body": JSON.stringify({question: "text q", answer: "test a", category: "4", difficulty: "2"}),
    "method": "POST",
  })

Search Questions

  • Description: Used to add search for a question in the DB.

  • Return: Returns a dict with the following values:

    1. 'success' equals ture on success and false on failure.
    2. 'questions' a list of the filtered question.
    3. 'total_questions' the count of the total matched questions.
    4. 'current_category' the first question category.

  • URL: /questions/search

  • Method: POST

  • URL Params:

    Optional: None

  • Data Params: Required:

    1. searchTerm: String holding the search term.

  • Success Response:

    • Code: 200

      Body (Click to expand) 
      {
  "current_category": 1,
  "questions": [
    {
      "answer": "Escher",
      "category": 1,
      "difficulty": 1,
      "id": 33,
      "question": "Which Dutch graphic artist–initials M C was a creator of optical illusions?"
    }
  ],
  "success": true,
  "total_questions": 1
}

  • Sample Call:

      fetch("http://127.0.0.1:5000/search", {
    "headers": {
      "content-type": "application/json"
    },
    "body": JSON.stringify({searchTerm: "Dutch"}),
    "method": "POST"
  })

Get Questions based on category

  • Description: Used to get specific category questions (not-paginated).

  • Return: Returns a dict with the following values:

    1. 'questions' a list of the category questions.
    2. 'total_questions' The count of the total category questions.
    3. 'current_category' The category id.

  • URL: /categories/<int:category_id>/questions

  • Method: GET

  • URL Params: None

  • Data Params: None

  • Success Response:

    • Code: 200

      Body (Click to expand) 
      {
  "current_category": 2,
  "questions": [
    {
      "answer": "Escher",
      "category": 2,
      "difficulty": 1,
      "id": 16,
      "question": "Which Dutch graphic artist–initials M C was a creator of optical illusions?"
    },
    {
      "answer": "Mona Lisa",
      "category": 2,
      "difficulty": 3,
      "id": 17,
      "question": "La Giaconda is better known as what?"
    },
    {
      "answer": "One",
      "category": 2,
      "difficulty": 4,
      "id": 18,
      "question": "How many paintings did Van Gogh sell in his lifetime?"
    },
    {
      "answer": "Jackson Pollock",
      "category": 2,
      "difficulty": 2,
      "id": 19,
      "question": "Which American artist was a pioneer of Abstract Expressionism, and a leading exponent of action painting?"
    },
    {
      "answer": "sal;jf",
      "category": 2,
      "difficulty": 2,
      "id": 31,
      "question": "aljfdh"
    },
    {
      "answer": "jklahdflk",
      "category": 2,
      "difficulty": 2,
      "id": 32,
      "question": "asfdajh"
    },
    {
      "answer": "jlkhadk",
      "category": 2,
      "difficulty": 2,
      "id": 37,
      "question": "aslkdhfk"
    }
  ],
  "total_questions": 7
}

  • Sample Call:

      fetch("http://127.0.0.1:5000/categories/2/questions")

Get Questions to play

  • Description: Takes a category and previous questions array

  • Return: Returns a dict with the following values:

    1. 'success' Boolean to indicated success.
    2. 'question' The next question.

  • URL: /quizzes

  • Method: POST

  • URL Params: None

  • Data Params: Required:

    1. previous_questions: Array of the previous question to avoid sending them back.
    2. quiz_category: The category to send questions from.

  • Success Response:

    • Code: 200

      Body (Click to expand) 
      {
  "question": {
    "answer": "sal;jf",
    "category": 2,
    "difficulty": 2,
    "id": 31,
    "question": "aljfdh"
  },
  "success": true
}

  • Sample Call:

      fetch("http://127.0.0.1:5000/quizzes", {
    "headers": {
      "content-type": "application/json"
    },
    "body": JSON.stringify({previous_questions: [1, 2, 3], quiz_category: {id: 2}}),
    "method": "POST"
  })

Testing The API

To run the tests, run

dropdb trivia_test
createdb trivia_test
psql trivia_test < trivia.psql
python test_flaskr.py

The available tests in this project checks that the following are true:

  1. You are able to get paginated questions using GET '/questions'
  2. You are able to get questions from specific search term using POST '/questions/search'
  3. You are able to get questions for quiz from previous_questions array & quiz_category object using POST '/quizzes'
  4. You are able to create new question and store in the db using POST '/questions'
  5. You are able to delete any question by id using DELETE '/questions'
  6. You are able to get questions from specific category using GET '/categories/<int:category_id>/questions'