Apa itu API Resources?

Question

Accepted Answer

**API Resources** adalah kelas transformasi yang mengontrol bagaimana model Eloquent (dan koleksi) **diserialisasi menjadi JSON** untuk respons API. Mereka memungkinkan Anda membentuk keluaran API dengan presisi — memilih field mana yang akan diekspos, mengganti namanya, memformat nilai, dan menyertakan data terkait — memisahkan representasi API dari struktur database.

## Masalahnya: mengekspos 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, ... } 😱
```

## Solusinya: 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
```

Method `toArray()` resource mendefinisikan bentuk JSON dengan tepat — Anda mengontrol field mana yang muncul, mengganti nama dan memformatnya, serta menyertakan resource terkait. Field sensitif sekadar 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 ini penting

API Resources penting untuk membangun API yang dirancang dengan baik dan aman di Laravel — mereka memberikan Anda kontrol presisi atas keluaran JSON, yang penting untuk **keamanan** dan desain API.

Manfaat paling kritis adalah **mencegah kebocoran data**: mengembalikan model Eloquent secara langsung mengekspos semua kolom mereka (berpotensi termasuk hash password, flag internal, atau data sensitif lainnya — kerentanan serius), sedangkan API Resources memungkinkan Anda secara eksplisit memilih field mana yang akan diekspos, memastikan data sensitif tidak pernah sampai ke klien.

Selain keamanan, mereka memungkinkan desain API yang bersih dengan **memisahkan representasi API dari skema database** — Anda dapat mengganti nama field, memformat nilai (tanggal, boolean), menyusun data bersarang/terkait, dan secara bersyarat menyertakan field berdasarkan izin, semuanya dalam kelas transformasi khusus.

Ini menjaga kontrak API tetap stabil dan disengaja daripada terikat pada struktur tabel internal.

Memahami API Resources — bagaimana mereka membentuk keluaran JSON, manfaat keamanan dari kontrol field eksplisit, dan fitur seperti field bersyarat dan resource bersarang — adalah pengetahuan penting untuk membangun API Laravel profesional, karena mengekspos model mentah tidak aman dan merupakan desain yang buruk.

Karena REST/JSON API adalah penggunaan utama Laravel saat ini, dan karena mengontrol bentuk respons (dengan aman dan bersih) adalah kebutuhan umum dan penting, API Resources adalah alat yang sering digunakan dan berharga yang membedakan API yang dibangun dengan baik dan aman dari API yang membocorkan data atau menghubungkan keluaran mereka erat dengan database.