ภาพรวมและแนวคิด API

Base URL การยืนยันตัวตนของแอป รูปแบบคำตอบ UUID เวลา และรหัสสถานะ HTTP

ภาพรวม

API สำหรับนักพัฒนาให้แอปของคุณ (เว็บ บอท หรือโปรแกรมหลังบ้าน) ทำสองอย่างได้ โดยแต่ละอย่างแยกเอกสารและแยกการตั้งค่ากัน:

ระบบ	ทำอะไร	เอกสาร
Auth	ให้ผู้เล่นพิสูจน์ว่าเป็นเจ้าของบัญชี Minecraft (uuid และชื่อ) แบบ OAuth	Sign in with Minecraft
Instance	ดู เพิ่ม ลบผู้เล่นของ Instance ที่ให้สิทธิ์แอปไว้	Instance API: ผู้เล่น

ชนิดข้อมูล (TypeScript) ทั้งหมดและตารางข้อผิดพลาดรวมอยู่ที่ อ้างอิงชนิดข้อมูลและข้อผิดพลาด วิธีสร้างแอปบนหน้าจออยู่ที่ Developer zone

เริ่มต้นใน 3 ขั้นตอน

สร้างแอปในเมนู Developer แล้วเก็บ client_id กับ client_secret
ถ้าจะใช้ Instance API: ในหน้าแอป ส่วน Instance เลือก Instance และสิทธิ์ที่ต้องการ
ถ้าจะใช้ Auth: ตั้งโหมด (Redirect หรือ Webhook) และ Redirect URI หรือ Webhook URL ในส่วน Auth

ที่อยู่ของ API

url

https://api-dms-launcher.mckimkung.in.th/api/v1

endpoint ทุกตัวในเอกสารนี้ต่อท้ายที่อยู่นี้ (เช่น GET /instances หมายถึง GET ตามด้วย Base URL ข้างบนแล้วต่อ /instances) ส่วนหน้า /authorize ที่ส่งผู้เล่นไปยืนยันตัวตนไม่ใช่ APIแต่เป็นหน้าเว็บของ Dashboard (โดเมนของเว็บที่คุณเปิดอยู่ ไม่ใช่โดเมนของ API) ดู Sign in with Minecraft

การยืนยันตัวตนของแอป

endpoint ใต้ /api/v1 ทุกตัวใช้ HTTP Basic โดยใช้ client_id เป็น username และ client_secret เป็น password:

http

Authorization: Basic base64(client_id + ":" + client_secret)

bash

# curl สร้าง header ให้เองด้วย -u client_id:client_secret
curl -u "$CLIENT_ID:$CLIENT_SECRET" https://api-dms-launcher.mckimkung.in.th/api/v1/instances

// Node.js
const auth = "Basic " + Buffer.from(CLIENT_ID + ":" + CLIENT_SECRET).toString("base64");
const res = await fetch(API + "/api/v1/instances", { headers: { Authorization: auth } });

กรณี	ผลลัพธ์
ไม่มี header หรือไม่ใช่ Basic	`401` พร้อมข้อความบอกรูปแบบที่ถูกต้อง
client_id ไม่มีอยู่ หรือ secret ผิด	`401` `Invalid client credentials` (ข้อความเดียวกันทั้งสองกรณี เพื่อให้เดา client_id ไม่ได้)
secret เดิมหลังกดสร้างใหม่	`401` ทันที

เก็บ secret ฝั่ง server เท่านั้น

อย่าใส่ client_secret ในเว็บหน้าบ้าน แอปมือถือ หรือ repository สาธารณะ ถ้าหลุดให้กด สร้างใหม่ ในหน้าแอป

ข้อกำหนดทั่วไปของ API

หัวข้อ	ข้อกำหนด
รูปแบบข้อมูล	JSON เข้ารหัส UTF-8 ทั้งคำขอและคำตอบ คำขอที่มี body ต้องส่ง `Content-Type: application/json`
ผลสำเร็จ	HTTP 2xx กับ `{ "statusCode": 200, "data": ... }` (ดูชนิด `ApiResponse<T>`)
ข้อผิดพลาด	HTTP 4xx / 5xx กับ `{ "statusCode": 404, "message": "...", "error": "Not Found" }` ข้อผิดพลาดการตรวจข้อมูลมีรายการ `errors` เพิ่ม ดู อ้างอิง
UUID	ขาเข้ารับได้ทั้งมีขีดและไม่มีขีด ตัวพิมพ์เล็กหรือใหญ่ ขาออกเป็นตัวพิมพ์เล็ก 32 หลัก ไม่มีขีด เสมอ เช่น `069a79f444e94726a5befca90e38aaf5`
เวลา	สตริง ISO 8601 เวลา UTC เช่น `2026-10-06T08:30:00.000Z`
ชื่อ Instance	ใน path ใช้ฟิลด์ `name` ของ Instance (ตัวระบุที่ไม่ซ้ำ เช่น `wanwera`) ตรงตัวพิมพ์เล็กใหญ่ ไม่ใช่ `title` ที่ใช้แสดง
การแบ่งหน้า	ยังไม่มี (รายการส่งกลับทั้งหมด) การเขียนจำกัดครั้งละไม่เกิน 100 รายการ
Rate limit	ปัจจุบันระบบยังไม่จำกัดจำนวนครั้ง แต่ควรควบคุมการเรียกของคุณเอง (เช่นไม่ poll ถี่เกินวินาทีละครั้ง) เพราะเกณฑ์อาจเปลี่ยนในอนาคต
เวอร์ชัน	เวอร์ชันอยู่ใน path (`/api/v1`) การเปลี่ยนที่ทำให้แอปเดิมพังจะออกเป็นเวอร์ชันใหม่ ส่วนการเพิ่มฟิลด์ใหม่ในคำตอบอาจเกิดขึ้นได้ ให้ละเลยฟิลด์ที่ไม่รู้จัก

รหัสสถานะ HTTP ที่พบ

รหัส	ความหมาย
`200`	สำเร็จ (รวมถึงคำขอเขียนที่ประมวลผลแล้ว ดูตัวเลขในคำตอบ)
`400`	ข้อมูลที่ส่งไม่ถูกต้อง หรือ code ใช้ไม่ได้
`401`	ยืนยันตัวตนของแอปไม่ผ่าน
`403`	แอปได้รับ Instance นี้ แต่ไม่มีสิทธิ์ (scope) ที่ทำรายการนี้
`404`	ไม่พบ Instance หรือแอปไม่ได้รับ Instance นี้ (สองกรณีนี้ตอบเหมือนกัน)
`5xx`	ข้อผิดพลาดฝั่งระบบ ลองใหม่ภายหลัง