Building a RESTful Tutor API with Axum

Welcome to the next step in building a personal tutor service with Axum. 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 Axum, a modern web framework. We'll start by setting up the main Axum application, then adapt the TutorController to integrate with Axum's state management and routing.

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. Axum is a modern, ergonomic web framework for building APIs. It is designed to be type-safe, modular, and easy to use, leveraging async capabilities.

To get started with Axum, add it to your project by including it in your Cargo.toml dependencies:

[dependencies]
axum = "0.7"
tokio = { version = "1", features = ["full"] }
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"
thiserror = "1.0"
anyhow = "1.0"
uuid = { version = "1.4", features = ["v4"] }
dotenv = "0.15"
async-openai = "0.14"

Once you have added these dependencies, you can use Cargo to build and run your application:

cargo run

Now, we can use Axum 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.

Next, we create an instance of our TutorController to handle the core operations of our personal tutor service. We use structs and shared state to manage controller instances:

let controller = Arc::new(Mutex::new(TutorController::new()));

We wrap the controller in an Arc<Mutex<...>> to allow safe, concurrent access from multiple request handlers in our async application. This controller will manage tutoring sessions and process student queries, serving as the bridge between our API endpoints and the underlying service layer.

We define request and response models using structs and derive macros from the serde crate for serialization and deserialization:

// Payload for creating a new tutoring session (client sends this)
#[derive(Deserialize)]
pub struct CreateSessionRequest {
    pub student_id: String,
}

// Response returned after successfully creating a session
#[derive(Serialize)]
pub struct CreateSessionResponse {
    pub session_id: String,
    pub message: String,
}

// Payload for sending a query to the tutor (client sends this)
#[derive(Deserialize)]
pub struct SendQueryRequest {
    pub student_id: String,
    pub session_id: String,
    pub query: String,
}

// Response returned after processing a tutoring query
#[derive(Serialize)]
pub struct SendQueryResponse {
    pub message: String,
}

These structs specify the expected structure of incoming requests and outgoing responses. Axum will automatically parse and validate JSON payloads against these models.

Each student is identified by a unique student_id, which is provided in the request payload. The client is responsible for generating and storing this identifier (for example, using a UUID). The server uses this student_id to manage sessions and personalize tutoring interactions.

To generate a new student_id, we'll use the uuid crate:

let student_id = Uuid::new_v4().to_string();

This approach keeps the API stateless and allows for flexible session management. Note that this is a simple and effective method for basic applications, in more advanced systems however, you might use authentication tokens, cookies, or server-managed sessions to provide stronger security and a better user experience.

For now, let's focus on creating a simple API using Axum.

Now that we've initialized our Axum application and created our controller instance, let's create the API endpoints that will allow students to interact with our personal tutor service. In Axum, routes are defined using handler functions:

pub async fn root() -> &'static str {
    "Welcome to the Tutor API!"
}

This route handles GET requests to the root path (/). It simply returns a welcome message as plain text.

Next, let's define a route for creating new tutoring sessions:

pub async fn create_session(
    Extension(controller): Extension<Arc<Mutex<TutorController>>>,
    Json(payload): Json<CreateSessionRequest>,
) -> Result<Json<CreateSessionResponse>, AppError> {
    let session_id = {
        let mut controller_guard = controller.lock().await;
        controller_guard.create_session(payload.student_id)?
    };

    Ok(Json(CreateSessionResponse {
        session_id,
        message: "Tutoring session created successfully".into(),
    }))
}

This route handles POST requests to /api/create_session. It expects a JSON payload containing the student_id. The controller's create_session method returns either a success response or an error, which is handled using the Result type. The Extension extractor is used to share application state (such as the controller instance) across different request handlers in Axum.

The AppError type is used for error handling and ensures that errors are returned in a consistent JSON format, as shown in the custom exception handling section later in this lesson.

Let's also define a route for sending queries to the tutor:

pub async fn send_query(
    Extension(controller): Extension<Arc<Mutex<TutorController>>>,
    Json(payload): Json<SendQueryRequest>,
) -> Result<Json<SendQueryResponse>, AppError> {
    let message = {
        let mut controller_guard = controller.lock().await;
        controller_guard
            .send_query(payload.student_id, payload.session_id, payload.query)
            .await?
    };

    Ok(Json(SendQueryResponse { message }))
}

This route handles POST requests to /api/send_query. It expects a JSON payload with the student_id, session_id, and query. The controller's send_query method processes the query and returns either a success response or an error.

To ensure consistent error responses across our API, we define a custom error type and implement the IntoResponse trait for it:

#[derive(Debug, thiserror::Error)]
pub enum AppError {
    #[error("Not found: {0}")]
    NotFound(String),

    #[error("Unauthorized: {0}")]
    Unauthorized(String),

    #[error("Bad request: {0}")]
    BadRequest(String),

    #[error("Internal error: {0}")]
    Internal(String),
}

