Was sind API Resources?

Question

Accepted Answer

**API Resources** sind Transformationsklassen, die steuern, wie Eloquent-Modelle (und Sammlungen) **zu JSON für API-Antworten serialisiert** werden. Sie ermöglichen es Ihnen, die API-Ausgabe präzise zu gestalten — indem Sie wählen, welche Felder Sie verfügbar machen, sie umbenennen, Werte formatieren und verwandte Daten einbeziehen — und dabei die API-Darstellung von der Datenbankstruktur entkoppeln.

## Das Problem: rohes Modell verfügbar machen

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

## Die Lösung: eine 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
```

Die `toArray()`-Methode der Resource definiert exakt die JSON-Form — Sie steuern, welche Felder erscheinen, benennen und formatieren sie um, und beziehen verwandte Resources ein. Sensible Felder sind einfach nicht enthalten.

## Bedingte und verschachtelte Daten

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

## Warum es wichtig ist

API Resources sind wichtig für den Aufbau gut gestalteter, sicherer APIs in Laravel — sie geben Ihnen präzise Kontrolle über die JSON-Ausgabe, was sowohl für **Sicherheit** als auch für API-Design wichtig ist.

Der kritischste Vorteil ist die **Verhinderung von Datenlecks**: Das direkte Zurückgeben von Eloquent-Modellen macht alle ihre Spalten verfügbar (möglicherweise einschließlich Password-Hashes, interner Flaggen oder anderer sensibler Daten — eine ernsthafte Sicherheitslücke), während API Resources es Ihnen ermöglichen, explizit zu wählen, welche Felder verfügbar gemacht werden, um sicherzustellen, dass sensible Daten niemals Clients erreichen.

Über Sicherheit hinaus ermöglichen sie ein sauberes API-Design durch **Entkopplung der API-Darstellung vom Datenbankschema** — Sie können Felder umbenennen, Werte formatieren (Daten, Booleans), verschachtelte/verwandte Daten strukturieren und Felder bedingt auf Basis von Berechtigungen einbeziehen, alles in einer dedizierten Transformationsklasse.

Dies hält den API-Vertrag stabil und absichtsvoll, statt ihn an interne Tabellenstruktur gekoppelt zu lassen.

API Resources zu verstehen — wie sie JSON-Ausgabe gestalten, den Sicherheitsvorteil expliziter Feldkontrolle, und Features wie bedingte Felder und verschachtelte Resources — ist wichtiges Wissen für den Aufbau professioneller Laravel APIs, da das Verfügbarmachen von rohen Modellen sowohl unsicher ist als auch schlechtes Design darstellt.

Da REST/JSON APIs heute eine primäre Nutzung von Laravel sind, und da das Kontrollieren der Antwortform (sicher und sauber) ein häufiges, wichtiges Bedürfnis ist, sind API Resources ein häufig verwendetes, wertvolles Werkzeug, das gut gebaute, sichere APIs von solchen unterscheidet, die Daten verlieren oder ihre Ausgabe eng an die Datenbank koppeln.