Serving Your Personal Tutor with a RESTful API Using FastAPI

Serving Your Personal Tutor with a RESTful API Using FastAPI | CodeSignal Learn

Serving Your Personal Tutor with a RESTful API Using FastAPI

Welcome to the next step in our journey of building a personal tutor service with FastAPI . In the previous lesson, we focused on the TutorController, which manages tutoring sessions and handles student queries by interacting with both the model and service layers. Now, we will take a significant step forward by creating a RESTful API for our personal tutor service using FastAPI. We'll start by setting up the main FastAPI application, then adapt the TutorController to integrate with FastAPI's session management.

Understanding RESTful APIs and FastAPI

RESTful APIs are a way for different software systems to communicate over the internet. They provide a set of rules that allow programs to exchange data. FastAPI is a modern, fast (high-performance) web framework for building APIs with Python 3.7+ based on standard Python type hints. It is designed to be easy to use and to provide automatic interactive API documentation. To get started with FastAPI, you can install it using pip by running the following command in your terminal or command prompt: Shell pip install fastapi pip install fastapi Additionally, to run the FastAPI application, you'll need to install Uvicorn, an ASGI server: Shell pip install uvicorn pip install uvicorn Now, we can use FastAPI to connect the components we've already built, allowing students to interact with our personal tutor service through a web interface. This will enable seamless communication between students and our tutoring service.

Initializing a FastAPI App

First, we need to initialize the FastAPI application: Python from fastapi import FastAPI # Initialize FastAPI app app = FastAPI(title="Personal Tutor API") from fastapi import FastAPI # Initialize FastAPI app app = FastAPI(title="Personal Tutor API") Here, we import the FastAPI module and instantiate the FastAPI class to create our application object, app . We also give it a title, "Personal Tutor API," which will be displayed in the automatic API documentation that FastAPI generates. This object will be used to configure and run our web application.

Adding Session Management with Starlette Middleware

FastAPI does not have built-in session management, but it's built on top of Starlette, which provides session handling capabilities. When you install FastAPI, Starlette comes bundled with it, giving you access to its middleware components. A middleware is a function that works with every request before it's processed by any specific route handler. It sits between the server receiving the request and your route functions, allowing you to modify requests or responses globally. We can add Starlette's SessionMiddleware to our FastAPI application to enable session management: Python from starlette.middleware.sessions import SessionMiddleware # Add session middleware app.add_middleware(SessionMiddleware, secret_key="your_secret_key_here") from starlette.middleware.sessions import SessionMiddleware # Add session middleware app.add_middleware(SessionMiddleware, secret_key="your_secret_key_here") The SessionMiddleware handles creating, reading, and updating session data stored in cookies. The secret_key parameter is crucial for securing session data, as it's used to sign the session cookies to prevent tampering.

Join the 1M+ learners on CodeSignal

Be a part of our community of 1M+ users who develop and demonstrate their skills on CodeSignal

Setting Up Static Files and Templates

For our personal tutor service, we want to provide a user-friendly interface. FastAPI allows us to serve static files (CSS, JavaScript, images) and use templates to render HTML pages: Python from fastapi.staticfiles import StaticFiles from fastapi.templating import Jinja2Templates # Mount static files directory app.mount("/static", StaticFiles(directory="static"), name="static") # Setup Jinja2 templates templates = Jinja2Templates(directory="templates") from fastapi.staticfiles import StaticFiles from fastapi.templating import Jinja2Templates # Mount static files directory app.mount("/static", StaticFiles(directory="static"), name="static") # Setup Jinja2 templates templates = Jinja2Templates(directory="templates") The StaticFiles class enables serving static files from the specified directory, and Jinja2Templates sets up template rendering with Jinja2, a powerful template engine for Python.

Creating the Controller Instance

Next, we create an instance of our TutorController to handle the core operations of our personal tutor service: Python from controllers.tutor_controller import TutorController # Create an instance of TutorController to handle tutoring operations tutor_controller = TutorController() from controllers.tutor_controller import TutorController # Create an instance of TutorController to handle tutoring operations tutor_controller = TutorController() This controller will manage tutoring sessions and process student queries, serving as the bridge between our API endpoints and the underlying service layer. By instantiating it at the application level, we ensure it's available to all route handlers.

Defining Request Models with Pydantic

FastAPI uses Pydantic for data validation. We can define a model for the query request to ensure we receive the correct data structure: Python from pydantic import BaseModel class QueryRequest(BaseModel): session_id: str query: str from pydantic import BaseModel class QueryRequest(BaseModel): session_id: str query: str This model specifies that a query request must include a session_id and a query . FastAPI will automatically validate incoming requests against this model and return appropriate error responses if the data doesn't match.

