Pernah nggak kamu bikin API, terus frontend-developer teman se-tim komplain karena format response-nya berubah-ubah? Kadang ada key data, kadang enggak. Kadang ada meta, kadang hilang. API Resource Collection di Laravel hadir sebagai solusi untuk masalah klasik ini. Di artikel ke-40 dari seri "50 Artikel Belajar Laravel" ini, kita akan kupas tuntas bagaimana cara membuat format response API yang konsisten, profesional, dan mudah di-maintain — tanpa ribet.
API Resource adalah kelas transformasi di Laravel yang mengubah model Eloquent (atau data apapun) menjadi format JSON yang sudah kamu definisikan sendiri. API Resource Collection adalah versi koleksi dari Resource — digunakan saat kamu ingin mengembalikan banyak data sekaligus dengan struktur yang sama.
🎁 Analogi: Kamu adalah Manajer Gudang
Bayangkan kamu adalah manajer gudang toko online. Setiap kali ada pesanan masuk, kamu harus menyiapkan paket dan mengemas produk. Masalahnya: tiap karyawan punya cara bungkus yang berbeda-beda. Ada yang pakai kardus besar, ada yang pakai plastik kecil. Pelanggan jadi bingung.
Nah, API Resource ibarat SOP pengemasan standar yang kamu buat. Semua karyawan wajib pakai template yang sama. Produk apapun — baju, sepatu, elektronik — dikemas dengan format yang seragam dan konsisten. Frontend developer yang "pelanggan" kamu pun jadi bahagia karena response-nya bisa diprediksi!
🛠 Cara Membuat dan Menggunakan API Resource Collection
Laravel menyediakan artisan command yang super mudah untuk generate Resource. Berikut langkah-langkah lengkapnya:
Generate API Resource dengan Artisan
Jalankan perintah berikut di terminal untuk membuat Resource baru.
# Membuat single resource php artisan make:resource UserResource # Membuat resource collection php artisan make:resource UserCollection # Atau sekaligus keduanya dengan flag --collection php artisan make:resource User --collection
Edit File UserResource.php
File akan berada di app/Http/Resources/UserResource.php. Isi method toArray() dengan field yang ingin kamu ekspos.
<?php
namespace App\Http\Resources;
use Illuminate\Http\Resources\Json\JsonResource;
class UserResource extends JsonResource
{
/**
* Ubah resource ke dalam format array.
*/
public function toArray($request): array
{
return [
'id' => $this->id,
'name' => $this->name,
'email' => $this->email,
'role' => $this->role,
'created_at' => $this->created_at->toDateString(),
// 'password' TIDAK dimasukkan — aman!
];
}
}
Gunakan di Controller
Panggil Resource dari controller, baik untuk single item maupun collection.
<?php
namespace App\Http\Controllers\Api;
use App\Http\Resources\UserResource;
use App\Models\User;
class UserController extends Controller
{
// Mengembalikan SINGLE resource
public function show($id)
{
$user = User::findOrFail($id);
return new UserResource($user);
}
// Mengembalikan COLLECTION (banyak data)
public function index()
{
$users = User::paginate(10);
return UserResource::collection($users);
}
}
UserResource::collection($users) dengan data hasil paginate(), Laravel secara otomatis menambahkan key links dan meta berisi informasi halaman. Keren kan? Tanpa kerja ekstra!🚀 Kustomisasi API Resource Collection: Tambahkan Meta & Wrapper
Kadang kamu butuh response yang lebih kaya — misalnya menambahkan pesan status, versi API, atau data agregat di luar daftar utama. Inilah saatnya kamu membuat Custom Collection Resource.
Buat Custom UserCollection.php
Tambahkan method with() untuk menyisipkan data tambahan di luar array utama.
<?php
namespace App\Http\Resources;
use Illuminate\Http\Resources\Json\ResourceCollection;
class UserCollection extends ResourceCollection
{
/**
* Kustomisasi struktur response collection
*/
public function toArray($request): array
{
return [
'data' => $this->collection,
];
}
/**
* Tambahkan data di luar wrapper 'data'
*/
public function with($request): array
{
return [
'meta' => [
'api_version' => '1.0.0',
'status' => 'success',
'total_users' => $this->collection->count(),
],
];
}
}
Conditional Fields — Data Kondisional
Tampilkan field hanya dalam kondisi tertentu, misalnya hanya untuk admin.
public function toArray($request): array
{
return [
'id' => $this->id,
'name' => $this->name,
'email' => $this->email,
// Hanya muncul jika user adalah admin
'admin_notes' => $this->when(
$request->user()?->isAdmin(),
$this->admin_notes
),
// Hanya muncul jika relasi sudah di-load
'posts' => PostResource::collection(
$this->whenLoaded('posts')
),
];
}
posts), pastikan kamu sudah melakukan eager loading dengan with('posts') di controller. Gunakan $this->whenLoaded() agar relasi hanya dimuat saat dibutuhkan, mencegah N+1 query problem.📊 Perbandingan: Resource vs Collection vs Response Biasa
| Metode | Kegunaan | Keamanan | Fleksibilitas |
|---|---|---|---|
| Return Model Langsung | Prototype cepat | ❌ Rendah | ❌ Tidak fleksibel |
| JSON Resource | Single item | ✅ Tinggi | ✅ Sangat fleksibel |
| API Resource Collection | Banyak item + meta | ✅ Tinggi | ✅ Paling fleksibel |
| response()->json() | Custom sederhana | ⚠️ Manual | ⚠️ Terbatas |
PostResource bisa memanggil UserResource untuk data author. Ini membuat API kamu sangat modular dan mudah di-maintain jangka panjang.{
"data": [
{
"id": 1,
"name": "Budi Santoso",
"email": "budi@example.com",
"role": "admin",
"created_at": "2025-01-15"
},
{
"id": 2,
"name": "Siti Rahayu",
"email": "siti@example.com",
"role": "user",
"created_at": "2025-02-03"
}
],
"meta": {
"api_version": "1.0.0",
"status": "success",
"total_users": 2,
"current_page": 1,
"last_page": 5
}
}
No comments:
Post a Comment