API Resources คืออะไร?

Question

Accepted Answer

**API Resources** คือคลาสสำหรับการแปลงข้อมูล (transformation classes) ที่ควบคุมวิธีที่ Eloquent models (และ collections) ถูก **serialize เป็น JSON** สำหรับ response ของ API ช่วยให้คุณกำหนดรูปร่างของ output ที่ API ส่งออกได้อย่างแม่นยำ ทั้งการเลือกว่าจะเปิดเผยฟิลด์ใด เปลี่ยนชื่อฟิลด์ จัดรูปแบบค่า และรวมข้อมูลที่เกี่ยวข้อง โดยแยกการนำเสนอของ API ออกจากโครงสร้างของฐานข้อมูล

## ปัญหา: การเปิดเผย model แบบดิบ

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

## วิธีแก้: ใช้ 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 กำหนดรูปร่างของ JSON อย่างแม่นยำ คุณควบคุมได้ว่าจะให้ฟิลด์ใดปรากฏ เปลี่ยนชื่อและจัดรูปแบบฟิลด์เหล่านั้น และรวม resource ที่เกี่ยวข้องเข้าไป ส่วนฟิลด์ที่เป็นข้อมูลอ่อนไหวก็เพียงแค่ไม่ใส่เข้าไป

## ข้อมูลแบบมีเงื่อนไขและแบบซ้อน

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

## ทำไมจึงสำคัญ

API Resources มีความสำคัญต่อการสร้าง API ที่ออกแบบมาอย่างดีและปลอดภัยใน Laravel เพราะให้การควบคุม output ของ JSON ได้อย่างแม่นยำ ซึ่งสำคัญทั้งในแง่ของ **security** และการออกแบบ API

ประโยชน์ที่สำคัญที่สุดคือการ **ป้องกันข้อมูลรั่วไหล** เพราะการคืน Eloquent models โดยตรงจะเปิดเผยคอลัมน์ทั้งหมด (ซึ่งอาจรวมถึง password hash, internal flags หรือข้อมูลอ่อนไหวอื่น ๆ ซึ่งเป็นช่องโหว่ที่ร้ายแรง) ในขณะที่ API Resources ให้คุณเลือกได้อย่างชัดเจนว่าจะเปิดเผยฟิลด์ใด เพื่อให้มั่นใจว่าข้อมูลอ่อนไหวจะไม่หลุดไปถึงไคลเอนต์

นอกเหนือจากด้าน security แล้ว ยังช่วยให้การออกแบบ API สะอาดขึ้นด้วยการ **แยกการนำเสนอของ API ออกจาก schema ของฐานข้อมูล** คุณสามารถเปลี่ยนชื่อฟิลด์ จัดรูปแบบค่า (วันที่ บูลีน) จัดโครงสร้างข้อมูลที่ซ้อนหรือเกี่ยวข้องกัน และรวมฟิลด์แบบมีเงื่อนไขตามสิทธิ์ ทั้งหมดนี้อยู่ในคลาสแปลงข้อมูลเฉพาะ

สิ่งนี้ทำให้ contract ของ API คงที่และเป็นไปตามที่ตั้งใจ แทนที่จะผูกติดกับโครงสร้างตารางภายใน

การเข้าใจ API Resources ทั้งวิธีที่มันกำหนดรูปร่างของ output JSON ประโยชน์ด้านความปลอดภัยของการควบคุมฟิลด์อย่างชัดเจน และฟีเจอร์อย่าง conditional fields และ nested resources เป็นความรู้ที่สำคัญสำหรับการสร้าง Laravel API ระดับมืออาชีพ เพราะการเปิดเผย model แบบดิบนั้นทั้งไม่ปลอดภัยและเป็นการออกแบบที่ไม่ดี

เนื่องจาก REST/JSON API เป็นการใช้งานหลักของ Laravel ในปัจจุบัน และการควบคุมรูปร่างของ response (อย่างปลอดภัยและสะอาด) เป็นความต้องการที่พบบ่อยและสำคัญ API Resources จึงเป็นเครื่องมือที่ใช้บ่อยและมีคุณค่า ซึ่งแยกแยะ API ที่สร้างมาอย่างดีและปลอดภัยออกจาก API ที่ทำให้ข้อมูลรั่วไหลหรือผูก output เข้ากับฐานข้อมูลอย่างแน่นเกินไป