Apakah itu API Resource?

Question

Accepted Answer

**API Resource** ialah kelas transformasi yang mengawal cara model Eloquent (dan collection) **diserikan ke JSON** untuk respons API. Ia membolehkan anda membentuk output API dengan tepat — memilih medan mana untuk didedahkan, menamakan semula medan, memformat nilai, dan menyertakan data berkaitan — memisahkan perwakilan API daripada struktur pangkalan data.

## Masalah: mendedahkan model mentah

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

## Penyelesaian: sebuah 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
```

`toArray()` resource mentakrifkan dengan tepat bentuk JSON — anda mengawal medan mana yang muncul, menamakan semula dan memformatnya, serta menyertakan resource berkaitan. Medan sensitif hanya tidak disertakan.

## Data bersyarat dan bersarang

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

## Mengapa ia penting

API Resource adalah penting untuk membina API yang direka bentuk baik dan selamat dalam Laravel — ia memberi anda kawalan tepat ke atas output JSON, yang penting untuk kedua-dua **keselamatan** dan reka bentuk API.

Manfaat paling kritikal ialah **mencegah kebocoran data**: memulangkan model Eloquent secara langsung mendedahkan semua lajurnya (berkemungkinan termasuk hash kata laluan, bendera dalaman, atau data sensitif lain — kerentanan serius), sedangkan API Resource membolehkan anda secara eksplisit memilih medan mana untuk didedahkan, memastikan data sensitif tidak sekali-kali sampai kepada klien.

Di luar keselamatan, ia membolehkan reka bentuk API yang bersih dengan **memisahkan perwakilan API daripada skema pangkalan data** — anda boleh menamakan semula medan, memformat nilai (tarikh, boolean), menstruktur data bersarang/berkaitan, dan menyertakan medan secara bersyarat berdasarkan kebenaran, semuanya dalam kelas transformasi yang khusus.

Ini mengekalkan kontrak API yang stabil dan disengajakan dan bukannya terikat kepada struktur jadual dalaman.

Memahami API Resource — cara ia membentuk output JSON, manfaat keselamatan kawalan medan yang eksplisit, dan ciri seperti medan bersyarat serta resource bersarang — adalah pengetahuan penting untuk membina API Laravel yang profesional, kerana mendedahkan model mentah adalah kedua-dua tidak selamat dan reka bentuk yang lemah.

Memandangkan API REST/JSON adalah kegunaan utama Laravel hari ini, dan memandangkan mengawal bentuk respons (dengan selamat dan bersih) adalah keperluan lazim dan penting, API Resource adalah alat berharga yang kerap digunakan yang membezakan API yang dibina baik dan selamat daripada yang membocorkan data atau mengikat output mereka secara ketat kepada pangkalan data.