What are API Resources?

Question

Accepted Answer

**API Resources** are transformation classes that control how Eloquent models (and collections) are **serialized to JSON** for API responses. They let you shape the API output precisely — choosing which fields to expose, renaming them, formatting values, and including related data — decoupling the API representation from the database structure.

## The problem: exposing raw models

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

## The solution: an 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
```

The resource's `toArray()` defines exactly the JSON shape — you control which fields appear, rename and format them, and include related resources. Sensitive fields are simply not included.

## Conditional and nested data

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

## Why it matters

API Resources are important for building well-designed, secure APIs in Laravel — they give you precise control over JSON output, which matters for both **security** and API design.

The most critical benefit is **preventing data leaks**: returning Eloquent models directly exposes all their columns (potentially including password hashes, internal flags, or other sensitive data — a serious vulnerability), whereas API Resources let you explicitly choose which fields to expose, ensuring sensitive data never reaches clients.

Beyond security, they enable clean API design by **decoupling the API representation from the database schema** — you can rename fields, format values (dates, booleans), structure nested/related data, and conditionally include fields based on permissions, all in a dedicated transformation class.

This keeps the API contract stable and intentional rather than coupled to internal table structure.

Understanding API Resources — how they shape JSON output, the security benefit of explicit field control, and features like conditional fields and nested resources — is important knowledge for building professional Laravel APIs, since exposing raw models is both insecure and poor design.

As REST/JSON APIs are a primary use of Laravel today, and as controlling response shape (safely and cleanly) is a common, important need, API Resources are a frequently-used, valuable tool that distinguishes well-built, secure APIs from ones that leak data or tightly couple their output to the database.