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 .

Understanding RESTful APIs and Symfony

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.

The Controller Architecture

In our personal tutor service, we're implementing a two-controller architecture: ApiController : Acts as the entry point for all HTTP requests, handling routing, request parsing, and response formatting 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

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<?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: Create an instance of the TutorController Delegate the business logic to the appropriate method 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.

The TutorController

The TutorController contains the core business logic for our personal tutor service. It's responsible for: Managing student sessions Processing student queries Interacting with the TutorService to generate responses Let's examine the key components of our TutorController: PHP<?php namespace App\Controller; require_once __DIR__ . '/../Service/TutorService.php'; use App\Service\TutorService; use Symfony\Component\HttpFoundation\Session\SessionInterface; class TutorController { private TutorService $tutorService; public function __construct(SessionInterface $session = null) { $this->tutorService = new TutorService($session); } public function ensureUserSession(SessionInterface $session): string { if (!$session->has('student_id')) { $session->set('student_id', uniqid('', true)); } return $session->get('student_id'); } public function createSession(SessionInterface $session): array { $studentId = $session->get('student_id'); if (!$studentId) { return ['error' => 'Session expired', 'code' => 401]; } $sessionId = $this->tutorService->createSession($studentId); return [ 'session_id' => $sessionId, 'message' => 'Tutoring session created successfully' ]; } public function sendQuery(SessionInterface $session, array $data): array { $studentId = $session->get('student_id'); if (!$studentId) { return ['error' => 'Session expired', 'code' => 401]; } // Extract session_id and query from the data array $sessionId = $data['session_id'] ?? null; $studentQuery = $data['query'] ?? null; if (!$sessionId || !$studentQuery) { return ['error' => 'Missing session_id or query', 'code' => 400]; } try { $tutorResponse = $this->tutorService->processQuery($studentId, $sessionId, $studentQuery); return ['response' => $tutorResponse]; } catch (\ValueError $e) { return ['error' => $e->getMessage(), 'code' => 404]; } catch (\RuntimeException $e) { return ['error' => $e->getMessage(), 'code' => 500]; } } } The TutorController handles several key responsibilities: Session Management: The ensureUserSession method creates and manages unique student IDs using Symfony's session system Input Validation: Methods like sendQuery validate input data and return appropriate error responses Error Handling: Try-catch blocks capture exceptions from the service layer and transform them into structured error responses Service Delegation: The controller delegates the actual tutoring logic to the TutorService

Defining Routes with routes.yaml

While Symfony supports route definitions using PHP attributes (annotations) directly in your controller classes, you can also define your application's routes in a configuration file called routes.yaml. This approach is especially useful for centralizing and managing your routes in one place. Here's an example of how you can define the home page route in config/routes.yaml: YAMLapp_index: path: / controller: App\Controller\ApiController::indexapp_index: path: / controller: App\Controller\ApiController::index In this example: app_index is the name of the route. path specifies the URL path (/ for the home page). controller points to the controller and method that should handle the request. You can define additional routes for your API endpoints in the same file: YAMLapi_create_session: path: /api/create_session controller: App\Controller\ApiController::createSession methods: [POST] api_send_query: path: /api/send_query controller: App\Controller\ApiController::sendQuery methods: [POST]api_create_session: path: /api/create_session controller: App\Controller\ApiController::createSession methods: [POST] api_send_query: path: /api/send_query controller: App\Controller\ApiController::sendQuery methods: [POST] This approach provides a clear overview of all your application's routes and can be used alongside or instead of PHP attribute-based routing, depending on your project's needs.

Session Management in Symfony

Our application uses Symfony's session management to track student interactions. The SessionInterface is automatically injected into our controller methods, allowing us to: Generate and store unique student IDs Maintain state between requests Ensure security by validating session data The ensureUserSession method demonstrates this pattern: PHPpublic function ensureUserSession(SessionInterface $session): string { if (!$session->has('student_id')) { $session->set('student_id', uniqid('', true)); } return $session->get('student_id'); }public function ensureUserSession(SessionInterface $session): string { if (!$session->has('student_id')) { $session->set('student_id', uniqid('', true)); } return $session->get('student_id'); } This method checks if a student ID exists in the session, creates one if needed, and returns the ID. This ensures that each student has a consistent identity across multiple requests.

Error Handling and Response Formatting

Our API implements consistent error handling and response formatting. The TutorController returns structured arrays that include: Success responses with relevant data Error responses with descriptive messages and appropriate HTTP status codes The ApiController then converts these structured arrays into proper HTTP responses using Symfony's JsonResponse class: PHP $result = $tutorController->sendQuery($session, $data); return new JsonResponse($result); This approach ensures that our API provides clear, consistent responses that clients can easily parse and handle.

Running the Symfony Application

To run your Symfony application, you can use the built-in web server provided by the Symfony CLI: Shell symfony server:start symfony server:start Or, if you don't have the Symfony CLI: Shell php -S localhost:3000 -t public php -S localhost:3000 -t public This command will start the Symfony development server, making your application accessible at http://localhost:3000 . You can now test your API endpoints using a tool like Postman or a web browser.

API Endpoints

Our personal tutor service exposes three main endpoints: GET / - The home page that welcomes users and ensures they have a session POST /api/create_session - Creates a new tutoring session for the current student POST /api/send_query - Processes a student query and returns a tutor response To use the API, clients would typically: Visit the home page to establish a session Create a tutoring session using the /api/create_session endpoint Send queries using the /api/send_query endpoint, including the session ID and query text

Summary and Next Steps

In this lesson, we successfully built a RESTful API for our personal tutor service using Symfony . We implemented a two-controller architecture that separates HTTP concerns from business logic, used Symfony's session management to track student interactions, and created a consistent error handling and response formatting system. This architecture provides a solid foundation for our personal tutor service, allowing it to scale and evolve as we add more features. The separation of concerns between the ApiController and TutorController makes our code more maintainable and testable, while Symfony's powerful features handle the complexities of HTTP interactions and session management. As you move on to the practice exercises, take the opportunity to experiment with the Symfony API and reinforce the concepts covered in this lesson. Try adding new endpoints, enhancing error handling, or extending the session management system to better understand how these components work together.

Previous Lesson

Join the 1M+ learners on CodeSignal

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