API Development and Documentation Final Project

Trivia App

Trivia App contains following featuers:

1. Display questions - both all questions and by category. Questions should show the question, category and difficulty rating by default and can show/hide the answer.
2. Delete questions.
3. Add questions and require that they include question and answer text.
4. Search for questions based on a text query string.
5. Play the quiz game, randomizing either all questions or within a specific category.

Getting Started

Trivia App needs to run backend server and frontend website

Backend

Install Dependencies

1. Python 3.7 - Follow instructions to install the latest version of python for your platform in the python docs

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

3. PIP Dependencies - Once your virtual environment is setup and running, install the required dependencies by navigating to the /backend directory and running:

pip install -r requirements.txt

Set up the Database

With Postgres running, create a trivia database:

createdb trivia

Populate the database using the trivia.psql file provided. From the backend folder in terminal run:

psql trivia < trivia.psql

Run the Server

To run the server, execute:

export FLASK_APP=flaskr
export FLASK_ENV=development
flask run

Testing

Write at least one test for the success and at least one error behavior of each endpoint using the unittest library.

To deploy the tests, run

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

[Notice] Some tests cases need to be test before insert data into db, so we test them first then insert data and finally test other endpoints

To deploy the tests, run

dropdb trivia_test
createdb trivia_test
python test_flaskr_empty_table.py

Frontend

Installing Dependencies

1. Installing Node and NPM This project depends on Nodejs and Node Package Manager (NPM). Before continuing, you must download and install Node (the download includes NPM) from https://nodejs.com/en/download.

2. Installing project dependencies This project uses NPM to manage software dependencies. NPM Relies on the package.json file located in the frontend directory of this repository. After cloning, open your terminal and run:

npm install

tip: npm iis shorthand for `npm install``

Running Your Frontend in Dev Mode

The frontend app was built using create-react-app. In order to run the app in development mode use npm start. You can change the script in the package.json file.

Open http://localhost:3000 to view it in the browser. The page will reload if you make edits.

npm start

API Reference

Base url

http://127.0.0.1:5000/

Error Handling

Errors are returned as JSON objects in the following format:

{
    "success": False, 
    "error": 400,
    "message": "bad request"
}

The API will return three error types when requests fail:

• 400: Bad Request
• 404: Resource Not Found
• 422: Not Processable

Endpoints

GET '/categories'

• Fetches a dictionary of categories in which the keys are the ids and the value is the corresponding string of the category
• Request Arguments: None
• Returns: An object with a single key, categories, that contains an object of id: category_string key: value pairs.
• Sample: curl http://127.0.0.1:5000/categories

{
  "categories": {
    "1": "Science",
    "2": "Art",
    "3": "Geography",
    "4": "History",
    "5": "Entertainment",
    "6": "Sports"
    },
    "success": true
}

---

GET '/questions?page=${integer}'

• Fetches a paginated set of questions, a total number of questions, all categories and current category id(null).
• Request Arguments: page - integer
• Returns: An object with 10 paginated questions, total questions, object including all categories, and current category id(null)
• Sample 1: curl http://127.0.0.1:5000/questions
• Sample 2: curl http://127.0.0.1:5000/questions?page=2

{
  "categories": {
    "1": "Science",
    "2": "Art",
    "3": "Geography",
    "4": "History",
    "5": "Entertainment",
    "6": "Sports"
  },
  "current_category": null,
  "questions": [
    {
      "answer": "Agra",
      "category": 3,
      "difficulty": 2,
      "id": 15,
      "question": "The Taj Mahal is located in which Indian city?"
    }
  ],
  "success": true,
  "total_questions": 21
}

---

GET '/categories/${id}/questions'

• Fetches questions for a cateogry specified by id request argument
• Request Arguments: id - integer
• Returns: An object with questions for the specified category, total questions, and current category id
• Sample : curl http://127.0.0.1:5000/categories/1/questions

{
  "current_category": 1,
  "questions": [
    {
      "answer": "The Liver",
      "category": 1,
      "difficulty": 4,
      "id": 20,
      "question": "What is the heaviest organ in the human body?"
    }
  ],
  "success": true,
  "total_questions": 4
}

---

DELETE '/questions/${id}'

• Deletes a specified question using the id of the question
• Request Arguments: id - integer
• Returns: Return HTTP status code and id of deleted the question.
• Sample : curl -X DELETE http://127.0.0.1:5000/questions/1

{
    "deleted": 24,
    "success": true
}

---

POST '/questions'

• Sends a post request in order to add a new question
• Request Body:

{
    "question": "Heres a new question string",
    "answer": "Heres a new answer string",
    "difficulty": 1,
    "category": 3
}

• Returns: Return HTTP status code and id of the created question.
• Sample : curl http://127.0.0.1:5000/questions -X POST -H "Content-Type: application/json" -d '{"question":"Heres a new question string", "answer":"Heres a new answer string", "difficulty":1, "category":3}'

{
    "created": 26,
    "success": true
}

---

POST '/questions'

• Sends a post request in order to search for a specific question by search term
• Request Body:

{
  "searchTerm": "this is the term the user is looking for"
}

• Returns: any array of questions, a number of totalQuestions that met the search term and the current category id(null)
• Sample : curl http://127.0.0.1:5000/questions -X POST -H "Content-Type: application/json" -d '{"searchTerm":"body"}'

{
  "current_category": null,
  "questions": [
    {
      "answer": "The Liver",
      "category": 1,
      "difficulty": 4,
      "id": 20,
      "question": "What is the heaviest organ in the human body?"
    }
  ],
  "success": true,
  "total_questions": 1
}

---

POST '/quizzes'

• Sends a post request in order to get the next question, take category id and previous ids of questions as parameters
• Request Body:

{    
    'previous_questions': [1, 4, 20, 15]
    'quiz_category': 1
}

• Returns: a single new question object
• Sample : curl http://127.0.0.1:5000/quizzes -X POST -H "Content-Type: application/json" -d '{"previous_questions":[1,4,20,15], "quiz_category": 1}'

{
  "question": {
    "answer": "Blood",
    "category": 1,
    "difficulty": 4,
    "id": 22,
    "question": "Hematology is a branch of medicine involving the study of what?"
  },
  "success": true
}

Deployment N/A

Authors

Yours truly, Coach Caryn, Leo Wu

Acknowledgements

The awesome team at Udacity and all of the students, soon to be full stack extraordinaires!