Managing Student Sessions

To ensure each student has a unique identifier, we create a dependency function that checks for a student ID in the session and creates one if it doesn't exist: Python import uuid from fastapi import Depends, Request async def get_student_id(request: Request): if "student_id" not in request.session: request.session["student_id"] = str(uuid.uuid4()) return request.session["student_id"] import uuid from fastapi import Depends, Request async def get_student_id(request: Request): if "student_id" not in request.session: request.session["student_id"] = str(uuid.uuid4()) return request.session["student_id"] This function will be used as a dependency in our route handlers, ensuring that each student has a unique ID before processing their requests.

Creating the Index Route

Now that we've initialized our FastAPI application and created our controller instance, let's create the API endpoints that will allow students to interact with our personal tutor service. In FastAPI, routes are defined using decorators that specify the HTTP method and path. Python@app.get("/") async def index(request: Request, student_id: str = Depends(get_student_id)): return templates.TemplateResponse( "tutor.html", {"request": request} )@app.get("/") async def index(request: Request, student_id: str = Depends(get_student_id)): return templates.TemplateResponse( "tutor.html", {"request": request} ) This route handles GET requests to the root path (/). The @app.get("/") decorator tells FastAPI that this function should be called when a user visits the homepage. The function receives a Request object and uses the get_student_id dependency to ensure the student has an ID. It then returns a rendered HTML template, tutor.html, passing the request object to the template.

Creating New Tutoring Sessions

Next, let's define a route for creating new tutoring sessions: Python @app.post("/api/create_session") async def create_session(student_id: str = Depends(get_student_id)): response = tutor_controller.create_session(student_id) if isinstance(response, tuple): error_data = response[0]["error"] raise HTTPException(status_code=error_data["code"], detail=error_data["message"]) return response["data"] @app.post("/api/create_session") async def create_session(student_id: str = Depends(get_student_id)): response = tutor_controller.create_session(student_id) if isinstance(response, tuple): error_data = response[0]["error"] raise HTTPException(status_code=error_data["code"], detail=error_data["message"]) return response["data"] This route handles POST requests to /api/create_session . We use POST instead of GET because we're creating a new resource (a tutoring session). The route uses the get_student_id dependency to identify the student. The controller's create_session method returns either a success response or an error tuple. If it's an error, we raise an HTTPException with the appropriate status code and message; otherwise, we return the data part of the response.

Handling Student Queries

Finally, let's create a route for sending queries to the tutor: Python from fastapi import HTTPException @app.post("/api/send_query") async def send_query(query_request: QueryRequest, student_id: str = Depends(get_student_id)): response = tutor_controller.send_query(student_id, query_request.session_id, query_request.query) if isinstance(response, tuple): error_data = response[0]["error"] raise HTTPException(status_code=error_data["code"], detail=error_data["message"]) return response["data"] from fastapi import HTTPException @app.post("/api/send_query") async def send_query(query_request: QueryRequest, student_id: str = Depends(get_student_id)): response = tutor_controller.send_query(student_id, query_request.session_id, query_request.query) if isinstance(response, tuple): error_data = response[0]["error"] raise HTTPException(status_code=error_data["code"], detail=error_data["message"]) return response["data"] This route handles POST requests to /api/send_query . It expects a request body that matches our QueryRequest model, automatically validating and parsing the JSON payload. We also use the get_student_id dependency as before. The controller's send_query method processes the query and returns either a success response or an error tuple, which we handle similarly to the create_session route.

Custom Exception Handling

To ensure consistent error responses across our API, we can add a custom exception handler for HTTPException: Pythonfrom fastapi.responses import JSONResponse @app.exception_handler(HTTPException) async def http_exception_handler(request: Request, exc: HTTPException): return JSONResponse( status_code=exc.status_code, content={ "status": "error", "error": { "message": exc.detail, "code": exc.status_code } } )from fastapi.responses import JSONResponse @app.exception_handler(HTTPException) async def http_exception_handler(request: Request, exc: HTTPException): return JSONResponse( status_code=exc.status_code, content={ "status": "error", "error": { "message": exc.detail, "code": exc.status_code } } ) This handler ensures that all HTTPException instances are converted to JSON responses with a consistent structure, making it easier for clients to handle errors.

Running the FastAPI Server

