Cosa sono le API Resources?

Question

Accepted Answer

**API Resources** sono classi di trasformazione che controllano come i modelli Eloquent (e le collezioni) vengono **serializzati a JSON** per le risposte API. Ti permettono di modellare l'output dell'API con precisione — scegliendo quali campi esporre, rinominandoli, formattando i valori e includendo i dati correlati — disaccoppiando la rappresentazione API dalla struttura del database.

## Il problema: esporre modelli grezzi

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

## La soluzione: una 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
```

Il metodo `toArray()` della risorsa definisce esattamente la forma JSON — tu controlli quali campi compaiono, li rinomini e li formatti, e includi le risorse correlate. I campi sensibili semplicemente non vengono inclusi.

## Dati condizionali e annidati

```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
];
```

## Perché è importante

Le API Resources sono importanti per costruire API ben progettate e sicure in Laravel — ti danno il controllo preciso sull'output JSON, che è fondamentale sia per la **sicurezza** che per il design dell'API.

Il vantaggio più critico è **prevenire le fughe di dati**: restituire modelli Eloquent direttamente espone tutte le loro colonne (potenzialmente includendo hash di password, flag interni o altri dati sensibili — una vulnerabilità seria), mentre le API Resources ti permettono di scegliere esplicitamente quali campi esporre, assicurando che i dati sensibili non raggiungano mai i client.

Inoltre, consentono un design API pulito **disaccoppiando la rappresentazione API dallo schema del database** — puoi rinominare i campi, formattare i valori (date, booleani), strutturare dati annidati/correlati e includere condizionatamente i campi in base ai permessi, il tutto in una classe di trasformazione dedicata.

Questo mantiene il contratto API stabile e intenzionale piuttosto che accoppiato alla struttura interna della tabella.

Comprendere le API Resources — come modellano l'output JSON, il vantaggio di sicurezza del controllo esplicito dei campi e funzionalità come i campi condizionali e le risorse annidate — è una conoscenza importante per costruire API Laravel professionali, poiché esporre modelli grezzi è sia insicuro che un cattivo design.

Poiché le API REST/JSON sono un uso primario di Laravel oggi, e poiché controllare la forma della risposta (in modo sicuro e pulito) è un'esigenza comune e importante, le API Resources sono uno strumento usato di frequente e prezioso che distingue le API ben costruite e sicure da quelle che perdono dati o accoppiano strettamente il loro output al database.