WA Driver Guide Practice API

This repository contains the backend API for an application designed to help native Chinese speakers study the Washington Driver Guide for their knowledge test required to obtain a driver's license. The API leverages GPT-4 by OpenAI to generate questions based on the Washington Driver Guide.

The API is built using the FastAPI framework, which is known for its performance and ease of use. It also uses Turso as the database solution and asyncio for asynchronous database operations.

Deployments and Links:

• Frontend repository link
• Frontend deployment on Vercel link
• API repository link
• API deployment on Vercel link

Table of Contents

1. Getting Started
2. Technologies Used
3. Configuration
4. Database Schema
5. API Documentation
   • Get Questions
   • Create Questions
6. Error Handling
7. Deployment
8. Contributing
9. License

Getting Started

Prerequisites

Ensure you have the following installed:

• Python (v3.7 or later)
• pip package manager

Installation

Clone the repository:

git clone https://github.com/adamowada/wa-driver-guide-practice-api.git
cd wa-driver-guide-practice-api

Install the required dependencies:

pip install -r requirements.txt

Running the API Locally

TODO: Fix these instructions, current configuration works on Vercel's serverless functions but not locally. To run locally there should only be one instance of FastAPI(), using a router, and then run with uvicorn. Vercel is weird.

You can start the API server with the following command:

uvicorn api.get-questions:app --reload

The API will be available at http://127.0.0.1:8000.

Technologies Used

• FastAPI: A modern, fast (high-performance) web framework for building APIs with Python 3.7+ based on standard Python type hints.
• OpenAI GPT-4: Used for generating questions based on the Washington Driver Guide.
• Turso: Utilized as the database solution for storing questions and answers.
• asyncio: For asynchronous operations to handle database transactions efficiently.
• Vercel: Deployment platform for serverless applications.

Configuration

Create a .env file in the root directory and add your API keys and other configurations:

OPENAI_API_KEY=<your_openai_api_key>
TURSO_DB_URL=<your_turso_db_url>
TURSO_DB_AUTH_TOKEN=<your_turso_db_auth_token>

Database Schema

The database schema consists of two main tables: questions and answers.

Questions Table

This table stores the questions generated by the API.

Column	Type	Description
id	INTEGER	Primary key, auto-incremented
question_text	TEXT	The text of the question
image_url	TEXT	URL of the image associated with the question (optional)

Answers Table

This table stores the answers corresponding to each question.

Column	Type	Description
id	INTEGER	Primary key, auto-incremented
question_id	INTEGER	Foreign key referencing questions.id
answer_text	TEXT	The text of the answer
is_correct	BOOLEAN	Indicates if the answer is correct
explanation	TEXT	Explanation of the answer

API Documentation

Get Questions

• Endpoint: /api/get-questions
• Method: GET

Request

This endpoint does not require any parameters.

Response

• Status: 200 OK
• Body: JSON array of the questions and answers.

Example:

{
  "questions": [
    {
      "question": "Question text...",
      "answers": [
        {
          "text": "Answer text...",
          "correct": true,
          "explanation": "Explanation text..."
        },
        {
          "text": "Answer text...",
          "correct": false,
          "explanation": "Explanation text..."
        }
      ],
      "image_url": "http://example.com/image.png"
    }
  ]
}

Create Questions

• Endpoint: /api/create-questions
• Method: POST

Request

This endpoint does not require any parameters.

Response

• Status: 201 Created
• Body: JSON array of the created questions and answers.

Example:

{
  "questions": [
    {
      "question": "Question text...",
      "answers": [
        {
          "text": "Answer text...",
          "correct": true,
          "explanation": "Explanation text..."
        },
        {
          "text": "Answer text...",
          "correct": false,
          "explanation": "Explanation text..."
        }
      ],
      "image_url": "http://example.com/image.png"
    }
  ]
}

Error Handling

The API will return standard HTTP status codes to indicate the success or failure of an API request. Common status codes include:

• 200 OK: The request was successful.
• 201 Created: The resource was successfully created.
• 400 Bad Request: The request could not be understood or was missing required parameters.
• 401 Unauthorized: Authentication failed or user does not have permissions for the requested operation.
• 404 Not Found: The requested resource could not be found.
• 500 Internal Server Error: An error occurred on the server.

Deployment

Vercel

This API is configured to be deployed on Vercel. The vercel.json file includes the necessary configurations. To deploy, follow these steps:

1. Install Vercel CLI if you haven't already:

   npm install -g vercel

2. Deploy the project:

   vercel

Contributing

Contributions are welcome! If you have any ideas or improvements, please open an issue or submit a pull request.