การเขียน OpenAPI / Swagger Spec: การนิยาม HTTP Status Code (200, 400, 401, 403, 500) และ Error Response

ในโลกของสถาปัตยกรรมระบบไมโครเซอร์วิส (Microservices) การสื่อสารระหว่างระบบต่างๆ ผ่าน Application Programming Interfaces (APIs) คือหัวใจหลักของธุรกิจดิจิทัล ความสำเร็จในการเชื่อมต่อเหล่านี้ไม่ได้ขึ้นอยู่กับแค่การส่งข้อมูลได้เท่านั้น แต่ยังรวมถึงความสามารถในการแจ้งสถานะ (Status) ของผลลัพธ์นั้นๆ อย่างชัดเจนและเป็นมาตรฐาน การกำหนดสัญญา (Contract) ที่แม่นยำสำหรับทุก Endpoint จึงเป็นสิ่งจำเป็นอย่างยิ่ง เพื่อให้ทั้งผู้พัฒนาฝั่ง Client และ Server เข้าใจตรงกันว่าเมื่อเกิดอะไรขึ้นบ้าง ไม่ว่าจะสำเร็จหรือผิดพลาด

OpenAPI Specification (OAS): สัญญาของ API ที่สมบูรณ์

OpenAPI Specification (OAS) คือมาตรฐานสากลที่ช่วยให้เราสามารถนิยาม API ทั้งหมดได้อย่างเป็นทางการ โดยไม่ได้จำกัดแค่การระบุว่า Endpoint นั้นๆ รับข้อมูลอะไร แต่ยังรวมถึงการกำหนด “สัญญา” ของสถานะ HTTP Code ที่คาดหวังไว้ด้วย การทำเช่นนี้ทำให้เครื่องมือต่างๆ สามารถอ่านและเข้าใจพฤติกรรมของ API ได้โดยอัตโนมัติ ทำให้เกิดความน่าเชื่อถือในระดับสถาปัตยกรรม

การนิยาม Status Code อย่างถูกต้องเป็นสิ่งสำคัญอย่างยิ่งในการสร้างประสบการณ์ที่ดีให้กับนักพัฒนา (Developer Experience – DX) เราต้องแยกแยะความแตกต่างของรหัสสถานะหลักๆ:

• 2xx (Success): การร้องขอสำเร็จ เช่น 200 OK
• 400 Bad Request: ข้อมูลที่ Client ส่งมาผิดรูปแบบ (เช่น ข้อมูลไม่ครบถ้วน)
• 401 Unauthorized: ผู้ใช้ไม่ได้ส่ง Credentials ที่ถูกต้อง
• 403 Forbidden: ผู้ใช้มีสิทธิ์ แต่ไม่มีสิทธิ์เข้าถึงทรัพยากรนั้นๆ
• 500 Internal Server Error: ข้อผิดพลาดที่เกิดจากฝั่ง Server (เช่น โค้ดล่ม หรือเกิด Constraint Violation ใน PostgreSQL)

การจัดการ Error Response ในบริบท PostgreSQL

เมื่อเราออกแบบ API ที่ทำงานกับฐานข้อมูล PostgreSQL การทำความเข้าใจว่าข้อผิดพลาดของฐานข้อมูลจะถูกแปลงเป็น HTTP Status Code อย่างไรจึงเป็นสิ่งสำคัญอย่างยิ่ง ตัวอย่างเช่น หาก API ของเรามีหน้าที่ดึงข้อมูลผู้ใช้ตาม ID และมีการเรียกใช้ฟังก์ชันที่ต้องตรวจสอบความถูกต้องของข้อมูลก่อนการประมวลผล:

SQL

-- ฟังก์ชันที่อาจเกิดข้อผิดพลาด (Constraint Violation) เมื่อรันใน Postgres
CREATE OR REPLACE FUNCTION process_user_data(user_id INT, data_list TEXT[])
RETURNS JSON AS $$
BEGIN
    -- สมมติว่ามีการตรวจสอบว่า user_id ต้องมีอยู่จริง
    SELECT * FROM users WHERE id = user_id;
    -- หาก data_list มีค่าที่ผิดรูปแบบ (เช่น มีค่า NULL ในคอลัมน์ที่ห้ามเป็น NULL)
    -- การ INSERT/UPDATE จะล้มเหลวและส่งข้อผิดพลาดกลับมา
    RETURN json_build_object('status', 'success', 'data', 'processed');
EXCEPTION
    WHEN unique_violation THEN
        -- การจับข้อผิดพลาดเฉพาะทางของ Postgres
        RAISE EXCEPTION 'Duplicate entry detected for user ID %', user_id;
    WHEN others THEN
        -- การจับข้อผิดพลาดทั่วไป (เช่น data type mismatch)
        RAISE EXCEPTION 'Database processing failed: %', SQLERRM;
END;

ในส่วนของ OpenAPI Spec เราจะต้องระบุว่าเมื่อฟังก์ชันนี้ล้มเหลวเนื่องจาก `unique_violation` (ซึ่งเป็นข้อผิดพลาดของข้อมูล) API ควรส่งสถานะ 400 Bad Request หรือ 422 Unprocessable Entity กลับไป พร้อมทั้งกำหนด Schema ของ Error Response ที่ระบุสาเหตุที่ชัดเจน เช่น: `{“error_code”: “DUPLICATE_ENTRY”, “message”: “User ID 1,2,3 already exists.”}`

บทสรุป: การสร้างสัญญาที่เชื่อถือได้

การนิยาม OpenAPI Spec ที่ครอบคลุม Status Code ทั้งหมด (200, 400, 401, 403, 500) ไม่ใช่แค่การทำเอกสาร แต่คือการสร้าง “สัญญาทางสถาปัตยกรรม” ที่ทำให้ทั้งทีมพัฒนาและผู้ใช้งาน API เข้าใจพฤติกรรมของระบบได้อย่างสมบูรณ์ การจัดการข้อผิดพลาดที่ชัดเจนตั้งแต่ระดับ Spec ทำให้การพัฒนาและการบำรุงรักษา API ที่ทำงานร่วมกับ PostgreSQL เป็นไปอย่างมีมาตรฐานและมีประสิทธิภาพสูงสุด