ผมดูแล Prisma Reviews ซึ่งเป็น API ขนาดเล็กที่รวบรวมรีวิวจากลูกค้าจาก 84 แพลตฟอร์มและส่งกลับในรูปแบบ JSON เดียวกัน บทความนี้ไม่ได้พูดถึงตัวผลิตภัณฑ์ แต่จะพูดถึงปัญหาทางวิศวกรรมสามข้อที่กินเวลาไปมากที่สุด ได้แก่ การออกแบบ schema ที่รองรับแหล่งข้อมูลที่มีโครงสร้างแตกต่างกันมาก การรักษา ID ให้คงที่เพื่อไม่ให้รีวิวเดียวกันปรากฏซ้ำสองครั้ง และการทดสอบ contract เพื่อไม่ให้การเปลี่ยนแปลงฝั่งต้นทางไปทำลายฝั่ง client โดยไม่มีใครรู้ตัว
ขอเกริ่นสั้น ๆ ก่อน เพราะเรื่องนี้กำหนดทุกอย่างที่เหลือ: รีวิวทุกแหล่งไม่ได้มาจาก API เสมอไป ใน 84 แหล่งของเรา มี 59 แหล่งที่มี API ทางการ ส่วนอีก 25 แหล่งไม่มี เราจึงอ่านข้อมูลจากหน้าเว็บสาธารณะหรือ feed ของพวกเขาแทน
ไม่ใช่ทุกแหล่งข้อมูลจะเป็น API
แพลตฟอร์มทุกตัวใน config ของเรามีคุณสมบัติสามอย่าง: ธุรกิจเชื่อมต่อกับมันอย่างไร, เราสามารถตอบกลับรีวิวได้หรือไม่ และรีวิวใหม่มาถึงเราทางไหน เมื่อจัดกลุ่ม 84 แหล่งตามวิธีที่เราอ่านข้อมูล จะได้สี่กลุ่ม:
| กลุ่ม | จำนวนแหล่ง | ตัวอย่าง |
|---|---|---|
| API ทางการ ใช้ credentials หรือ OAuth ของธุรกิจเอง | 50 | Google Business Profile (รอการอนุมัติสิทธิ์), App Store, Google Play, Trustpilot (รอการอนุมัติสิทธิ์), Judge.me, Yotpo, eBay, Wix, WooCommerce, Shopware, property manager อย่าง Hostaway และ Guesty |
| API สาธารณะทางการ ไม่ต้องใช้ credentials ของธุรกิจ | 9 | Steam, Etsy, Salesforce AppExchange, Atlassian Marketplace, VS Code Marketplace, Open VSX, JetBrains Marketplace, Thunderbird Add-ons, Viator |
| ไม่มี API: อ่านจากหน้าเว็บหรือ feed สาธารณะ | 3 | Shopify App Store (หน้ารีวิวแบบ HTML), WordPress.org (RSS feed ของรีวิว), Apple Podcasts (feed รีวิวสาธารณะ) |
| ไม่มี API: ผ่านผู้ให้บริการข้อมูลแบบเสียเงิน | 22 | Google Maps, Yelp, Tripadvisor, Booking.com, Facebook, Airbnb, Expedia, Capterra, OpenTable |
แต่ละกลุ่มแตกต่างกันในแบบที่ส่งผลต่อการออกแบบ API:
- การยืนยันตัวตน กลุ่มแรกต้องใช้ OAuth flow หรือ key ที่ธุรกิจนำมาวาง ส่วนอีกสามกลุ่มต้องใช้แค่ URL สาธารณะของ listing เท่านั้น
- การตอบกลับ มีเพียง 25 จาก 84 แหล่งที่อนุญาตให้บุคคลที่สามโพสต์คำตอบกลับได้ และสองแหล่งในนั้นคือ Google Business Profile กับ Trustpilot ยังรอแพลตฟอร์มอนุมัติสิทธิ์ของเราอยู่ การมี API อย่างเดียวไม่พอ: endpoint ตอบกลับของ Atlassian ตอนนี้ตอบกลับมาเป็น
410 API_DEPRECATEDและ reply API ของ Microsoft Store พังจากฝั่ง Microsoft เอง ทั้งสองจึงอ่านได้อย่างเดียว - ต้นทุนและความถี่ API ทางการไม่มีค่าใช้จ่ายต่อการเรียก เราจึงเช็คบ่อย ส่วนการอ่านผ่านผู้ให้บริการข้อมูลถูกคิดค่าบริการต่อรีวิว และบางผู้ให้บริการคิดค่าต่อรอบการรันโดยไม่สนว่ามีข้อมูลใหม่หรือไม่ แหล่งเหล่านี้จึงถูกเช็ควันละครั้ง
- ทำไมจึงไม่มี API partner API ของ Expedia ที่รองรับการตอบกลับเปิดให้เฉพาะ full channel manager เท่านั้น และพวกเขาปฏิเสธคำขอของเรา ของ Airbnb เปิดเฉพาะผู้ที่ได้รับเชิญ Shopify ไม่มีรีวิว API เลย นักพัฒนาแอปจึงต้องตอบกลับใน dashboard ของตัวเอง
บางแพลตฟอร์มปรากฏสองครั้ง รีวิวของ Airbnb และ Booking.com อาจมาจากหน้าเว็บสาธารณะ (อ่านได้อย่างเดียว) หรือผ่าน official API ของ property manager ซึ่งตอบกลับได้ นี่คือเหตุผลของหนึ่งในฟิลด์ที่จะพูดถึงด้านล่าง
ใช้ schema เดียวสำหรับทุกแหล่ง
รีวิวทุกฉบับจากทุกแหล่งมีฟิลด์เหมือนกัน 14 ฟิลด์ และทุกฟิลด์ต้องมีค่าเสมอ เมื่อแพลตฟอร์มไม่ได้ให้ข้อมูลบางอย่างกับเรา ฟิลด์นั้นจะเป็น null ไม่ใช่หายไป ฟิลด์ที่หายไปกับค่า null ไม่ต่างอะไรกันสำหรับมนุษย์ แต่ไม่ใช่สำหรับ client ที่มี type แบบเข้มงวด และการรับประกันว่า "มีค่าเสมอ" ทำให้ง่ายต่อการทดสอบ
{ "id": "rev_01KJ8Q2M4T7HX3VB9CWD6NRZ5E", "platform": "google", "location_id": "loc_01KJ8P9W2C4D6F8G0H2J4K6M8N", "rating": 4, "title": null, "text": "Great flat white, a bit slow at lunchtime.", "author": "Marta G.", "language": "en", "url": null, "source": null, "created_at": "2026-10-19T12:41:07.000Z", "updated_at": "2026-10-19T12:41:07.000Z", "deleted_at": null, "reply": null } rating เป็นจำนวนเต็มระหว่าง 1 ถึง 5 หรือ null Booking.com ให้คะแนนเต็ม 10 เราจึงหารสอง ปัดเศษ และจำกัดช่วงไว้ที่ 1-5 Steam ไม่มีดาว มีแค่ "recommended" หรือ "not recommended" ซึ่งเราแมปเป็น 5 และ 1 บางแหล่งอนุญาตให้รีวิวได้โดยไม่ต้องให้คะแนนเลย กรณีนั้นฟิลด์จะเป็น null เราไม่เขียนค่า 0 เด็ดขาด เพราะมันดูเหมือนคะแนนจริงและทำให้ค่าเฉลี่ยตกลง
text และ title เป็น null ได้ รีวิวที่มีแต่คะแนนพบได้บ่อยบน app store และมีเพียงบางแพลตฟอร์มที่มีหัวข้อรีวิว เราไม่แต่งหัวข้อขึ้นจากประโยคแรก
url มีความหมายเฉพาะบนแพลตฟอร์มที่อ่านได้อย่างเดียว เมื่อเราโพสต์คำตอบกลับไม่ได้ url คือที่ที่ธุรกิจสามารถเข้าไปตอบกลับด้วยตัวเองได้ หาก client พยายามตอบกลับตามดี ข้อความ error จะส่ง URL เดียวกันนี้กลับมาด้วย
source มีอยู่เพราะ aggregator Viator ส่งกลับทั้งรีวิวที่เขียนบน Viator และบน Tripadvisor property manager หนึ่งตัวส่งรีวิวจาก Airbnb, Booking.com และ Vrbo ผ่านการเชื่อมต่อเดียว platform บอกว่ารีวิวมาผ่านการเชื่อมต่อไหน ส่วน source บอกว่ารีวิวถูกเขียนบนเว็บไหน
created_at กับ updated_at แยกจากกัน เพราะคนแก้รีวิวของตัวเอง รีวิวหนึ่งดาวที่ถูกแก้เป็นสี่ดาวควรถูกนับเป็นการอัปเดต ไม่ใช่รายการใหม่
reply เป็น object ที่มี status ไม่ใช่ string ค่า status ได้แก่ published, queued, failed หรือ unknown ตัวสุดท้ายต้องอธิบายเพิ่ม บางครั้งคำขอส่งออกไปยังแพลตฟอร์มแล้วแต่ไม่มีคำตอบกลับมา และแพลตฟอร์มไม่มีวิธีให้เราอ่านคำตอบกลับคืน การ retry อาจทำให้คำตอบเดียวกันถูกโพสต์ซ้ำสองครั้ง ภายใต้ชื่อของธุรกิจ เราจึงหยุด ทำเครื่องหมายเป็น unknown และแจ้งให้ client ตรวจสอบที่แพลตฟอร์มก่อนโพสต์อีกครั้ง status ที่บอกว่า "เราไม่รู้" มีประโยชน์กว่าการเดา
ขีดจำกัดความยาวของคำตอบกลับถูกตรวจสอบแยกตามแพลตฟอร์มก่อนเข้าคิว: 4,096 ไบต์บน Google Business Profile, 350 ตัวอักษรบน Google Play, 80 ตัวอักษรบน eBay emoji หนึ่งตัวนับเป็นหนึ่งตัวอักษรแต่กินสี่ไบต์ เราจึงนับ code point สำหรับขีดจำกัดแบบตัวอักษร และนับไบต์สำหรับขีดจำกัดแบบไบต์
ID ที่คงที่และการกำจัดข้อมูลซ้ำ
ข้อมูลซ้ำคือบั๊กแรกที่ client จะสังเกตเห็น กฎของเราง่ายมาก: connector ทุกตัวต้องส่งกลับ ID ของแพลตฟอร์มเองสำหรับรีวิวทุกฉบับ และฐานข้อมูลมี unique index บน (location_id, external_id) การ sync รีวิวเดียวกันครั้งที่สองจึงเป็นการอัปเดต ไม่ใช่การ insert ตำแหน่ง (location) ทำงานในลักษณะเดียวกัน ด้วย unique index บน (connection_id, external_id)
ส่วนที่ยากคือ "ID ของแพลตฟอร์มเอง" ไม่ได้มีอยู่เสมอไป:
- รีวิวของ Etsy ไม่มี ID ของตัวเอง รีวิวแต่ละฉบับผูกกับ transaction หนึ่งรายการพอดี เราจึงใช้ transaction ID เป็นรีวิว ID
- WordPress.org ไม่ให้รีวิว ID ใน feed รีวิวแต่ละฉบับคือ topic ในฟอรัม เราจึงใช้ topic slug
- หน้า Shopify App Store มี review content ID ฝังอยู่ใน HTML เราอาศัยค่านี้ โดยรับรู้ว่าการออกแบบหน้าใหม่อาจเปลี่ยนมัน
- Google Play มี ID จริง แต่ API ของมันส่งกลับเฉพาะรีวิวที่สร้างหรือแก้ไขในเจ็ดวันล่าสุด ประวัติที่เก็บไว้เป็นของเราเอง และเราอ่านซ้ำไม่ได้
Client ไม่เห็น platform ID เป็น primary key เลย พวกเขาได้รับ ID ของเราเองที่มี prefix บอกชนิดและส่วนลำดับเวลา (rev_01KJ…, loc_01KJ…, req_01KJ…) prefix ทำให้ ID ที่หลุดไปผิดที่เห็นได้ชัดใน log และการเรียงลำดับช่วยเรื่อง pagination: cursor เก็บ timestamp และ ID ของรายการสุดท้าย ทำให้ขอบของหน้าไม่ขยับแม้มีรีวิวใหม่เข้ามา
การเชื่อมต่อใหม่ ธุรกิจถอดการเชื่อมต่อบัญชีออกแล้วเชื่อมกลับใหม่ในอีกหนึ่งสัปดาห์ต่อมา ถ้าสร้าง location ใหม่จะทำให้รีวิวทุกฉบับซ้ำ แทนที่จะทำแบบนั้น location ที่ถูกถอดไม่เกิน 30 วันและมี external ID เดิมจะถูกเปิดใช้งานใหม่: ID เดิม ไม่มีรีวิวซ้ำ
การลบ รีวิวที่ถูกลบจากแพลตฟอร์มจะหายไปเงียบ ๆ ไม่มีอะไรแจ้งให้คุณทราบ ใน 84 แหล่ง เราอ่านประวัติทั้งหมดได้ 60 แหล่ง เราจึงอ่านซ้ำเป็นระยะ (ทุก 25 วันสำหรับ Google Business Profile ซึ่งข้อกำหนดไม่ให้เราเก็บเนื้อหาที่ยังไม่ยืนยันนานเกิน 30 วัน และรายสัปดาห์สำหรับแหล่งส่วนใหญ่ที่เหลือ) และทำเครื่องหมายรีวิวที่แพลตฟอร์มไม่ส่งกลับอีกด้วย deleted_at พร้อม webhook review.deleted มาตรการป้องกันสำคัญคือ: ถ้าการอ่านจบก่อนกำหนด เพราะ timeout หรือขีดจำกัดจำนวนหน้า เราจะไม่ทำเครื่องหมายอะไรเลย การตีความ "ฉันไม่เห็นมัน" ว่า "มันหายไปแล้ว" จะลบรีวิวจริงทิ้ง Google Play ถูกยกเว้นเพราะข้อจำกัดหน้าต่างเจ็ดวันของมัน
ทดสอบ contract กับ OpenAPI spec
contract ของเราคือเอกสาร OpenAPI 3.1 ที่มี 18 paths, 30 schemas และ 9 webhook events มีการทดสอบสองแบบที่ช่วยรักษาความถูกต้องของมัน
แบบแรกถูกและรันทุกครั้งที่ commit: enum ใน spec ต้องตรงกับในโค้ดเป๊ะ ๆ platform ID ใน spec ต้องเท่ากับรายการใน platform config และ webhook events ใน spec ต้องเท่ากับประเภท event ที่โค้ดส่งออกได้ client ที่ generate มาจะปฏิเสธค่า enum ที่ไม่รู้จัก ดังนั้นถ้าเพิ่มแพลตฟอร์มในโค้ดแต่ไม่ได้เพิ่มใน spec client เหล่านั้นจะพังตั้งแต่ sync แรก
แบบที่สองคือ test mode API key มีสองชนิดคือ pk_live_… และ pk_test_… ใช้กับเซิร์ฟเวอร์เดียวกัน key ทดสอบจะ route ทุกแพลตฟอร์มไปยัง test connector: location และรีวิวตัวอย่างแบบ deterministic ที่มีรูปร่างเหมือนของจริง (ร้านกาแฟบน Google, แอปบน App Store, โรงแรมบน Booking.com), คำตอบกลับที่ถูกยอมรับแต่ไม่เผยแพร่ที่ไหนเลย และบนแพลตฟอร์มที่อ่านได้อย่างเดียว ทุกรีวิวจะมี url เพราะเอกสารสัญญาไว้แบบนั้น ใครก็รัน contract ทั้งหมดได้ รวมถึง write paths โดยไม่กระทบบัญชีจริง
ตัวอย่างด้านล่างคือตัวอย่างที่อยู่ใน spec โดยแทน URL ด้วย example.com คำขอแบบ list:
GET /v1/reviews?platform=google&limit=1 Authorization: Bearer pk_test_… จะคืนรีวิวที่แสดงไว้ก่อนหน้านี้ใน data พร้อม next_cursor คำตอบกลับไปยังแพลตฟอร์มที่รองรับการตอบกลับจะถูกยอมรับด้วย 202 และรีวิวจะกลับมาพร้อมคำตอบในคิว (ละฟิลด์อื่น):
POST /v1/reviews/rev_01KJ8Q2M4T7HX3VB9CWD6NRZ5E/reply Authorization: Bearer pk_test_… Content-Type: application/json { "text": "Thanks Marta! We have added a second barista at lunch." } { "id": "rev_01KJ8Q2M4T7HX3VB9CWD6NRZ5E", "platform": "google", "reply": { "text": "Thanks Marta! We have added a second barista at lunch.", "created_at": null, "status": "queued", "error": null } } กรณีที่น่าสนใจคือความล้มเหลว error ทุกตัวมีรูปแบบเดียวกัน (type, code, message, retryable, request_id, docs_url) และบาง code เพิ่มฟิลด์ที่ client นำไปใช้ตัดสินใจได้ การตอบกลับรีวิว Yelp จะได้ 422 กลับมา:
{ "error": { "type": "invalid_request_error", "code": "reply_not_supported", "message": "Yelp has no reply API for third parties, so Prisma only reads its reviews. Answer this one on the platform: https://example.com/biz/example-cafe-madrid", "retryable": false, "request_id": "req_01KJ8T3C5D7E9F1G3H5J7K9M1N", "docs_url": "https://example.com/docs/errors#reply_not_supported", "platform": "yelp", "url": "https://example.com/biz/example-cafe-madrid" } } คำตอบกลับที่ยาวเกินขีดจำกัดของแพลตฟอร์มก็ได้ 422 เช่นกัน พร้อม code: "reply_too_long", platform: "google_play" และ max_length: 350 client ควร branch ที่ code ไม่ใช่ที่ message: message ไว้สำหรับคนอ่านและเปลี่ยนได้ตลอด
รูปแบบเดียวกันนี้ใช้กับ traffic จริงด้วย นี่คือ response จริงจาก production ต่อคำขอที่ไม่มี key (ตัด header บางส่วน และแทน docs URL):
HTTP/1.1 401 Unauthorized Content-Type: application/json Request-Id: req_01K6VVGDM8CFFJEQ3MNWWR582S {"error":{"type":"authentication_error","code":"missing_api_key","message":"Send your API key as \"Authorization: Bearer pk_live_…\".","retryable":false,"request_id":"req_01K6VVGDM8CFFJEQ3MNWWR582S","docs_url":"https://example.com/docs/errors#missing_api_key"}} request_id ใน body ตรงกับ header Request-Id สำหรับแต่ละ operation เราตรวจสอบ status code, ว่า body ผ่านการ validate กับ schema ของมัน (ฟิลด์รีวิวครบ 14 ฟิลด์ และ type รองรับ nullable ตามที่ประกาศ), รูปแบบ error ใน response ที่ไม่ใช่ 2xx ทุกตัว และ header Request-Id กับ rate-limit บน response สำเร็จ
รันการตรวจสอบชุดเดียวกันด้วย Apidog CLI
การตรวจสอบแบบนี้ใช้ได้กับ API ใดก็ตามที่แถมไฟล์ OpenAPI มาด้วย Apidog CLI import spec ให้ และ coding agent อย่าง Claude Code เขียนและรัน test case ตั้งค่าครั้งเดียว:
npm install -g apidog-cli@latest apidog login --with-token <YOUR_TOKEN> apidog skill install จากนั้นสั่ง agent ด้วย prompt เดียว:
Import ./openapi.json into Apidog project <projectId>. Create test cases for the list reviews and reply endpoints that assert the status code, that the body validates against its schema with all 14 review fields present, and that the Request-Id header is set. Add a case that replies to a Yelp review and expects 422 with code reply_not_supported. Run them against the test environment and summarize any failures. Agent จะ import spec, อ่าน schema ของ test case, validate payload, สร้าง test case และรันมัน:
apidog import --project <projectId> --format openapi --file ./openapi.json apidog cli-schema get test-case-create apidog cli-schema validate test-case-create --file case.json apidog test-case create --project <projectId> --file case.json apidog run --test-case <caseId> --project <projectId> -e <envId> -r cli,junit reporter แบบ junit เขียนไฟล์ที่ CI ของคุณอ่านได้ การรันชุดนี้จึงใช้เป็นเงื่อนไขบังคับในทุก pull request ได้ คู่มือ Apidog CLI CI/CD guide อธิบายการตั้งค่า pipeline อย่างละเอียด
บทเรียน
ออกแบบ "มี API" กับ "ตอบกลับได้" เป็นคุณสมบัติแยกกัน Atlassian และ Microsoft พิสูจน์แล้วว่า API อาจมีอยู่จริงแต่รับการตอบกลับไม่ได้ ถ้าใช้ flag เดียวสำหรับทั้งสองอย่าง เท่ากับสัญญาว่าจะตอบกลับได้ในกรณีที่เราส่งมอบไม่ได้
วางแผนรับสถานะ unknown ของการตอบกลับตั้งแต่ก่อนคำตอบแรกถูกส่งออก สถานะที่ยอมรับความไม่แน่นอนมีต้นทุนแค่ค่า enum เพิ่มหนึ่งตัว แต่คำตอบกลับซ้ำที่เปิดให้สาธารณะเห็นมีต้นทุนคือความไว้วางใจของลูกค้า
อย่าเชื่อว่า platform ID จะมีอยู่หรือคงที่ตลอด จดไว้ให้ชัดเจนในแต่ละ connector ว่า ID มาจากไหน และอะไรจะทำให้มันเปลี่ยน
ทดสอบ spec กับโค้ด ไม่ใช่แค่โค้ดกับ spec การทดสอบ enum ใช้โค้ดประมาณสิบบรรทัด แต่มันปกป้องความล้มเหลวที่สร้างความเสียหายแก่ client ที่ generate มาที่สุด





