Serving Your Personal Tutor with a RESTful API Using Symfony

Welcome to the next step in our journey of building a personal tutor service with Symfony. 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 Symfony. We'll explore how to structure our application with an ApiController that serves as the entry point for HTTP requests and delegates business logic to the TutorController.

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. Symfony is a popular PHP framework that simplifies the process of building web applications, including RESTful APIs. It offers a clean and flexible architecture, making it easy to create robust and scalable applications.

Symfony's routing system, controller architecture, and HTTP foundation components make it an excellent choice for building RESTful APIs. These components allow us to define clear endpoints, process requests, and return structured responses.

In our personal tutor service, we're implementing a two-controller architecture:

1. ApiController: Acts as the entry point for all HTTP requests, handling routing, request parsing, and response formatting
2. TutorController: Contains the business logic for managing tutoring sessions and processing student queries

This separation of concerns allows us to keep our API interface clean and focused on HTTP interactions, while the core tutoring logic remains independent of the web layer.

The ApiController serves as the entry point for all HTTP requests to our API. It's responsible for:

• Defining routes using Symfony's annotation system
• Parsing incoming request data
• Delegating to the TutorController for business logic
• Formatting responses as JSON

Let's examine the key components of our ApiController:

<?php

namespace App\Controller;

use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpFoundation\Session\SessionInterface;
use Symfony\Component\Routing\Annotation\Route;

class ApiController
{
    #[Route('/', name: 'app_index', methods: ['GET'])]
    public function index(SessionInterface $session): Response
    {
        // Create TutorController instance directly in the method
        $tutorController = new TutorController($session);
        
        // Ensure user has a session
        $tutorController->ensureUserSession($session);
        return new Response("Welcome to the Personal Tutor Service!");
    }

    #[Route('/api/create_session', name: 'api_create_session', methods: ['POST'])]
    public function createSession(SessionInterface $session): Response
    {
        // Create TutorController instance directly in the method
        $tutorController = new TutorController($session);
        
        // Handle tutoring session creation request
        $result = $tutorController->createSession($session);
        return new JsonResponse($result);
    }

    #[Route('/api/send_query', name: 'api_send_query', methods: ['POST'])]
    public function sendQuery(Request $request, SessionInterface $session): JsonResponse
    {
        // Create TutorController instance directly in the method
        $tutorController = new TutorController($session);
        
        // Parse JSON payload
        $data = json_decode($request->getContent(), true);
        
        // Send to the TutorController
        $result = $tutorController->sendQuery($session, $data);
        
        // Return result as JSON
        return new JsonResponse($result);
    }
}

Notice how each method in the ApiController follows a similar pattern:

1. Create an instance of the TutorController
2. Delegate the business logic to the appropriate method
3. Return the result as a properly formatted HTTP response

Symfony uses PHP attributes (previously called annotations) placed above controller methods—such as #[Route('/path', name: 'route_name')]—to automatically generate routes by reading these attributes during the application's routing configuration process.