วิธีใช้ Apidog เข้าใจพื้นฐาน API: Request, Response, Body, Header, Auth และอื่นๆ

คุณอาจเคยต้องเรียกใช้ API ของบุคคลที่สามในบางโปรเจกต์ หรือกำลังเรียนรู้วิธีทำให้ระบบต่างๆ สื่อสารกัน เมื่อคุณส่งคำขอตามเอกสาร คุณมักจะได้รับข้อผิดพลาดที่อธิบายไม่ได้ เช่น 400 Bad Request, 401 Unauthorized หรือไม่ได้รับอะไรกลับมาเลย

ปัญหาเหล่านี้มักจะอยู่ที่รายละเอียดที่ดูเหมือนง่ายแต่สำคัญอย่างยิ่ง: รูปแบบคำขอไม่ถูกต้อง, ข้อมูล Header ที่จำเป็นขาดหายไป, วิธีการยืนยันตัวตนไม่ถูกต้อง หรือรูปแบบข้อมูลไม่ตรงกับที่ API คาดหวัง หากแนวคิดพื้นฐานเหล่านี้ไม่เข้าใจอย่างชัดเจน การเรียกใช้ API ทุกครั้งจะรู้สึกเหมือนการเสี่ยงโชค

คุณจำเป็นต้องเข้าใจองค์ประกอบแต่ละส่วนของคำขอและคำตอบอย่างแท้จริง และรู้บทบาทของแต่ละส่วน เพื่อให้คุณสามารถระบุสาเหตุได้อย่างรวดเร็วเมื่อเกิดปัญหา

ถัดไป เราจะเริ่มต้นจากแนวคิดพื้นฐานที่สุด และค่อยๆ ชี้แจงกระบวนการทำงานของ API ทั้งหมดทีละขั้นตอน

คำขอ (Requests): สิ่งที่คุณบอกกับเซิร์ฟเวอร์

เมื่อคุณต้องการรับข้อมูลจากเซิร์ฟเวอร์ หรือต้องการให้เซิร์ฟเวอร์ดำเนินการบางอย่าง คุณต้องส่งคำขอ (request)

คำขอ API ที่สมบูรณ์ประกอบด้วยองค์ประกอบสำคัญหลายประการ ประการแรกคือเมธอดของคำขอ (request method) ซึ่งที่พบบ่อยที่สุดคือ GET, POST, PUT, DELETE

• GET ใช้สำหรับดึงข้อมูล
• POST ใช้สำหรับสร้างข้อมูลใหม่
• PUT ใช้สำหรับอัปเดตข้อมูลที่มีอยู่
• DELETE ใช้สำหรับลบข้อมูล

นอกเหนือจากเมธอดแล้ว คำขอยังต้องระบุ URL ซึ่งจะบอกระบบว่าทรัพยากรเฉพาะที่คุณต้องการเข้าถึงอยู่ที่ใด ตัวอย่างเช่น https://api.weather.com/current/beijing ระบุอย่างชัดเจนว่าคุณต้องการรับข้อมูลสภาพอากาศปัจจุบันของปักกิ่ง

แต่การมีเพียงเมธอดและ URL นั้นยังไม่เพียงพอ บ่อยครั้งที่คุณต้องส่งข้อมูลเพิ่มเติมไปยังเซิร์ฟเวอร์ นี่คือส่วนอื่นๆ ของคำขอที่เข้ามาเกี่ยวข้อง: Header และ Body

Header: คำสั่งเพิ่มเติมสำหรับคำขอ

Header ประกอบด้วยข้อมูลเมตาต่างๆ เกี่ยวกับคำขอ ซึ่งช่วยให้เซิร์ฟเวอร์เข้าใจและประมวลผลคำขอของคุณได้ดียิ่งขึ้น

Header พื้นฐานที่สุดคือ Content-Type ซึ่งจะบอกเซิร์ฟเวอร์ว่าข้อมูลที่คุณกำลังส่งอยู่ในรูปแบบใด หากคุณกำลังส่งข้อมูล JSON ให้ตั้งค่า Content-Type: application/json หากส่งข้อมูลฟอร์ม ให้ตั้งค่า Content-Type: application/x-www-form-urlencoded

