ออกแบบ REST API ให้มืออาชีพตามแนวทาง Google API Design Guide

API ที่ออกแบบดีคือสัญญาที่ทีมอื่นพึ่งพาได้นานหลายปี บทความนี้สรุปหลักการจาก API Design Guide ของ Google ครอบคลุมการออกแบบแบบ Resource-Oriented การตั้งชื่อ การจัดการ Error การแบ่งหน้า และการทำเวอร์ชัน พร้อมตัวอย่างที่นำไปใช้กับโปรเจกต์จริงได้ทันที

คิดแบบ Resource ไม่ใช่แบบฟังก์ชัน

หัวใจของแนวทาง Google คือ Resource-Oriented Design ให้มอง API เป็นชุดของทรัพยากร (Resource) ที่มีชื่อเรียกชัดเจน เช่น ลูกค้า คำสั่งซื้อ สินค้า แล้วใช้กริยามาตรฐานของ HTTP จัดการ ได้แก่ GET (อ่าน), POST (สร้าง), PATCH (แก้ไขบางส่วน), DELETE (ลบ) แทนที่จะสร้าง Endpoint แบบกริยาเฉพาะกิจอย่าง /getCustomerData หรือ /doOrderCancel ที่เพิ่มจำนวนไม่รู้จบ

ตั้งชื่อ Collection เป็นคำนามพหูพจน์และวางลำดับชั้นให้สื่อความสัมพันธ์ เช่น GET /customers/123/orders หมายถึงคำสั่งซื้อทั้งหมดของลูกค้า 123 รูปแบบที่คาดเดาได้เช่นนี้ทำให้นักพัฒนาที่มาใหม่เดา API ได้ถูกโดยแทบไม่ต้องเปิดเอกสาร ซึ่งคือเครื่องหมายของ API ที่ออกแบบดี

ใช้ HTTP Status Code ให้ตรงความหมาย

Status Code คือภาษากลางที่ไคลเอนต์ใช้ตัดสินใจ อย่าตอบ 200 OK พร้อมข้อความ error ในเนื้อหา เพราะจะหลอกทั้งระบบ Monitoring และ Retry Logic ของผู้เรียก แนวทางพื้นฐานคือ 200/201 สำเร็จ, 400 คำขอผิดรูปแบบ, 401 ยังไม่ยืนยันตัวตน, 403 ไม่มีสิทธิ์, 404 ไม่พบทรัพยากร, 409 ข้อมูลขัดแย้ง และ 500 ข้อผิดพลาดฝั่งเซิร์ฟเวอร์

Google แนะนำโครงสร้าง Error Body ที่สม่ำเสมอทั้งระบบ ประกอบด้วยรหัส error ที่โปรแกรมอ่านได้ ข้อความที่มนุษย์เข้าใจ และรายละเอียดประกอบ เช่น ฟิลด์ไหนผิดเพราะอะไร การลงทุนออกแบบ Error ให้ดีช่วยลดเวลาดีบักของทีมผู้ใช้ API ลงมาก และลดตั๋ว Support ที่ถามว่า "ทำไม error" ได้อย่างเห็นผล

การแบ่งหน้า การกรอง และการเรียงลำดับ

ทุก Endpoint ที่คืนรายการต้องรองรับการแบ่งหน้า (Pagination) ตั้งแต่วันแรก เพราะเพิ่มทีหลังคือ Breaking Change แนวทางของ Google คือ Cursor-Based Pagination ใช้พารามิเตอร์ page_size คู่กับ page_token โดยเซิร์ฟเวอร์คืน next_page_token สำหรับเรียกหน้าถัดไป วิธีนี้ให้ผลถูกต้องแม้ข้อมูลถูกเพิ่มหรือลบระหว่างการเลื่อนหน้า ต่างจาก offset ที่อาจข้ามหรือซ้ำรายการ

