Qu'est-ce que les API Resources ?

Question

Accepted Answer

**API Resources** sont des classes de transformation qui contrôlent comment les modèles Eloquent (et les collections) sont **sérialisés en JSON** pour les réponses API. Elles vous permettent de façonner précisément la sortie API — en choisissant les champs à exposer, en les renommant, en formatant les valeurs et en incluant les données liées — en découplant la représentation API de la structure de la base de données.

## Le problème : exposer les modèles bruts

```php
// ❌ returning a model directly exposes ALL columns (maybe including sensitive ones)
return User::find($id);   // { id, name, email, password_hash, internal_notes, ... } 😱
```

## La solution : une API Resource

```php
<?php
// php artisan make:resource UserResource
class UserResource extends JsonResource {
    public function toArray($request): array {
        return [
            'id' => $this->id,
            'name' => $this->name,
            'email' => $this->email,
            // password and internal fields deliberately OMITTED
            'joined' => $this->created_at->toDateString(),   // format a value
            'is_admin' => (bool) $this->is_admin,
            // include related data (conditionally loaded)
            'posts' => PostResource::collection($this->whenLoaded('posts')),
        ];
    }
}
```

```php
// use it in a controller
return new UserResource($user);                  // a single model
return UserResource::collection(User::all());     // a collection
```

La méthode `toArray()` de la resource définit exactement la structure JSON — vous contrôlez quels champs apparaissent, les renommez et les formatez, et incluez les resources liées. Les champs sensibles ne sont simplement pas inclus.

## Données conditionnelles et imbriquées

```php
return [
    'id' => $this->id,
    'secret' => $this->when($request->user()->isAdmin(), $this->secret),  // conditional field
    'posts' => PostResource::collection($this->whenLoaded('posts')),       // only if eager-loaded
];
```

## Pourquoi c'est important

Les API Resources sont importantes pour construire des API bien conçues et sécurisées dans Laravel — elles vous donnent un contrôle précis sur la sortie JSON, ce qui compte pour la **sécurité** et la conception d'API.

Le bénéfice le plus critique est **la prévention des fuites de données** : retourner directement les modèles Eloquent expose toutes leurs colonnes (potentiellement incluant des hash de mots de passe, des drapeaux internes ou d'autres données sensibles — une vulnérabilité grave), tandis que les API Resources vous permettent de choisir explicitement quels champs exposer, en garantissant que les données sensibles ne atteignent jamais les clients.

Au-delà de la sécurité, elles permettent une conception d'API propre en **découplant la représentation API du schéma de base de données** — vous pouvez renommer les champs, formater les valeurs (dates, booléens), structurer les données imbriquées/liées et inclure conditionnellement les champs en fonction des permissions, tout cela dans une classe de transformation dédiée.

Cela maintient le contrat API stable et intentionnel plutôt que couplé à la structure interne de la table.

Comprendre les API Resources — comment elles façonnent la sortie JSON, le bénéfice de sécurité du contrôle explicite des champs et des fonctionnalités comme les champs conditionnels et les resources imbriquées — est une connaissance importante pour construire des APIs Laravel professionnelles, car exposer des modèles bruts est à la fois non sécurisé et une mauvaise conception.

Comme les APIs REST/JSON sont un usage principal de Laravel aujourd'hui, et comme le contrôle de la forme de la réponse (de manière sûre et propre) est un besoin commun et important, les API Resources sont un outil fréquemment utilisé et précieux qui distingue les APIs bien construites et sécurisées de celles qui fuient des données ou couplent étroitement leur sortie à la base de données.