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.

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.

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:

1. API Entry Point (ApiController): Handles HTTP requests, parses incoming data, and formats outgoing responses.
2. 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 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:

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);
    }
}

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.