Header ที่สำคัญอีกอย่างคือ User-Agent ซึ่งระบุว่าไคลเอนต์ใดกำลังส่งคำขอ เบราว์เซอร์จะตั้งค่านี้โดยอัตโนมัติ เพื่อบอกเซิร์ฟเวอร์ว่าคำขอนั้นมาจาก Chrome, Firefox หรือเบราว์เซอร์อื่น

Header Accept จะบอกเซิร์ฟเวอร์ว่าคุณคาดหวังรูปแบบใดสำหรับคำตอบ ตัวอย่างเช่น Accept: application/json หมายความว่าคุณต้องการให้เซิร์ฟเวอร์ส่งข้อมูลกลับมาในรูปแบบ JSON

นอกจากนี้ยังมี Header สำหรับการควบคุมแคช เช่น Cache-Control ซึ่งสามารถสั่งการเซิร์ฟเวอร์หรือพร็อกซีเซิร์ฟเวอร์กลางว่าจะจัดการแคชอย่างไร Header เหล่านี้อาจดูเป็นเชิงเทคนิค แต่การทำความเข้าใจจะช่วยให้คุณควบคุมพฤติกรรม API ได้ดียิ่งขึ้น

Body: เนื้อหาเฉพาะของคำขอ

เมื่อคุณต้องการส่งข้อมูลจำนวนมากไปยังเซิร์ฟเวอร์ ข้อมูลนั้นจะอยู่ในส่วน Body

คำขอ GET มักจะไม่มี Body เนื่องจาก GET ใช้สำหรับดึงข้อมูลเป็นหลัก และพารามิเตอร์ที่จำเป็นสามารถวางไว้ใน URL ได้โดยตรง แต่คำขอเช่น POST และ PUT มักจะต้องมี Body เพื่อบรรจุข้อมูล

รูปแบบ Body ที่พบบ่อยที่สุดคือ JSON ตัวอย่างเช่น เมื่อลงทะเบียนผู้ใช้บนเว็บไซต์ เบราว์เซอร์ของคุณจะส่งคำขอ POST พร้อม Body ที่อาจมีลักษณะดังนี้:

{
  "username": "john_doe",
  "email": "john@example.com",
  "password": "secretpassword"
}

รูปแบบ Body ทั่วไปอีกรูปแบบหนึ่งคือ form-data โดยเฉพาะอย่างยิ่งเมื่ออัปโหลดไฟล์ รูปแบบนี้สามารถรวมทั้งข้อมูลข้อความและข้อมูลไฟล์ ทำให้เหมาะสำหรับการจัดการการส่งฟอร์มที่ซับซ้อน

API บางตัวใช้รูปแบบ XML สำหรับ Body แม้ว่าจะพบน้อยกว่า JSON ในปัจจุบัน แต่ก็ยังคงใช้อย่างแพร่หลายในระบบองค์กรบางแห่ง ไม่ว่ารูปแบบใด สิ่งสำคัญคือต้องแน่ใจว่า Header Content-Type ตรงกับรูปแบบจริงของ Body

คำตอบ (Responses): การตอบกลับจากเซิร์ฟเวอร์

เมื่อเซิร์ฟเวอร์ได้รับคำขอของคุณ จะส่งคำตอบกลับมา โครงสร้างของคำตอบคล้ายกับคำขอ ซึ่งรวมถึง Header และ Body แต่มีองค์ประกอบสำคัญเพิ่มเติมคือ: รหัสสถานะ (status code)

รหัสสถานะคือตัวเลขสามหลักที่บอกคุณถึงผลลัพธ์ของการประมวลผลคำขอ 200 หมายถึงสำเร็จ ซึ่งเป็นสิ่งที่คุณหวังว่าจะเห็นมากที่สุด 404 หมายถึงไม่พบทรัพยากรที่ร้องขอ หรือที่รู้จักกันในชื่อ "ข้อผิดพลาด 404" 500 หมายถึงข้อผิดพลาดภายในเซิร์ฟเวอร์ ซึ่งโดยปกติแล้วหมายความว่ามีบางอย่างผิดพลาดที่ฝั่งเซิร์ฟเวอร์

