เบื้องหลัง API Artisan: สร้าง Laravel API ที่นักพัฒนาอยากใช้จริง

นักพัฒนามือใหม่จำนวนมากเปิด editor แล้วเริ่มเขียน route ทันที แต่ช่างฝีมือที่ดีจะร่างแบบก่อนลงมือ ก่อนเขียนโค้ด ให้ถามตัวเองสามข้อ: API นี้มีไว้เพื่ออะไร, resource อะไรบ้างที่จะเปิดให้เข้าถึง และใครคือผู้ใช้งานปลายทาง (mobile app, SPA หรือระบบภายนอก)

เมื่อตอบคำถามเหล่านี้ได้แล้ว ให้ออกแบบ endpoint ตามหลัก RESTful คือยึด resource เป็นหลักและใช้ HTTP method สื่อความหมายของการกระทำ เช่น GET /api/users สำหรับดึงรายการ และ POST /api/users สำหรับสร้างใหม่ แทนที่จะตั้งชื่อ endpoint แบบ /api/getAllUsers ซึ่งไม่ตรงตามแบบแผนที่นักพัฒนาส่วนใหญ่คุ้นเคย

Laravel มีคำสั่งสร้าง controller สำหรับ API โดยเฉพาะ ซึ่งจะมาพร้อมเมธอดมาตรฐานครบทั้ง 5 ตัวสำหรับ CRUD โดยไม่มีเมธอดสำหรับแสดงฟอร์ม (เพราะ API ไม่ต้องการ view)

// สร้าง controller แบบ API (ไม่มี create/edit form)
php artisan make:controller UserController --api

คำสั่งนี้จะสร้างเมธอด index, store, show, update, destroy ให้พร้อมใช้ จากนั้นคุณแค่เติม logic เข้าไป โดยให้แต่ละเมธอดทำหน้าที่เดียวให้ชัดเจน ไม่ปนกัน

public function index() {
    return UserResource::collection(User::paginate(10));
}

public function show(User $user) {
    return new UserResource($user);
}

public function store(StoreUserRequest $request) {
    $user = User::create($request->validated());
    return new UserResource($user);
}

ปัญหาคลาสสิกของมือใหม่คือการ return $user; ตรง ๆ จาก Eloquent ซึ่งจะส่งทุกคอลัมน์ในตาราง รวมถึง password hash หรือ token ที่ไม่ควรหลุดออกไปด้วย API Resource คือชั้นที่ทำหน้าที่ "คัดและจัดรูป" ข้อมูลก่อนส่งออกไปเป็น JSON

php artisan make:resource UserResource

public function toArray($request) {
    return [
        'id' => $this->id,
        'name' => $this->name,
        'email' => $this->email,
        'joined_at' => $this->created_at->format('Y-m-d'),
    ];
}

ข้อดีคือเมื่อโครงสร้างฐานข้อมูลเปลี่ยน คุณแก้แค่ที่เดียวในไฟล์ Resource โดยที่ฝั่ง client ไม่รู้สึกถึงผลกระทบเลย

อย่าไว้ใจข้อมูลที่ส่งเข้ามาจาก client เด็ดขาด ไม่ว่าจะเป็นแอปมือถือของทีมคุณเองก็ตาม Laravel แนะนำให้แยก logic การตรวจสอบข้อมูลออกจาก controller ไปไว้ในคลาส Form Request โดยเฉพาะ เพื่อให้ controller อ่านง่ายและ validation rule นำกลับมาใช้ซ้ำได้

php artisan make:request StoreUserRequest

public function rules() {
    return [
        'name'  => 'required|string|max:255',
        'email' => 'required|email|unique:users,email',
    ];
}

สำหรับ API ที่ให้บริการ SPA หรือแอปมือถือ Laravel Sanctum คือตัวเลือกที่เบาและตั้งค่าง่ายกว่า OAuth เต็มรูปแบบ เหมาะกับโปรเจกต์ส่วนใหญ่ที่ไม่ได้ต้องการระบบสิทธิ์ซับซ้อนระดับองค์กร

