Wat zijn API Resources?

Question

Accepted Answer

**API Resources** zijn transformatieklassen die bepalen hoe Eloquent-modellen (en collecties) **naar JSON worden geserialiseerd** voor API-responses. Ze stellen je in staat om de API-output nauwkeurig vorm te geven — door te kiezen welke velden je blootstelt, ze te hernoemen, waarden op te maken en gerelateerde gegevens op te nemen — wat de API-representatie ontkoppelt van de databasestructuur.

## Het probleem: ruwe modellen blootstellen

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

## De oplossing: een 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
```

De `toArray()`-methode van de resource definieert exact de JSON-vorm — je bepaalt welke velden verschijnen, geeft ze een andere naam, maakt ze op en voegt gerelateerde resources toe. Gevoelige velden worden eenvoudig niet opgenomen.

## Voorwaardelijke en geneste gegevens

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

## Waarom het belangrijk is

API Resources zijn belangrijk voor het bouwen van goed ontworpen, veilige API's in Laravel — ze geven je nauwkeurige controle over JSON-output, wat belangrijk is voor zowel **beveiliging** als API-ontwerp.

Het meest kritieke voordeel is **het voorkomen van datalekken**: het rechtstreeks retourneren van Eloquent-modellen blootstelt alle kolommen (mogelijk inclusief wachtwoordhashes, interne markeringen of andere gevoelige gegevens — een ernstig veiligheidsprobleem), terwijl API Resources je stellen in staat om expliciet te kiezen welke velden je blootstelt, zodat gevoelige gegevens nooit bij clients terechtkomen.

Buiten beveiliging stellen ze schoon API-ontwerp mogelijk door **de API-representatie ontkoppeld te houden van het databaseschema** — je kunt velden hernoemen, waarden opmaken (datums, booleaanse waarden), geneste/gerelateerde gegevens structureren en velden voorwaardelijk opnemen op basis van machtigingen, allemaal in een speciale transformatieklasse.

Dit houdt het API-contract stabiel en intentioneel in plaats van gekoppeld aan interne tabelstructuur.

Het begrijpen van API Resources — hoe ze JSON-output vorm geven, het veiligheidsvoordeel van expliciete veldcontrole, en functies zoals voorwaardelijke velden en geneste resources — is belangrijk kennis voor het bouwen van professionele Laravel-API's, omdat het blootstellen van ruwe modellen zowel onveilig als slecht ontwerp is.

Aangezien REST/JSON-API's tegenwoordig een primair gebruik van Laravel zijn, en aangezien het controleren van responsievormen (veilig en schoon) een veel voorkomende, belangrijke behoefte is, zijn API Resources een veel gebruikt, waardevol gereedschap dat goed gebouwde, veilige API's onderscheidt van API's die gegevens lekken of hun output strak koppelen aan de database.