Header ของคำตอบประกอบด้วยข้อมูลต่างๆ เกี่ยวกับคำตอบ Content-Type จะบอกคุณถึงรูปแบบของข้อมูลคำตอบ, Content-Length จะบอกคุณถึงขนาดของข้อมูลคำตอบ และ Set-Cookie ใช้สำหรับตั้งค่าคุกกี้บนฝั่งไคลเอนต์

Body ของคำตอบประกอบด้วยข้อมูลจริงที่คุณร้องขอ หากร้องขอข้อมูลสภาพอากาศ Body อาจมีอุณหภูมิ ความชื้น ความเร็วลม เป็นต้น หากร้องขอข้อมูลผู้ใช้ Body อาจมีชื่อผู้ใช้ อีเมล เวลาลงทะเบียน เป็นต้น

การทำความเข้าใจโครงสร้างของคำตอบช่วยให้คุณสามารถพิจารณาได้ว่าการเรียกใช้ API สำเร็จหรือไม่ และจะจัดการกับข้อมูลที่ส่งกลับมาได้อย่างไร เมื่อการเรียกใช้ API ผิดพลาด การตรวจสอบรหัสสถานะและ Body ของคำตอบมักจะเป็นขั้นตอนแรกในการวินิจฉัยปัญหา

การยืนยันตัวตน (Auth): การพิสูจน์ตัวตนของคุณ

API ที่มีคุณค่าส่วนใหญ่ต้องการการยืนยันตัวตนบางรูปแบบ เช่นเดียวกับที่คุณต้องใช้บัตรประจำตัวเพื่อเข้าสถานที่บางแห่ง คุณต้องให้ข้อมูลรับรองเพื่อเข้าถึง API ที่ได้รับการป้องกัน

วิธีการยืนยันตัวตนที่ง่ายที่สุดคือ API Key ผู้ให้บริการจะมอบคีย์เฉพาะให้คุณ ซึ่งคุณจะรวมไว้ในทุกคำขอ โดยทั่วไป API Key จะถูกวางไว้ใน Header เช่น Authorization: Bearer your-api-key-here

อีกวิธีที่พบบ่อยคือ Basic Authentication คุณให้ชื่อผู้ใช้และรหัสผ่าน ซึ่งไคลเอนต์จะเข้ารหัสและวางไว้ใน Header Authorization แม้จะง่าย แต่วิธีนี้มีความปลอดภัยค่อนข้างต่ำ

OAuth เป็นวิธีการยืนยันตัวตนที่ซับซ้อนแต่ปลอดภัยกว่า ช่วยให้ผู้ใช้สามารถอนุญาตให้แอปของบุคคลที่สามเข้าถึงข้อมูลของตนได้โดยไม่ต้องให้รหัสผ่านโดยตรง เมื่อคุณเข้าสู่ระบบแอปอื่นโดยใช้ WeChat คุณกำลังใช้กระบวนการ OAuth

JWT (JSON Web Token) เป็นวิธีการยืนยันตัวตนยอดนิยมอีกวิธีหนึ่ง หลังจากผู้ใช้เข้าสู่ระบบ เซิร์ฟเวอร์จะสร้างโทเค็นที่มีข้อมูลผู้ใช้ ซึ่งผู้ใช้จะนำไปใช้ในการร้องขอครั้งถัดไป ข้อดีของ JWT คือเซิร์ฟเวอร์ไม่จำเป็นต้องจัดเก็บข้อมูลเซสชัน ซึ่งช่วยเพิ่มความสามารถในการปรับขนาดของระบบ

การเลือกวิธีการยืนยันตัวตนขึ้นอยู่กับความต้องการเฉพาะและข้อกำหนดด้านความปลอดภัยของคุณ สำหรับโปรเจกต์ส่วนตัวง่ายๆ API Key อาจเพียงพอ สำหรับแอปที่ต้องการการเข้าสู่ระบบของผู้ใช้ OAuth หรือ JWT อาจเหมาะสมกว่า