composer require laravel/sanctum

Route::middleware(['auth:sanctum', 'throttle:60,1'])->group(function () {
    Route::get('/profile', [ProfileController::class, 'show']);
});

การห่อ route ไว้ใน middleware group แบบนี้ ทำให้คุณจัดการ authentication และ rate limiting ของหลาย endpoint พร้อมกันได้จากจุดเดียว ไม่ต้องเขียนซ้ำในทุกเมธอด

API ที่ตอบกลับข้อมูลทั้งตารางในครั้งเดียวคือระเบิดเวลา เพราะเมื่อข้อมูลในฐานข้อมูลโตขึ้น response time จะยิ่งช้าลงเรื่อย ๆ ใช้ paginate() เพื่อจำกัดจำนวนต่อหน้าเสมอ

// ดึง user พร้อม posts ในคำสั่งเดียว แทนการ query วนลูป
$users = User::with('posts')->paginate(10);

การเรียก with('posts') คือ eager loading ที่ช่วยแก้ปัญหา N+1 query ซึ่งเป็นสาเหตุอันดับต้น ๆ ที่ทำให้ API ของมือใหม่ช้าโดยไม่รู้ตัว เพราะถ้าไม่ใส่ Laravel จะยิง query แยกไปดึง posts ของ user แต่ละคนทีละแถว

ฝั่ง client จะเขียนโค้ดจัดการ error ได้ง่ายขึ้นมาก ถ้า API ของคุณตอบกลับ error format เดียวกันทุกครั้ง ไม่ใช่บางจุด throw exception เป็น HTML บางจุดเป็น JSON ปนกัน Laravel มีระบบ exception handler กลางที่ช่วยควบคุมเรื่องนี้ได้ในจุดเดียว

ส่วนเรื่อง CORS หากต้องเปิดให้ frontend จากโดเมนอื่นเรียก API ได้ ให้ตั้งค่าผ่านไฟล์ config/cors.php โดยควรระบุโดเมนที่อนุญาตให้ชัดเจน แทนที่จะเปิดกว้างด้วย '*' ในระบบที่ใช้งานจริง เพราะนั่นเท่ากับเปิดให้เว็บไซต์ใดก็ได้เรียก API ของคุณ

วันหนึ่งคุณจะต้องเปลี่ยนโครงสร้าง response แน่นอน ไม่ว่าจะเพิ่มฟิลด์หรือลบฟิลด์ที่ไม่ใช้แล้ว การมี version ใน path ตั้งแต่เริ่มต้น ช่วยให้คุณปล่อยเวอร์ชันใหม่ได้โดยไม่ทำให้แอปเวอร์ชันเก่าที่ยังเรียก API อยู่พังกะทันหัน

Route::prefix('v1')->group(function () {
    Route::get('/users', [UserController::class, 'index']);
});

Laravel มีเครื่องมือทดสอบ API ในตัวที่ใช้งานง่ายมาก แค่ยิง request จำลองแล้วตรวจสอบ response ที่ได้ การมีเทสต์เพียงไม่กี่เคสสำหรับ endpoint สำคัญ ช่วยให้คุณกล้า refactor โค้ดในอนาคตโดยไม่ต้องนั่งทดสอบมือทุกครั้ง

public function test_user_can_register() {
    $response = $this->postJson('/api/register', [
        'name'  => 'CyberMan',
        'email' => 'dev@example.com',
    ]);

    $response->assertStatus(201);
}

API ที่ไม่มีเอกสาร คือ API ที่ทีมอื่นกลัวจะใช้ แพ็กเกจอย่าง l5-swagger ช่วยให้คุณเขียนคอมเมนต์รูปแบบ OpenAPI ไว้เหนือแต่ละเมธอด แล้วระบบจะ generate หน้าเอกสารแบบ interactive ให้อัตโนมัติ ทำให้นักพัฒนาฝั่งอื่นทดลองยิง request ได้จากเบราว์เซอร์โดยไม่ต้องถามคุณซ้ำ ๆ