Module 16 – API REST avec Laravel

Niveau 4 – Laravel avancé (PRO)

Objectifs

Au programme :

Concevoir une API REST avec Laravel (routes api.php, contrôleurs dédiés)
Utiliser les API Resources pour formater les réponses JSON de façon cohérente
Sécuriser l’API avec Laravel Sanctum (tokens pour SPA ou mobile)
Mettre en place versioning et pagination pour une API professionnelle
Réaliser un projet API complète (CRUD, auth, resources, tests)

Théorie

Routes API (routes/api.php)

Les routes dans routes/api.php sont préfixées par /api et ont le middleware api (pas de session, pas de CSRF ; attente de JSON). Idéal pour une API consommée par un front (Vue, React, mobile).

use App\Http\Controllers\Api\ArticleController;

Route::apiResource('articles', ArticleController::class);
// GET    /api/articles      -> index
// GET    /api/articles/{id} -> show
// POST   /api/articles      -> store
// PUT    /api/articles/{id} -> update
// DELETE /api/articles/{id} -> destroy

Versioning : préfixer par un numéro de version pour ne pas casser les clients existants.

Route::prefix('v1')->group(function () {
    Route::apiResource('articles', ArticleController::class);
});
// /api/v1/articles

Réponses JSON cohérentes

Réponse simple :

return response()->json(['data' => $articles]);

Code HTTP :

return response()->json(['message' => 'Created'], 201);
return response()->json(['error' => 'Not found'], 404);

API Resources : classes qui transforment un modèle (ou une collection) en tableau JSON structuré. On contrôle les champs exposés, les relations, les métadonnées.

Créer une resource :

php artisan make:resource ArticleResource
php artisan make:resource ArticleCollection  # pour les listes

ArticleResource.php :

namespace App\Http\Resources;

use Illuminate\Http\Request;
use Illuminate\Http\Resources\Json\JsonResource;

class ArticleResource extends JsonResource
{
    public function toArray(Request $request): array
    {
        return [
            'id'         => $this->id,
            'title'      => $this->title,
            'body'       => $this->body,
            'user'       => new UserResource($this->whenLoaded('user')),
            'created_at' => $this->created_at->toIso8601String(),
        ];
    }
}

Dans le contrôleur :

return new ArticleResource($article);
return ArticleResource::collection($articles);  // liste

Pagination : Laravel pagine et ajoute meta et links automatiquement.

return ArticleResource::collection(Article::paginate(15));

Authentification API : Laravel Sanctum

Sanctum permet :

Tokens pour des clients sans navigateur (mobile, autre service) : l’utilisateur se connecte une fois, reçoit un token à envoyer dans Authorization: Bearer <token>.
Authentification SPA : si l’API est consommée par une SPA sur le même domaine, on peut utiliser les cookies de session (sanctum comme garde).

Installation : fourni avec Laravel ; config dans config/sanctum.php.

Créer un token (ex. après login) :

$user = User::where('email', $request->email)->first();
if (!$user || !Hash::check($request->password, $user->password)) {
    return response()->json(['message' => 'Invalid credentials'], 401);
}
$token = $user->createToken('app-name')->plainTextToken;
return response()->json(['token' => $token, 'user' => new UserResource($user)]);

Protéger les routes API : middleware auth:sanctum.

Route::middleware('auth:sanctum')->group(function () {
    Route::apiResource('articles', ArticleController::class);
});

Le client envoie ensuite : Authorization: Bearer <token>.

Révoquer un token : $request->user()->currentAccessToken()->delete(); (logout).

Pagination

Pour les listes, toujours paginer pour éviter de renvoyer des milliers de lignes.

$articles = Article::with('user')->paginate(15);
return ArticleResource::collection($articles);

Réponse typique : data (page courante), meta (current_page, total, per_page), links (prev, next, etc.).

Gestion des erreurs et validation

Validation : en API, $request->validate() renvoie automatiquement du JSON (422) avec les erreurs par champ.
404 : abort(404) ou response()->json([], 404).
Exception handler : personnaliser app/Exceptions/Handler.php pour renvoyer un format JSON cohérent en cas d’exception (message, code).

Exemple de contrôleur API

namespace App\Http\Controllers\Api;

use App\Http\Controllers\Controller;
use App\Http\Resources\ArticleResource;
use App\Models\Article;
use Illuminate\Http\Request;

class ArticleController extends Controller
{
    public function index()
    {
        return ArticleResource::collection(Article::with('user')->paginate(15));
    }

    public function show(Article $article)
    {
        return new ArticleResource($article->load('user'));
    }

    public function store(Request $request)
    {
        $validated = $request->validate([...]);
        $article = Article::create($validated);
        return (new ArticleResource($article))->response()->setStatusCode(201);
    }

    public function update(Request $request, Article $article)
    {
        $article->update($request->validate([...]));
        return new ArticleResource($article);
    }

    public function destroy(Article $article)
    {
        $article->delete();
        return response()->json(null, 204);
    }
}

En pratique

Toujours utiliser des API Resources pour un format de réponse stable et documentable.
Pagination sur les listes (index).
Sanctum pour l’auth API (tokens ou session SPA selon le cas).
Versioning (ex. /api/v1/) pour faire évoluer l’API sans casser les clients.
Codes HTTP cohérents : 200, 201, 204, 400, 401, 403, 404, 422.

Quiz – Module 16

Q1. Quelle est la différence entre les routes web et api dans Laravel ?
Q2. À quoi servent les API Resources ?
Q3. Comment protéger une route API pour qu’elle ne soit accessible qu’avec un token ?
Q4. Comment paginer une liste dans une réponse API ?
Q5. Quel package Laravel utilise-t-on pour l’authentification par token API ?

Réponses

R1. Les routes web ont session, CSRF, cookies ; les routes api sont préfixées par /api, sans session, et renvoient du JSON (middleware api).

R2. À formater les modèles (ou collections) en structure JSON cohérente (champs choisis, relations conditionnelles, métadonnées) pour les réponses API.

R3. Avec le middleware auth:sanctum ; le client envoie le token dans l’en-tête Authorization: Bearer <token>.

R4. En utilisant paginate() sur le query builder puis en renvoyant une Resource::collection() sur le résultat ; Laravel ajoute meta et links.

R5. Laravel Sanctum (tokens pour API ; peut aussi gérer l’auth SPA sur le même domaine).

Projet : API complète

Cahier des charges :

Une ressource (ex. articles ou produits) en CRUD complet via API (index, show, store, update, destroy).
Sanctum : login (email/password) renvoie un token ; les routes de modification (store, update, destroy) protégées par auth:sanctum.
API Resources pour toutes les réponses concernant la ressource.
Pagination sur l’index.
Validation via Form Request ou $request->validate().
Versioning : préfixe /api/v1/.
(Bonus) Tests feature pour au moins 2 routes (ex. index et store).

Critères de réussite : Réponses JSON cohérentes, codes HTTP corrects, documentation ou collection Postman/Insomnia pour tester.

Suite

Module 17 – Tests (tests unitaires, feature, PHPUnit/Pest, mocking, examen écriture de tests).

Objectifs​

Théorie​

Routes API (routes/api.php)​

Réponses JSON cohérentes​

Authentification API : Laravel Sanctum​

Pagination​

Gestion des erreurs et validation​

Exemple de contrôleur API​

En pratique​

Quiz – Module 16​

Projet : API complète​

Suite​