Endpoint คืออะไร? การออกแบบ Endpoint ที่ดี

หลังจากที่เราได้เรียนรู้เรื่อง HTTP Methods ในบทที่แล้ว เราจะมาทำความเข้าใจกับ "Endpoint" ซึ่งเป็นส่วนสำคัญอีกส่วนหนึ่งในการสร้าง API ครับ

Endpoint คืออะไร?

Endpoint คือ จุดเชื่อมต่อ (entry point) ที่ Client ใช้เพื่อเข้าถึงทรัพยากรหรือฟังก์ชันการทำงานของ API คิดง่ายๆ ว่า Endpoint คือ "ที่อยู่" ของ API ที่ Client สามารถส่ง Request ไปเพื่อขอข้อมูลหรือสั่งให้ API ทำงานบางอย่าง

ยกตัวอย่าง:

`/users` - Endpoint สำหรับจัดการข้อมูลผู้ใช้ทั้งหมด
`/users/{id}` - Endpoint สำหรับจัดการข้อมูลผู้ใช้เฉพาะคน (โดย `{id}` คือ ID ของผู้ใช้)
`/products` - Endpoint สำหรับจัดการข้อมูลสินค้าทั้งหมด
`/products/{product_id}` - Endpoint สำหรับจัดการข้อมูลสินค้าเฉพาะชิ้น (โดย `{product_id}` คือ ID ของสินค้า)

จากตัวอย่างข้างต้น `/users` และ `/products` คือ Endpoint ที่ Client สามารถส่ง Request ไปเพื่อดึงข้อมูลผู้ใช้หรือสินค้าทั้งหมดได้ ส่วน `/users/{id}` และ `/products/{product_id}` คือ Endpoint ที่ Client สามารถใช้เพื่อดึงข้อมูล แก้ไข หรือลบข้อมูลผู้ใช้หรือสินค้าเฉพาะคนได้

หลักการออกแบบ Endpoint ที่ดี

การออกแบบ Endpoint ที่ดีมีความสำคัญอย่างมากต่อความสามารถในการใช้งาน (usability) และความง่ายในการบำรุงรักษา (maintainability) ของ API ต่อไปนี้เป็นหลักการสำคัญที่ควรพิจารณา:

ใช้คำนาม (Nouns) แทนคำกริยา (Verbs): Endpoint ควรสื่อถึงทรัพยากร (resource) ที่ API จัดการ ไม่ใช่การกระทำ (action) ที่ API ทำกับทรัพยากรนั้น
ใช้ภาษาอังกฤษ (English): Endpoint ควรใช้ภาษาอังกฤษเพื่อให้เป็นสากลและง่ายต่อการเข้าใจสำหรับนักพัฒนาจากทั่วโลก
ใช้ตัวพิมพ์เล็ก (Lowercase): Endpoint ควรใช้ตัวพิมพ์เล็กทั้งหมดเพื่อความเป็นระเบียบและความสอดคล้อง
ใช้ขีดกลาง (Hyphens) แทน Underscores: หากจำเป็นต้องใช้คำมากกว่าหนึ่งคำใน Endpoint ให้ใช้ขีดกลาง (-) แทน Underscores (_) เพื่อให้อ่านง่ายขึ้น
ใช้ Versioning: ควรใส่ Version ของ API ไว้ใน Endpoint เพื่อให้สามารถอัปเดต API ได้โดยไม่กระทบกับการทำงานของ Client ที่ใช้ API เวอร์ชั่นเก่า
ใช้ HTTP Methods ให้เหมาะสม: Endpoint ควรถูกออกแบบมาให้ทำงานร่วมกับ HTTP Methods (GET, POST, PUT, DELETE) อย่างถูกต้องและสอดคล้อง

ตัวอย่าง Endpoint ที่ดี

ต่อไปนี้เป็นตัวอย่าง Endpoint ที่ดีตามหลักการที่กล่าวมา:

ถูกต้อง: `/v1/users` (ดึงข้อมูลผู้ใช้ทั้งหมด - GET), `/v1/users/{id}` (ดึงข้อมูลผู้ใช้เฉพาะคน - GET, แก้ไขข้อมูลผู้ใช้เฉพาะคน - PUT, ลบข้อมูลผู้ใช้เฉพาะคน - DELETE)
ไม่ดี: `/getAllUsers` (ใช้คำกริยา), `/V1/Users` (ใช้ตัวพิมพ์ใหญ่), `/users_list` (ใช้ Underscores)
ถูกต้อง: `/v1/products` (ดึงข้อมูลสินค้าทั้งหมด - GET), `/v1/products/{product_id}` (ดึงข้อมูลสินค้าเฉพาะชิ้น - GET, แก้ไขข้อมูลสินค้าเฉพาะชิ้น - PUT, ลบข้อมูลสินค้าเฉพาะชิ้น - DELETE)
ไม่ดี: `/get_product_details` (ใช้คำกริยาและ Underscores), `/Products/ID` (ใช้ตัวพิมพ์ใหญ่)

คำอธิบายเพิ่มเติม:

`/v1/` คือ Version ของ API (Version 1)
`users` และ `products` คือชื่อของทรัพยากร (resources) ที่ API จัดการ
`{id}` และ `{product_id}` คือ Parameter ที่ใช้ระบุ ID ของผู้ใช้หรือสินค้าเฉพาะคน