impl IntoResponse for AppError {
    fn into_response(self) -> Response {
        let (status, error_message) = match self {
            Self::NotFound(msg) => (StatusCode::NOT_FOUND, msg),
            Self::Unauthorized(msg) => (StatusCode::UNAUTHORIZED, msg),
            Self::BadRequest(msg) => (StatusCode::BAD_REQUEST, msg),
            Self::Internal(msg) => (StatusCode::INTERNAL_SERVER_ERROR, msg),
        };

        let body = Json(json!({
            "status": "error",
            "error": {
                "message": error_message,
                "code": status.as_u16()
            }
        }));

        (status, body).into_response()
    }
}

This implementation ensures that all errors are converted to JSON responses with a consistent structure, making it easier for clients to handle errors.

In the previous unit, the TutorController was a simple struct that managed a test session and delegated to the TutorService. To integrate with Axum and support stateless API requests, we should make several key changes:

• The controller should now accept student_id and session_id as explicit parameters, rather than relying on internal state or a test session map.
• Error handling can be standardized using a custom AppError type, allowing for consistent API responses.
• The controller methods should support calls from async request handlers, supporting concurrent access via Arc<Mutex<...>>.

Here is how the updated TutorController might look like:

pub struct TutorController {
    service: TutorService,
}

impl TutorController {
    pub fn new() -> Self {
        Self {
            service: TutorService::new(),
        }
    }

    pub fn create_session(&mut self, student_id: String) -> Result<String, AppError> {
        if student_id.is_empty() {
            return Err(AppError::Unauthorized("Session expired".to_string()));
        }

        let session_id = self.service.create_session(&student_id);
        Ok(session_id)
    }

    pub async fn send_query(
        &mut self,
        student_id: String,
        session_id: String,
        query: String,
    ) -> Result<String, AppError> {
        if student_id.is_empty() {
            return Err(AppError::Unauthorized("Session expired".to_string()));
        }

        if session_id.is_empty() || query.is_empty() {
            return Err(AppError::BadRequest("Missing session_id or query".to_string()));
        }

        self.service
            .process_query(&student_id, &session_id, &query)
            .await
            .map_err(|err| {
                if err.to_string().contains("Session not found") {
                    AppError::NotFound(err.to_string())
                } else {
                    AppError::Internal(err.to_string())
                }
            })
    }
}

This updated controller is now stateless and ready for use in a web API context. By taking all necessary identifiers as parameters and returning standardized errors, it can be safely shared across concurrent requests and easily integrated with Axum's async handlers.

To interact with our personal tutor service, a student can follow these steps:

1. Access the Index Route (/): The student begins by accessing the index route of the API. This step can be used to verify that the API is running and available. The server responds with a welcome message, ready for interaction.

2. Create a Tutoring Session (/api/create_session): Before sending a query, the student needs to create a new tutoring session. This is done by sending a POST request to the /api/create_session route with their student_id. The server will respond with a unique session ID, which is essential for identifying the tutoring session in subsequent interactions.

3. Send a Query (/api/send_query): With the tutoring session established, the student can now send academic questions to the personal tutor. This involves sending a POST request to the /api/send_query route, including the student_id, session_id, and the query content. The server processes the query using the DeepSeek model and responds with the tutor's explanation, allowing the student to continue the learning conversation.

By following these steps, a student can effectively receive personalized academic support from our personal tutor service, leveraging the RESTful API to manage tutoring sessions and exchange queries.

Now that we've defined our routes and prepared our controller for integration with Axum, the final step is to set up the server to run our application. We use the tokio runtime and the main function to launch the server:

#[tokio::main]
async fn main() {
    let controller = Arc::new(Mutex::new(TutorController::new()));

    let app = Router::new()
        .route("/", get(routes::root))
        .route("/api/create_session", post(routes::create_session))
        .route("/api/send_query", post(routes::send_query))
        .layer(Extension(controller));

    let listener = tokio::net::TcpListener::bind("127.0.0.1:3000")
        .await
        .expect("failed to bind");
    println!("Listening on http://127.0.0.1:3000");

    axum::serve(listener, app).await.unwrap();
}

This code block does several important things:

1. The controller is created and shared across handlers using Arc<Mutex<...>>.
2. The Axum Router is configured with the necessary routes and layers.
3. The server listens on port 3000 and prints a message to indicate it is running.

This setup ensures that your application can handle multiple concurrent requests efficiently while maintaining safe access to shared state, and provides a clear entry point for interacting with your tutor API!

In this lesson, we successfully built a RESTful API for our personal tutor service using Axum. We set up an Axum application, defined routes for tutoring operations, and explored how the TutorController integrates with Axum's state management and error handling. This lesson marks a significant milestone in our course, as it brings together all the components we've developed so far into a functional web application that can deliver personalized academic support at scale.

As you move on to the practice exercises, take the opportunity to experiment with the Axum API and reinforce the concepts covered in this lesson. This hands-on practice will prepare you for further development and exploration of additional Axum features and RESTful API concepts.