การประยุกต์ใช้จริง: การเชื่อมโยงแนวคิดเหล่านี้เข้าด้วยกัน

ตอนนี้เรามาดูกันว่าแนวคิดเหล่านี้ทำงานร่วมกันได้อย่างไรผ่านตัวอย่างเฉพาะ สมมติว่าคุณกำลังพัฒนาแอปบล็อกและต้องการสร้างบทความใหม่

อันดับแรก คุณส่งคำขอ POST ไปยัง https://api.myblog.com/articles Header ของคำขอจะรวม Content-Type เพื่อระบุรูปแบบข้อมูล และ Authorization เพื่อให้ข้อมูลการยืนยันตัวตน:

POST /articles HTTP/1.1
Host: api.myblog.com
Content-Type: application/json
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...

Body ประกอบด้วยเนื้อหาเฉพาะของบทความ:

{
  "title": "API Basics Introduction",
  "content": "This is a detailed introduction to APIs...",
  "tags": ["API", "Programming", "Beginner"]
}

หลังจากได้รับคำขอ เซิร์ฟเวอร์จะตรวจสอบโทเค็นใน Header Authorization ก่อนเพื่อยืนยันว่าคุณมีสิทธิ์ในการสร้างบทความ จากนั้นจะแยกวิเคราะห์ข้อมูล JSON ใน Body และสร้างบันทึกบทความใหม่

หากทุกอย่างเป็นไปอย่างราบรื่น เซิร์ฟเวอร์จะส่งคืนรหัสสถานะ 201 (ระบุว่าสร้างสำเร็จ) Header ของคำตอบอาจรวมถึงตำแหน่งของบทความที่สร้างขึ้นใหม่ และ Body จะมีข้อมูลบทความฉบับเต็ม รวมถึง ID ที่ระบบสร้างขึ้นและเวลาที่สร้าง:

{
  "id": 12345,
  "title": "API Basics Introduction",
  "content": "This is a detailed introduction to APIs...",
  "tags": ["API", "Programming", "Beginner"],
  "created_at": "2024-01-15T10:30:00Z",
  "author_id": 678
}

กระบวนการที่สมบูรณ์นี้แสดงให้เห็นว่าคำขอ, คำตอบ, Body, Header และการยืนยันตัวตน ทำงานร่วมกันได้อย่างไร แต่ละส่วนมีบทบาทของตนเอง แต่ทั้งหมดร่วมกันทำให้การโต้ตอบ API สมบูรณ์

การดีบักและการทดสอบ: ทำให้การพัฒนา API ราบรื่นยิ่งขึ้น

เมื่อคุณเริ่มใช้งาน API จริงๆ คุณจะพบปัญหาต่างๆ อย่างหลีกเลี่ยงไม่ได้ คำขอถูกส่งไป แต่กลับคืนรหัสสถานะข้อผิดพลาด หรือรูปแบบข้อมูลคำตอบไม่เป็นไปตามที่คุณคาดหวัง หรือการยืนยันตัวตนล้มเหลวเสมอ

ณ จุดนี้ คุณจำเป็นต้องสามารถดูเนื้อหาคำขอและคำตอบทั้งหมดได้ เครื่องมือสำหรับนักพัฒนาของเบราว์เซอร์เป็นจุดเริ่มต้นที่ดี เนื่องจากสามารถแสดงคำขอ HTTP ทั้งหมด รวมถึง Header และ Body สำหรับการทดสอบ API ที่ซับซ้อนมากขึ้น การใช้ Apidog จะมีประโยชน์มากกว่า

ปัญหาที่พบบ่อย ได้แก่ Content-Type ไม่ตรงกัน, ข้อผิดพลาดข้อมูลการยืนยันตัวตน, รูปแบบคำขอไม่ถูกต้อง เป็นต้น การตรวจสอบรหัสสถานะและข้อความแสดงข้อผิดพลาดอย่างละเอียดมักจะช่วยให้คุณระบุปัญหาได้อย่างรวดเร็ว