Serving Your Personal Tutor with a RESTful API

Welcome to the next step in our journey of building a personal tutor service. 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. We'll explore how to structure our application with an API entry point that serves as the gateway for HTTP requests and delegates business logic to the TutorController . We will use Laravel, a popular PHP framework, to implement our API and controller structure.

Understanding RESTful APIs

RESTful APIs provide a standardized way for different software systems to communicate over the internet. They define a set of rules and conventions for exchanging data using HTTP methods such as GET, POST, PUT, and DELETE . RESTful APIs allow clients and servers to interact in a stateless manner, making it easy to build scalable and maintainable applications. By exposing clear endpoints and using structured data formats like JSON, RESTful APIs enable seamless integration between different parts of a system or between different systems altogether.

The Controller Architecture

In our personal tutor service, we implement a clear separation between the components that handle HTTP requests and those that contain the core business logic. This separation is achieved through a two-controller architecture: API Entry Point (ApiController) : Handles HTTP requests, parses incoming data, and formats outgoing responses. Business Logic Controller (TutorController) : Manages the core logic for tutoring sessions, including session management and processing student queries. This approach keeps the API interface focused on HTTP interactions, while the core tutoring logic remains independent and reusable. Laravel makes it easy to define controllers and route HTTP requests to them, helping us maintain this separation of concerns.

The ApiController

The API entry point acts as the gateway for all HTTP requests to our service. Its responsibilities include: Defining and handling API endpoints for different actions (such as creating sessions or sending queries) Parsing incoming request data (for example, extracting JSON payloads) Delegating business logic to the TutorController Formatting responses in a structured way, such as JSON, for clients to consume By following this pattern, the API entry point ensures that HTTP-specific concerns are separated from the core business logic, making the application easier to maintain and extend. Laravel Example: In Laravel, controllers are PHP classes that group related request handling logic. Here’s how the ApiController is implemented: PHPnamespace App\Http\Controllers; use Illuminate\Http\Request; use Illuminate\Http\Response; use App\Http\Controllers\TutorController; class ApiController extends Controller { public function index(Request $request) { $tutorController = new TutorController(); $tutorController->ensureUserSession($request); return response('Welcome to the Personal Tutor Service!', 200) ->header('Content-Type', 'text/plain'); } public function createSession(Request $request) { $tutorController = new TutorController(); $result = $tutorController->createSession($request); return response()->json($result, 200); } public function sendQuery(Request $request) { $tutorController = new TutorController(); $data = $request->json()->all(); $sessionId = $data['session_id'] ?? null; $studentQuery = $data['query'] ?? null; $result = $tutorController->sendQuery($request, $sessionId, $studentQuery); $status = 200; if (isset($result['code'])) { $status = $result['code']; } return response()->json($result, $status); } } In this example, Laravel’s Request object is used to access incoming HTTP data, and the response() helper is used to send responses in the appropriate format.

Join the 1M+ learners on CodeSignal

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

PHP

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use Illuminate\Http\Response;
use App\Http\Controllers\TutorController;

class ApiController extends Controller
{
    public function index(Request $request)
    {
        $tutorController = new TutorController();
        $tutorController->ensureUserSession($request);

        return response('Welcome to the Personal Tutor Service!', 200)
            ->header('Content-Type', 'text/plain');
    }

    public function createSession(Request $request)
    {
        $tutorController = new TutorController();
        $result = $tutorController->createSession($request);

        return response()->json($result, 200);
    }

    public function sendQuery(Request $request)
    {
        $tutorController = new TutorController();
        $data = $request->json()->all();
        $sessionId = $data['session_id'] ?? null;
        $studentQuery = $data['query'] ?? null;

        $result = $tutorController->sendQuery($request, $sessionId, $studentQuery);

        $status = 200;
        if (isset($result['code'])) {
            $status = $result['code'];
        }

        return response()->json($result, $status);
    }
}

PHP

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use App\Services\TutorService;

class TutorController extends Controller
{
    private TutorService $tutorService;

    public function __construct()
    {
        $this->tutorService = new TutorService();
    }
    
    public function ensureUserSession(Request $request): string
    {
        if (!$request->session()->has('student_id')) {
            $request->session()->put('student_id', uniqid('', true));
        }
        return $request->session()->get('student_id');
    }
    
    public function createSession(Request $request): array
    {
        $studentId = $request->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(Request $request, string $sessionId, string $studentQuery): array
    {
        $studentId = $request->session()->get('student_id');
        if (!$studentId) {
            return ['error' => 'Session expired', 'code' => 401];
        }
        
        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];
        }
    }
}

PHP

use Illuminate\Support\Facades\Route;
use App\Http\Controllers\ApiController;

Route::get('/', [ApiController::class, 'index']);
Route::post('/api/create_session', [ApiController::class, 'createSession']);
Route::post('/api/send_query', [ApiController::class, 'sendQuery']);

use Illuminate\Support\Facades\Route;
use App\Http\Controllers\ApiController;

Route::get('/', [ApiController::class, 'index']);
Route::post('/api/create_session', [ApiController::class, 'createSession']);
Route::post('/api/send_query', [ApiController::class, 'sendQuery']);

PHP

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use App\Services\TutorService;

class TutorController extends Controller
{
    private TutorService $tutorService;

    public function __construct()
    {
        $this->tutorService = new TutorService();
    }
    
    public function ensureUserSession(Request $request): string
    {
        if (!$request->session()->has('student_id')) {
            $request->session()->put('student_id', uniqid('', true));
        }
        return $request->session()->get('student_id');
    }
    
    public function createSession(Request $request): array
    {
        $studentId = $request->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(Request $request, string $sessionId, string $studentQuery): array
    {
        $studentId = $request->session()->get('student_id');
        if (!$studentId) {
            return ['error' => 'Session expired', 'code' => 401];
        }
        
        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];
        }
    }
}

PHP

use Illuminate\Support\Facades\Route;
use App\Http\Controllers\ApiController;

Route::get('/', [ApiController::class, 'index']);
Route::post('/api/create_session', [ApiController::class, 'createSession']);
Route::post('/api/send_query', [ApiController::class, 'sendQuery']);

Serving Your Personal Tutor with a RESTful API

Understanding RESTful APIs

The Controller Architecture

The ApiController

Join the 1M+ learners on CodeSignal

The TutorController

Session Management

Error Handling and Response Formatting

API Endpoints

Summary and Next Steps