API Resource là gì?

Question

API Resource là gì?

Accepted Answer

**API Resource** là các class biến đổi kiểm soát cách các model Eloquent (và collection) được **serialize thành JSON** cho các response API. Chúng cho phép bạn định hình output API một cách chính xác — chọn field nào để expose, đổi tên chúng, định dạng giá trị, và bao gồm dữ liệu liên quan — tách biểu diễn API khỏi cấu trúc database.

## Vấn đề: expose model thô

```php
// ❌ trả về một model trực tiếp expose TẤT CẢ cột (có thể gồm cả cột nhạy cảm)
return User::find($id);   // { id, name, email, password_hash, internal_notes, ... } 😱
```

## Giải pháp: một 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 và các field nội bộ được CỐ Ý BỎ QUA
            'joined' => $this->created_at->toDateString(),   // định dạng một giá trị
            'is_admin' => (bool) $this->is_admin,
            // bao gồm dữ liệu liên quan (load có điều kiện)
            'posts' => PostResource::collection($this->whenLoaded('posts')),
        ];
    }
}
```

```php
// dùng nó trong một controller
return new UserResource($user);                  // một model đơn lẻ
return UserResource::collection(User::all());     // một collection
```

Hàm `toArray()` của resource định nghĩa chính xác hình dạng JSON — bạn kiểm soát field nào xuất hiện, đổi tên và định dạng chúng, và bao gồm các resource liên quan. Các field nhạy cảm đơn giản là không được bao gồm.

## Dữ liệu có điều kiện và lồng nhau

```php
return [
    'id' => $this->id,
    'secret' => $this->when($request->user()->isAdmin(), $this->secret),  // field có điều kiện
    'posts' => PostResource::collection($this->whenLoaded('posts')),       // chỉ nếu đã eager-load
];
```

## Tại sao điều này quan trọng

API Resource quan trọng để xây dựng các API được thiết kế tốt, an toàn trong Laravel — chúng cho bạn quyền kiểm soát chính xác output JSON, điều quan trọng cho cả **bảo mật** lẫn thiết kế API.

Lợi ích then chốt nhất là **ngăn rò rỉ dữ liệu**: trả về model Eloquent trực tiếp expose tất cả cột của chúng (có thể gồm cả password hash, cờ nội bộ, hoặc dữ liệu nhạy cảm khác — một lỗ hổng nghiêm trọng), trong khi API Resource cho phép bạn chọn rõ ràng field nào để expose, đảm bảo dữ liệu nhạy cảm không bao giờ đến tay client.

Ngoài bảo mật, chúng cho phép thiết kế API sạch sẽ bằng cách **tách biểu diễn API khỏi schema database** — bạn có thể đổi tên field, định dạng giá trị (date, boolean), cấu trúc dữ liệu lồng nhau/liên quan, và bao gồm field có điều kiện dựa trên quyền, tất cả trong một class biến đổi chuyên dụng.

Điều này giữ hợp đồng API ổn định và có chủ đích thay vì gắn chặt với cấu trúc bảng nội bộ.

Hiểu API Resource — cách chúng định hình output JSON, lợi ích bảo mật của việc kiểm soát field rõ ràng, và các tính năng như field có điều kiện và resource lồng nhau — là kiến thức quan trọng để xây dựng các API Laravel chuyên nghiệp, vì expose model thô vừa không an toàn vừa thiết kế kém.

Khi REST/JSON API là một mục đích chính của Laravel ngày nay, và khi kiểm soát hình dạng response (an toàn và sạch sẽ) là một nhu cầu phổ biến, quan trọng, API Resource là một công cụ được dùng thường xuyên, có giá trị phân biệt các API được xây dựng tốt, an toàn với những API rò rỉ dữ liệu hoặc gắn chặt output của chúng với database.