การกำหนดเวอร์ชัน

การกำหนดเวอร์ชัน

Public API กำหนดเวอร์ชันไว้ใน URL path: ทุก route อยู่ภายใต้ /api/v1/... ซึ่งปัจจุบันเป็นเวอร์ชันเดียวที่มี

นโยบาย

• เราจะเพิ่มเฉพาะฟิลด์ endpoint และประเภทเหตุการณ์ใหม่ให้กับ v1 เท่านั้น — การเปลี่ยนแปลงแบบเพิ่มเติมที่ไม่ทำลายความเข้ากันได้จะถูกปล่อยออกโดยไม่มีการเปลี่ยนเวอร์ชัน
• การเปลี่ยนแปลงที่ทำลายความเข้ากันได้จริงๆ (ลบฟิลด์ เปลี่ยนชนิดหรือความหมายของฟิลด์ ลบ endpoint) จะถูกปล่อยเป็นเวอร์ชันใหม่ (/api/v2/...) เท่านั้น ไม่ใช่การแก้ไข v1 ในที่เดิม
• v1 จะทำงานต่อไปโดยไม่มีการเปลี่ยนแปลงที่ทำลายความเข้ากันได้แบบไม่แจ้งล่วงหน้า ตราบใดที่ยังไม่ถูกประกาศเลิกใช้อย่างเป็นทางการ (ดูด้านล่าง)

วงจรการเลิกใช้งาน

เมื่อเราจำเป็นต้องเลิกใช้ route หรือทั้งเวอร์ชัน เราจะประกาศล่วงหน้าก่อนถึงวันปิดใช้งาน และทำเครื่องหมายทุกการตอบกลับจาก route ที่เลิกใช้แล้วด้วย header สองตัวตามมาตรฐาน RFC 8594:

Header	ความหมาย
Deprecation	true หรือ HTTP-date ที่ระบุว่าเมื่อใด route นี้เริ่มถูกเลิกใช้
Sunset	HTTP-date — route จะหยุดให้บริการหลังจากวันนี้
Link: <url>; rel="deprecation"	ไม่บังคับ — ลิงก์ไปยังคู่มือการย้ายระบบสำหรับ route ที่เลิกใช้

HTTP/1.1 200 OK
Deprecation: true
Sunset: Wed, 01 Apr 2026 00:00:00 GMT
Link: <https://docs.clienta.ai/api/migration-v2>; rel="deprecation"

ตรวจสอบ header เหล่านี้ในระบบจริง

อย่าพึ่งพาแค่อีเมลประกาศ release notes เพียงอย่างเดียว — ตรวจสอบ header Sunset ในการตอบกลับจาก route ที่คุณเรียกใช้จริง หากพบ ให้วางแผนการย้ายระบบก่อนถึงวันที่ระบุ หลังจากวันนั้น route จะหยุดให้บริการ (404)

เราจะให้ระยะเวลาแจ้งล่วงหน้าขั้นต่ำก่อนที่วันที่ Sunset จะมีผล — ระยะเวลาที่แน่นอนจะระบุไว้ในประกาศการเลิกใช้งานนั้นๆ เอง เนื่องจากขึ้นอยู่กับว่าการเปลี่ยนแปลงนั้นส่งผลกระทบมากน้อยเพียงใด

Request-Id

ทุกการตอบกลับ — ไม่ว่าจะสำเร็จหรือผิดพลาด — จะมี header Request-Id แนบมาด้วย ใช้ค่านี้เมื่อติดต่อฝ่ายสนับสนุนเกี่ยวกับคำขอใดคำขอหนึ่งโดยเฉพาะ เป็นวิธีที่เร็วที่สุดที่เราจะค้นหาคำขอนั้นในบันทึกของเรา

Request-Id: 1f2e4b6a-9c3d-4a11-8b7e-6d5f0a1c2b3d

รูปแบบการตอบกลับข้อผิดพลาด

ทุกการตอบกลับที่เป็นข้อผิดพลาด (สถานะที่ไม่ใช่ 2xx) จาก /api/v1 ใช้รูปแบบ JSON เดียวกัน:

{
  "error": {
    "type": "VALIDATION_ERROR",
    "message": "Invalid request. Please check your input and try again.",
    "requestId": "1f2e4b6a-9c3d-4a11-8b7e-6d5f0a1c2b3d"
  }
}

requestId จะตรงกับค่า header Request-Id ของการตอบกลับนั้นเสมอ

การแบ่งหน้า

Endpoint ที่แสดงรายการใช้การแบ่งหน้าแบบ cursor — ไม่ใช้เลขหน้าหรือ offset ซึ่งอาจคลาดเคลื่อนได้เมื่อมีการเขียนข้อมูลพร้อมกัน

GET /api/v1/conversations?limit=20

{
  "success": true,
  "data": [ /* ... */ ],
  "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI2LTA3LTE2VDA0OjAwOjAwLjAwMFoiLCJpZCI6ImNvbnZfMTIzIn0"
}

• limit ค่าเริ่มต้นคือ 20 และถูกจำกัดไว้สูงสุดที่ 100 — ค่าที่นอกช่วงจะถูกปรับให้อยู่ในช่วงโดยอัตโนมัติ ไม่ถูกปฏิเสธ
• ส่งค่า nextCursor จากการตอบกลับก่อนหน้าเป็นพารามิเตอร์ cursor เพื่อดึงหน้าถัดไป
• nextCursor จะเป็น null เมื่อถึงหน้าสุดท้าย
• cursor เป็นโทเคนแบบ opaque ที่เข้ารหัส base64url — อย่าพยายามแยกวิเคราะห์หรือสร้างเองด้วยมือ cursor ที่เสียหาย/ถูกดัดแปลงจะถูกปฏิเสธด้วย 400 VALIDATION_ERROR แทนที่จะรีเซ็ตกลับไปหน้าแรกโดยไม่แจ้งเตือน