Dev at

.gitignore

@@ -14,4 +14,5 @@ Thumbs.db
 env/
 frontend/node_modules/
 
-.env
+.env
+.venv

backend/README.md

@@ -24,6 +24,8 @@ pip install -r requirements.txt
 
 ### Set up the Database
 
+used Postgres.app for local development.
+
 With Postgres running, create a `trivia` database:
 
 ```bash
@@ -48,7 +50,7 @@ flask run --reload
 
 The `--reload` flag will detect file changes and restart the server automatically.
 
-## To Do Tasks
+## To Do Tasks (COMPLETED)
 
 These are the files you'd want to edit in the backend:
 
@@ -67,32 +69,133 @@ One note before you delve into your tasks: for each endpoint, you are expected t
 8. Create a `POST` endpoint to get questions to play the quiz. This endpoint should take a category and previous question parameters and return a random questions within the given category, if provided, and that is not one of the previous questions.
 9. Create error handlers for all expected errors including 400, 404, 422, and 500.
 
-## Documenting your Endpoints
 
-You will need to provide detailed documentation of your API endpoints including the URL, request parameters, and the response body. Use the example below as a reference.
+## API Reference
 
-### Documentation Example
+### Getting Started
+* **Base URL:** Currently, this app can only be run locally. The backend is hosted at `http://127.0.0.1:5000/`.
+* **Authentication:** This version of the application does not require authentication or API keys.
 
-`GET '/api/v1.0/categories'`
+### Error Handling
+Errors are returned as JSON objects in the following format:
+```json
+{
+    "success": False,
+    "error": 404,
+    "message": "resource not found"
+}
+```
+The API will return five types of errors for various failure conditions:
+* **400:** Bad Request
+* **404:** Resource Not Found
+* **405:** Method Not Allowed
+* **422:** Unprocessable
+* **500:** Internal Server Error
 
-- 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.
+---
 
+### Endpoints
+
+#### `GET /categories`
+- **General:** Fetches a dictionary of categories where keys are the IDs and values are the category names.
+- **Request Arguments:** None
+- **Returns:** An object with `categories` and `success` status.
 ```json
 {
-  "1": "Science",
-  "2": "Art",
-  "3": "Geography",
-  "4": "History",
-  "5": "Entertainment",
-  "6": "Sports"
+  "categories": {
+    "1": "Science",
+    "2": "Art",
+    "3": "Geography",
+    "4": "History",
+    "5": "Entertainment",
+    "6": "Sports"
+  },
+  "success": true
 }
 ```
 
-## Testing
+#### `GET /questions`
+- **General:** Returns a list of questions, number of total questions, current category, and categories.
+- **Request Arguments:** `page` (optional integer, defaults to 1).
+- **Returns:** Paginated questions (10 per page).
+```json
+{
+  "categories": { "1": "Science", "2": "Art" },
+  "current_category": null,
+  "questions": [
+    {
+      "id": 1,
+      "question": "What is the capital of Greece?",
+      "answer": "Athens",
+      "category": "3",
+      "difficulty": 1
+    }
+  ],
+  "success": true,
+  "total_questions": 1
+}
+```
+
+#### `DELETE /questions/<int:question_id>`
+- **General:** Deletes a question of a given ID if it exists.
+- **Request Arguments:** `question_id` (Path parameter).
+- **Returns:** ID of the deleted question and success status.
+```json
+{
+  "deleted": 1,
+  "success": true
+}
+```
 
-Write at least one test for the success and at least one error behavior of each endpoint using the unittest library.
+#### `POST /questions`
+- **General:** This endpoint handles two distinct actions:
+    1. **Create:** If no `searchTerm` is provided, it creates a new question.
+    2. **Search:** If a `searchTerm` is provided, it returns questions containing that string.
+- **Request Body (Create):** `question` (str), `answer` (str), `difficulty` (int), `category` (str).
+- **Request Body (Search):** `searchTerm` (str).
+- **Returns (Create):** ID of created question.
+- **Returns (Search):** List of matching questions.
+```json
+{
+  "questions": [],
+  "success": true,
+  "total_questions": 10
+}
+```
+
+#### `GET /categories/<int:category_id>/questions`
+- **General:** Returns all questions belonging to a specific category.
+- **Request Arguments:** `category_id` (Path parameter).
+- **Returns:** Paginated questions within that category.
+```json
+{
+  "questions": [...],
+  "total_questions": 5,
+  "current_category": "Science",
+  "success": true
+}
+```
+
+#### `POST /quizzes`
+- **General:** Returns a single random question within a chosen category that has not been previously asked.
+- **Request Body:** `previous_questions` (list of IDs), `quiz_category` (object with `id` and `type`).
+- **Returns:** A single question object.
+```json
+{
+  "question": {
+    "id": 5,
+    "question": "How many states are in the US?",
+    "answer": "50",
+    "category": "3",
+    "difficulty": 1
+  },
+  "success": true
+}
+```
+
+---
+
+## Testing
 
 To deploy the tests, run