กำหนดค่า default และเพดานของ page_size เสมอ เช่น default 20 สูงสุด 100 เพื่อป้องกันการดึงข้อมูลทั้งตารางโดยไม่ตั้งใจ ส่วนการกรองและเรียงลำดับให้ใช้พารามิเตอร์มาตรฐานอย่าง filter และ order_by ในรูปแบบเดียวกันทุก Endpoint เพื่อให้ผู้ใช้เรียนรู้ครั้งเดียวใช้ได้ทั้งระบบ

ทำเวอร์ชันอย่างมีวินัย: สัญญาที่ห้ามฉีก

เมื่อ API เผยแพร่แล้ว มันคือสัญญากับผู้ใช้ทุกราย การเปลี่ยนแปลงที่ทำลายความเข้ากันได้ (Breaking Change) เช่น ลบฟิลด์ เปลี่ยนชนิดข้อมูล หรือเปลี่ยนความหมาย ต้องออกเป็นเวอร์ชันใหม่เท่านั้น แนวทางที่แพร่หลายคือใส่เวอร์ชันหลักไว้ในเส้นทาง เช่น /v1/customers และเมื่อออก v2 ให้ประกาศ Deprecation Timeline ของ v1 ชัดเจน เช่น สนับสนุนต่ออีกอย่างน้อย 12 เดือน

การเปลี่ยนแปลงที่ไม่ทำลาย เช่น เพิ่มฟิลด์ใหม่หรือเพิ่ม Endpoint ใหม่ ทำได้ในเวอร์ชันเดิม โดยฝั่งไคลเอนต์ก็ควรเขียนแบบ Tolerant Reader คือไม่พังเมื่อเจอฟิลด์ที่ไม่รู้จัก วินัยสองฝั่งนี้ทำให้ระบบวิวัฒน์ได้โดยไม่ต้องนัดหยุดระบบพร้อมกันทุกทีม

ความปลอดภัยพื้นฐานที่ขาดไม่ได้

ทุก API ต้องวิ่งบน HTTPS เท่านั้น การยืนยันตัวตนให้ใช้มาตรฐานเปิดอย่าง OAuth 2.0 กับ Bearer Token (เช่น JWT) แทนการประดิษฐ์ระบบเอง กำหนดอายุ Token ให้สั้น เช่น 15-60 นาที คู่กับ Refresh Token และตรวจสอบสิทธิ์ระดับทรัพยากรทุกครั้ง อย่าเชื่อว่าผู้ที่ยืนยันตัวตนแล้วมีสิทธิ์กับทุกข้อมูล ซึ่งเป็นช่องโหว่ Broken Access Control อันดับหนึ่งใน OWASP Top 10

เพิ่ม Rate Limiting เพื่อกันทั้งการโจมตีและบั๊กฝั่งไคลเอนต์ที่ยิงรัว เช่น จำกัด 1,000 คำขอต่อนาทีต่อ API Key พร้อมตอบ 429 และเฮดเดอร์ Retry-After และอย่าใส่ข้อมูลอ่อนไหวใน URL เพราะ URL มักถูกบันทึกใน Log หลายชั้นตลอดเส้นทาง

เอกสารและกระบวนการ: Design-First ด้วย OpenAPI

แนวทางที่ทีมชั้นนำใช้คือ Design-First เขียนสเปกด้วย OpenAPI (Swagger) ก่อนเขียนโค้ด แล้วให้ทีม Backend, Frontend และ QA รีวิวสัญญาร่วมกัน สเปกนี้ใช้สร้างเอกสารโต้ตอบได้ สร้าง Mock Server ให้ Frontend เริ่มงานได้ทันที และสร้าง Client SDK อัตโนมัติ ลดงานซ้ำซ้อนทั้งสาย

สุดท้าย ตั้ง Review Checklist สำหรับ API ใหม่ทุกตัว เช่น ตั้งชื่อตามมาตรฐานหรือไม่ มี Pagination หรือไม่ Error Format ตรงมาตรฐานกลางหรือไม่ และมี Backward Compatibility หรือไม่ การรีวิวการออกแบบ API เหมือนที่รีวิวโค้ด คือการลงทุนที่ให้ผลตอบแทนยาวนานที่สุดอย่างหนึ่งของทีมแพลตฟอร์ม