เวอร์ชันของ API

ทุก path ขึ้นต้นด้วยเวอร์ชัน เช่น https://api.sukson.dev/v1/me ถ้าเรียกเวอร์ชันที่ไม่มี จะได้ 404 UNKNOWN_VERSION

ตอนนี้มีเวอร์ชันเดียวคือ v1 เพราะเวอร์ชันอยู่ใน path โค้ดที่เขียนไว้กับ v1 จึงไม่พังเพราะการเปลี่ยนแปลงใน v1 และเมื่อมีเวอร์ชันใหม่ v1 ยังใช้ได้ต่ออีกระยะหนึ่ง

สิ่งที่เพิ่มได้ใน v1 โดยไม่เปลี่ยนเวอร์ชัน

สิ่งเหล่านี้อาจเพิ่มเข้ามาใน v1 ได้ทุกเมื่อ

• endpoint ใหม่
• ฟิลด์ใหม่ในคำตอบหรือใน event
• ฟิลด์ใหม่แบบไม่บังคับในคำขอ
• ค่าใหม่ของ enum เช่น kind, trigger, status และ type ของ event
• code ใหม่ของข้อผิดพลาด
• หัว HTTP ใหม่

โค้ดของคุณจึงควร ข้ามฟิลด์และค่าที่ไม่รู้จัก และตอบ 200 เมื่อเจอ event type ที่ไม่รู้จัก

สิ่งที่ต้องขึ้นเวอร์ชันใหม่ (breaking change)

การเปลี่ยนที่อาจทำให้โค้ดเดิมพัง จะมาในเวอร์ชันใหม่เท่านั้น เช่น

• ลบหรือเปลี่ยนชื่อ endpoint หรือฟิลด์
• เปลี่ยนชนิดหรือความหมายของฟิลด์
• ฟิลด์ที่ไม่บังคับกลายเป็นบังคับ
• เปลี่ยนรูปแบบลายเซ็น webhook (ลายเซ็นมีเวอร์ชันของตัวเองคือ v1=)

การเลิกใช้เวอร์ชันเก่า

• เมื่อมี /v2 แล้ว /v1 ยังใช้ได้ต่ออีกระยะหนึ่ง ระยะเวลาจะประกาศพร้อมกับ /v2
• วันเลิกใช้ประกาศล่วงหน้าใน บันทึกการเปลี่ยนแปลง
• หลังวันเลิกใช้ เวอร์ชันนั้นได้ 404 UNKNOWN_VERSION

Bot API เดิม (/bot-api/*)

Bot API เดิมบน api.sukson.com/bot-api/* (เช่น getMe, sendMessage) ยังใช้ได้ในช่วงเปลี่ยนผ่าน และจะปิดหลังจากประกาศ ตารางนี้บอกว่าแต่ละคำสั่งเดิมย้ายไปที่ไหนใน v1

Bot API เดิม	API v1
GET /bot-api/getMe	GET /v1/me
GET /bot-api/getChats	GET /v1/me/chats
POST /bot-api/sendMessage	POST /v1/chats/{chat_id}/messages
POST /bot-api/editMessage	PATCH /v1/messages/{message_id}
POST /bot-api/deleteMessage	DELETE /v1/messages/{message_id}
POST /bot-api/setWebhook	PUT /v1/me/webhook
GET /bot-api/getWebhookInfo	GET /v1/me/webhook
POST /bot-api/deleteWebhook	DELETE /v1/me/webhook
POST /bot-api/setCommands	PUT /v1/me/commands

ที่ต่างกันหลัก ๆ: คำตอบของ v1 ไม่ห่อด้วย {success, data} และข้อผิดพลาดเป็น {message, code, details} ส่วน token และรหัสลับ webhook ใช้ชุดเดิมได้เลย