การใช้ HTTP Methods กับ Endpoint

Endpoint ที่ดีจะต้องถูกออกแบบมาให้ทำงานร่วมกับ HTTP Methods อย่างถูกต้องและสอดคล้อง ตารางต่อไปนี้แสดงตัวอย่างการใช้งาน HTTP Methods กับ Endpoint `/v1/users`:

HTTP Method	Endpoint	คำอธิบาย
GET	`/v1/users`	ดึงข้อมูลผู้ใช้ทั้งหมด
POST	`/v1/users`	สร้างผู้ใช้ใหม่
GET	`/v1/users/{id}`	ดึงข้อมูลผู้ใช้ที่มี ID เท่ากับ `{id}`
PUT	`/v1/users/{id}`	แก้ไขข้อมูลผู้ใช้ที่มี ID เท่ากับ `{id}`
DELETE	`/v1/users/{id}`	ลบข้อมูลผู้ใช้ที่มี ID เท่ากับ `{id}`

ตัวอย่างโค้ด (PHP):

ถึงแม้ว่าเราจะยังไม่ได้ลงลึกในเรื่องของการเขียนโค้ด PHP สำหรับ API แต่เราสามารถยกตัวอย่างการทำงานของ Endpoint ในเชิงคอนเซปต์ได้ดังนี้:

<?php

// ตัวอย่างการจัดการ Endpoint /v1/users ด้วย HTTP Method GET
if ($_SERVER['REQUEST_METHOD'] === 'GET' && $_SERVER['REQUEST_URI'] === '/v1/users') {
  // ดึงข้อมูลผู้ใช้ทั้งหมดจากฐานข้อมูล
  $users = getUsersFromDatabase();

  // แปลงข้อมูลเป็น JSON และส่งกลับไป
  header('Content-Type: application/json');
  echo json_encode($users);
}

// ตัวอย่างการจัดการ Endpoint /v1/users/{id} ด้วย HTTP Method GET
elseif ($_SERVER['REQUEST_METHOD'] === 'GET' && preg_match('/\/v1\/users\/(\d+)/', $_SERVER['REQUEST_URI'], $matches)) {
  // ดึง ID ของผู้ใช้จาก URL
  $userId = $matches[1];

  // ดึงข้อมูลผู้ใช้จากฐานข้อมูลโดยใช้ ID
  $user = getUserFromDatabase($userId);

  // ถ้าไม่พบผู้ใช้ ให้ส่ง Error กลับไป
  if (!$user) {
    http_response_code(404); // Not Found
    echo json_encode(['message' => 'User not found']);
    exit;
  }

  // แปลงข้อมูลเป็น JSON และส่งกลับไป
  header('Content-Type: application/json');
  echo json_encode($user);
}

// ฟังก์ชันจำลองสำหรับการดึงข้อมูลผู้ใช้จากฐานข้อมูล (ในความเป็นจริงจะต้องเชื่อมต่อกับฐานข้อมูล)
function getUsersFromDatabase() {
  // จำลองข้อมูลผู้ใช้
  return [
    ['id' => 1, 'name' => 'John Doe'],
    ['id' => 2, 'name' => 'Jane Smith']
  ];
}

function getUserFromDatabase($id) {
  // จำลองข้อมูลผู้ใช้
  if ($id == 1) {
    return ['id' => 1, 'name' => 'John Doe'];
  } elseif ($id == 2) {
    return ['id' => 2, 'name' => 'Jane Smith'];
  } else {
    return null;
  }
}

?>

คำอธิบายโค้ด:

โค้ดนี้เป็นเพียงตัวอย่างเพื่อให้เห็นภาพการทำงานของ Endpoint และ HTTP Methods เท่านั้น
`$_SERVER['REQUEST_METHOD']` ใช้ตรวจสอบ HTTP Method ที่ Client ส่งมา
`$_SERVER['REQUEST_URI']` ใช้ตรวจสอบ URL ที่ Client ส่งมา
`preg_match()` ใช้ตรวจสอบรูปแบบ URL และดึงค่า Parameter (ในที่นี้คือ ID ของผู้ใช้)
`json_encode()` ใช้แปลงข้อมูล PHP เป็น JSON String
`header('Content-Type: application/json')` ใช้กำหนด Content-Type ของ Response เป็น JSON
`http_response_code(404)` ใช้ส่ง HTTP Status Code 404 (Not Found) กลับไปเมื่อไม่พบข้อมูล

สรุป

Endpoint คือจุดเชื่อมต่อที่ Client ใช้เพื่อเข้าถึงทรัพยากรหรือฟังก์ชันการทำงานของ API การออกแบบ Endpoint ที่ดีมีความสำคัญอย่างมากต่อความสามารถในการใช้งานและความง่ายในการบำรุงรักษาของ API ควรใช้คำนามแทนคำกริยา ใช้ภาษาอังกฤษ ใช้ตัวพิมพ์เล็ก ใช้ขีดกลางแทน Underscores ใช้ Versioning และใช้ HTTP Methods ให้เหมาะสม ในบทต่อไป เราจะเริ่มทำการติดตั้ง PHP และ Web Server เพื่อเตรียมพร้อมสำหรับการสร้าง API จริงๆ ครับ