Now that we've defined our routes and prepared our controller for integration with FastAPI, the final step is to set up the server to run our application. We'll use Uvicorn, an ASGI server, to serve our FastAPI application. Python import uvicorn # Start the ASGI server to run the FastAPI application if __name__ == "__main__": uvicorn.run("main:app", host="0.0.0.0", port=3000, reload=True) import uvicorn # Start the ASGI server to run the FastAPI application if __name__ == "__main__": uvicorn.run("main:app", host="0.0.0.0", port=3000, reload=True) This code block does several important things: The if __name__ == "__main__": condition ensures that the server only starts when we run this file directly, not when it's imported by another module. The uvicorn.run() function launches the ASGI server with our FastAPI application. The first argument, "main:app", tells Uvicorn where to find our application — in this case, the app variable in the main.py file. This syntax allows us to run the main file directly with a command like python main.py instead of having to use the uvicorn command-line interface. We set the host to "0.0.0.0" to make the server accessible from any network interface, not just localhost. This is useful if you want to access the server from other devices on your network. The port is set to 3000, so our application will be available at http://localhost:3000 . The reload=True parameter enables hot reloading, which automatically restarts the server when you make changes to your code. This is extremely helpful during development. Now, let's explore how our TutorController has been adapted to work with FastAPI's session management and request handling.

Adapting the TutorController

The TutorController has been designed to work seamlessly with FastAPI, handling student IDs and session management effectively. Let's examine its key methods and how they integrate with our API. Pythonclass TutorController: def __init__(self): self.tutor_service = TutorService() def create_session(self, student_id): if not student_id: return self._error_response('Session expired', 401) session_id = self.tutor_service.create_session(student_id) return self._success_response({ 'session_id': session_id, 'message': 'Tutoring session created successfully' })class TutorController: def __init__(self): self.tutor_service = TutorService() def create_session(self, student_id): if not student_id: return self._error_response('Session expired', 401) session_id = self.tutor_service.create_session(student_id) return self._success_response({ 'session_id': session_id, 'message': 'Tutoring session created successfully' }) The create_session method accepts a student_id parameter from FastAPI's session management. It checks if the student ID is valid, creates a new tutoring session using the TutorService, and returns a success response with the session ID. Python def send_query(self, student_id, session_id, student_query): if not student_id: return self._error_response('Session expired', 401) if not session_id or not student_query: return self._error_response('Missing session_id or query', 400) try: tutor_response = self.tutor_service.process_query( student_id, session_id, student_query ) return self._success_response({'message': tutor_response}) except ValueError as e: return self._error_response(str(e), 404) except RuntimeError as e: return self._error_response(str(e), 500) def send_query(self, student_id, session_id, student_query): if not student_id: return self._error_response('Session expired', 401) if not session_id or not student_query: return self._error_response('Missing session_id or query', 400) try: tutor_response = self.tutor_service.process_query( student_id, session_id, student_query ) return self._success_response({'message': tutor_response}) except ValueError as e: return self._error_response(str(e), 404) except RuntimeError as e: return self._error_response(str(e), 500) The send_query method is responsible for processing student queries. It receives the student ID, session ID, and the query content. After validating these parameters, it calls the process_query method on the TutorService to generate a response. The method includes comprehensive error handling, returning appropriate error responses for various scenarios. Python def _success_response(self, data): response = { 'status': 'success', 'data': data } return response def _error_response(self, message, status_code): response = { 'status': 'error', 'error': { 'message': message, 'code': status_code } } return response, status_code def _success_response(self, data): response = { 'status': 'success', 'data': data } return response def _error_response(self, message, status_code): response = { 'status': 'error', 'error': { 'message': message, 'code': status_code } } return response, status_code The controller also includes helper methods for generating consistent success and error responses. The _success_response method wraps data in a standard structure, while the _error_response method creates a tuple containing the error details and the appropriate HTTP status code. This consistent response format makes it easier for our FastAPI routes to handle the controller's output.

Serving Your Personal Tutor with a RESTful API Using FastAPI

Understanding RESTful APIs and FastAPI

Initializing a FastAPI App

Adding Session Management with Starlette Middleware

Join the 1M+ learners on CodeSignal

Setting Up Static Files and Templates

Creating the Controller Instance

Defining Request Models with Pydantic

Managing Student Sessions

Creating the Index Route

Creating New Tutoring Sessions

Handling Student Queries

Custom Exception Handling

Running the FastAPI Server

Adapting the TutorController

How Students Interact with the Personal Tutor API

Summary and Next Steps