ในโลกของการพัฒนา Microservices และระบบที่ต้องมีการสื่อสารระหว่างบริการ (Service-to-Service Communication) การมี ‘สัญญา’ (Contract) ที่ชัดเจนสำหรับ API คือหัวใจสำคัญที่สุด OpenAPI Specification (OAS) หรือที่รู้จักกันในชื่อ Swagger คือเครื่องมือมาตรฐานที่ช่วยให้เราสามารถกำหนดโครงสร้างของ API ได้อย่างแม่นยำและเป็นระบบ การทำความเข้าใจและกำหนดองค์ประกอบของ Request อย่างครบถ้วน ไม่ว่าจะเป็น Path Parameters, Query Parameters หรือ Request Headers จึงเป็นทักษะที่จำเป็นสำหรับ Senior Developer ทุกคน
ทำไมต้องกำหนด OpenAPI Spec อย่างละเอียด?
การกำหนด Spec ที่สมบูรณ์ช่วยให้เกิดประโยชน์หลายด้าน ตั้งแต่การสร้าง Mock Server สำหรับการพัฒนาแบบขนาน (Parallel Development) ไปจนถึงการสร้างระบบ Validation Gateway โดยเฉพาะเมื่อ API ของคุณต้องโต้ตอบกับฐานข้อมูล Backend อย่าง PostgreSQL การระบุพารามิเตอร์ที่ถูกต้องจะช่วยให้แน่ใจว่าคำสั่ง SQL ที่ถูกสร้างขึ้นจาก API Call นั้นจะได้รับค่าที่ถูกต้องและปลอดภัยจากช่องโหว่ประเภท SQL Injection
องค์ประกอบหลักในการกำหนด Request Parameters
OAS แบ่งพารามิเตอร์ออกเป็น 3 ประเภทหลัก ซึ่งแต่ละประเภทมีบทบาทที่แตกต่างกันในการส่งข้อมูล:
- Path Parameters: ใช้ระบุทรัพยากรเฉพาะเจาะจงใน URL เช่น การดึงข้อมูลผู้ใช้คนใดคนหนึ่ง (เช่น `/users/{user_id}`)
- Query Parameters: ใช้สำหรับการกรอง (Filtering), การจัดเรียง (Sorting) หรือการจำกัดจำนวนข้อมูล (Limiting) เช่น `?status=active&limit=10`
- Request Headers: ใช้ส่งข้อมูลเมตา (Metadata) ที่ไม่ปรากฏใน URL เช่น Bearer Token สำหรับการยืนยันตัวตน (Authorization) หรือ Content-Type
ตัวอย่างการใช้งานในบริบท PostgreSQL
สมมติว่าเรากำลังสร้าง API Endpoint เพื่อดึงรายการสินค้าจาก PostgreSQL โดยต้องการให้ผู้ใช้สามารถระบุ ID สินค้า (Path Parameter) และกรองตามหมวดหมู่ (Query Parameter) พร้อมทั้งต้องส่ง Token ยืนยันตัวตน (Header) เราจะต้องกำหนด Spec ให้ครอบคลุมทุกส่วน:
SQL
-- ตัวอย่างการเรียกใช้ฟังก์ชันที่รับพารามิเตอร์หลายตัวใน PostgreSQL
-- Path Parameter: $1 (product_id)
-- Query Parameter: $2 (category_name)
-- Header Parameter: ต้องถูกตรวจสอบก่อนถึงขั้นนี้
SELECT * FROM products
WHERE id = $1 AND category = $2;
-- ตัวอย่างการเรียกใช้ด้วยค่าจริง:
SELECT * FROM products WHERE id = 'p101' AND category = 'apple,banana,orange';
การกำหนด Spec นี้ช่วยให้เราสามารถสร้าง Validation Logic ที่มั่นใจได้ว่าค่าที่ส่งมา (เช่น ‘p101’ และ ‘apple,banana,orange’) จะถูกส่งผ่านไปยัง PostgreSQL อย่างปลอดภัยและตรงตามชนิดข้อมูลที่คาดหวัง (Type Casting) เสมอ
บทสรุป: Best Practices สำหรับ API Architect
การเขียน OpenAPI Spec ที่สมบูรณ์ไม่ใช่แค่การเขียนเอกสาร แต่คือการสร้าง ‘สัญญา’ ทางเทคนิคที่ช่วยลดความเสี่ยงของระบบทั้งหมด ในฐานะ Senior Architect คุณต้องมั่นใจว่าทุก Endpoint มีการระบุ Schema, Data Type, และ Constraints ของ Path, Query และ Header อย่างชัดเจน การทำเช่นนี้ไม่เพียงแต่ช่วยให้ทีมงานอื่นทำงานได้เร็วขึ้น แต่ยังช่วยให้ระบบ Backend อย่าง PostgreSQL ของเรามีความทนทาน (Resilience) และปลอดภัยสูงสุดด้วย