ระบบจัดการแข่งขัน EasyKidsEasyKids

คู่มือ REST API ภาษาไทย

เชื่อมต่อข้อมูลการแข่งขันสดและจัดการระบบ EasyKids ผ่าน JSON API รุ่น 1
GET /api

API ใช้ URL ภายใต้ /api ส่งและรับข้อมูล JSON พร้อมรูปแบบผลลัพธ์ที่สม่ำเสมอ

Base URLhttps://results.easykidsrobotics.com/api

เริ่มใช้งานอย่างรวดเร็ว

  1. สร้าง Bearer Token ของผู้ดูแลจากเมนู “การเข้าถึง API”
  2. ส่ง Token พร้อมคำขอ API ของการแข่งขันทุกครั้ง
  3. ส่งหัวข้อ Accept: application/json และ Content-Type: application/json เมื่อมี Request Body
  4. เพิ่ม ?lang=th หรือส่ง Accept-Language: th-TH เพื่อรับข้อความและ Validation ภาษาไทย

การยืนยันตัวตนและสิทธิ์

REST API ของการแข่งขันทุก Endpoint ต้องใช้ Bearer Token ของผู้ดูแล ส่วนผู้ชมเข้าดูได้เฉพาะลิงก์เว็บไซต์ส่วนตัวที่ผู้ดูแลสร้างให้

Authorization: Bearer YOUR_ADMIN_TOKEN
Accept: application/json
Content-Type: application/json
Accept-Language: th-TH
เก็บ Token ไว้ฝั่งเซิร์ฟเวอร์เท่านั้น ห้ามใส่ใน JavaScript สาธารณะ URL หรือ Git

รูปแบบ Response

เมื่อสำเร็จ ข้อมูลอยู่ใน data และรายการแบบแบ่งหน้าจะมี current_page, per_page, total และ links

{
  "success": true,
  "data": { "id": "...", "status": "LIVE" }
}

เมื่อไม่สำเร็จ success เป็น false, error.message อธิบายสาเหตุ และ Validation จะมี error.fields แยกตามชื่อฟิลด์

{
  "success": false,
  "error": {
    "message": "ข้อมูลที่ส่งมาไม่ถูกต้อง",
    "fields": { "name": ["กรุณากรอก ชื่อ"] }
  }
}

REST Resource สำหรับอ่านข้อมูล

ต้องใช้ Bearer Token ของผู้ดูแล
GET
MethodEndpointรายละเอียดสิทธิ์
GET/api/healthตรวจสอบสถานะบริการสาธารณะ
GET/api/tournamentsรายการแข่งขันพร้อมตัวกรองและ Paginationผู้ดูแล
GET/api/tournaments/{id}รายละเอียดการแข่งขัน รวมรอบ ทีม แมตช์ และอันดับผู้ดูแล
GET/api/tournaments/{id}/participantsรายชื่อผู้เข้าแข่งขันทั้งหมดผู้ดูแล
GET/api/tournaments/{id}/participants/{participant}ผู้เข้าแข่งขันหนึ่งราย สมาชิก อันดับ และผล Rankingผู้ดูแล
GET/api/tournaments/{id}/matchesรายการแมตช์ทั้งหมดผู้ดูแล
GET/api/tournaments/{id}/matches/{match}รายละเอียดแมตช์หนึ่งรายการผู้ดูแล
GET/api/tournaments/{id}/standingsตารางอันดับทั้งหมดผู้ดูแล
GET/api/tournaments/{id}/standings/{participant}อันดับของผู้เข้าแข่งขันหนึ่งรายผู้ดูแล

ตัวกรองและ Pagination

GET /tournaments รองรับ status, format, search และ per_page ตั้งแต่ 1–100 รายการ การสร้างหรือแก้ไข Double Elimination รองรับ grand_final_matches ค่า 1 หรือ 2

REST Resource สำหรับผู้ดูแล

Bearer Token
MethodEndpointรายละเอียดสิทธิ์
POST/api/tournamentsสร้างการแข่งขันผู้ดูแล
PUT / PATCH/api/tournaments/{id}แทนที่ / แก้ไขข้อมูลการแข่งขันผู้ดูแล
DELETE/api/tournaments/{id}ลบการแข่งขันและข้อมูลที่เกี่ยวข้องผู้ดูแล
POST/api/tournaments/{id}/participantsเพิ่มผู้เข้าแข่งขันผู้ดูแล
PUT / PATCH/api/tournaments/{id}/participants/{participant}แทนที่ / แก้ไขผู้เข้าแข่งขันผู้ดูแล
DELETE/api/tournaments/{id}/participants/{participant}ลบผู้เข้าแข่งขันผู้ดูแล
POST/api/tournaments/{id}/participants/importนำเข้า CSV ด้วย multipart/form-data ชื่อ csv_fileผู้ดูแล
PATCH/api/tournaments/{id}/share-linkเปลี่ยนลิงก์ผู้ชมโดยส่ง share_slugผู้ดูแล
PATCH/api/tournaments/{id}/statusเปลี่ยนเป็น LIVE, COMPLETED หรือ ARCHIVED ตามลำดับที่ถูกต้องผู้ดูแล
PUT/api/tournaments/{id}/matches/{match}/resultบันทึกหรือแก้ไข score_a และ score_b โดยส่งค่าผลเดิมซ้ำได้อย่างปลอดภัยผู้ดูแล
POST/api/tournaments/{id}/participants/{participant}/attemptsบันทึกผล Ranking โดยส่ง attempt_numberผู้ดูแล
PUT/api/tournaments/{id}/participants/{participant}/attempts/{number}บันทึกผล Ranking ตามหมายเลขครั้งใน URLผู้ดูแล

Endpoint ควบคุมสถานะ (รองรับระบบเดิม)

แนะนำให้ระบบใหม่ใช้ PATCH /status ส่วน Endpoint /start, /complete และ /archive ยังคงใช้งานได้เพื่อความเข้ากันได้

MethodEndpointรายละเอียดสิทธิ์
POST/api/tournaments/{id}/startเริ่มแข่งขันและสร้างสายผู้ดูแล
POST/api/tournaments/{id}/completeจบการแข่งขันเมื่อผลครบผู้ดูแล
POST/api/tournaments/{id}/archiveเก็บการแข่งขันที่จบแล้วผู้ดูแล
POST/api/tournaments/{id}/matches/{match}/resultบันทึกผลคะแนนแบบเดิมผู้ดูแล

ตัวอย่าง Request

ค้นหาและกรองการแข่งขัน

curl "https://results.easykidsrobotics.com/api/tournaments?format=ROUND_ROBIN&search=EasyKids&per_page=20&lang=th" \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN"

สร้างการแข่งขัน

curl -X POST "https://results.easykidsrobotics.com/api/tournaments" \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept-Language: th-TH" \
  -d '{"name":"EasyKids 2026","competition":"Robot Challenge","division":"Junior","format":"DOUBLE_ELIMINATION","seeding_method":"REGISTRATION_ORDER","grand_final_matches":2}'

ตั้งลิงก์ผู้ชมแบบสั้น

curl -X PATCH "https://results.easykidsrobotics.com/api/tournaments/{id}/share-link" \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"share_slug":"easykids-final-26"}'

เปลี่ยนสถานะด้วย REST status resource

curl -X PATCH "https://results.easykidsrobotics.com/api/tournaments/{id}/status" \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status":"LIVE"}'

บันทึกหรือแก้ไขผลแมตช์ด้วย PUT

curl -X PUT "https://results.easykidsrobotics.com/api/tournaments/{id}/matches/{match}/result" \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"score_a":3,"score_b":1}'

แก้ไขคะแนนของแมตช์ที่จบแล้วได้ระหว่างการแข่งขันสถานะ LIVE หากผู้ชนะเปลี่ยน ระบบจะอัปเดตแมตช์ปลายทางที่ยังไม่เริ่มให้อัตโนมัติ และจะปฏิเสธเมื่อแมตช์ปลายทางเริ่มแล้ว

HTTP Status ที่ใช้

200อ่านหรือแก้ไขสำเร็จ
201สร้าง Resource สำเร็จ
401ไม่มี Token หรือ Token ไม่ถูกต้อง
403บัญชีไม่มีสิทธิ์ผู้ดูแล
404ไม่พบ Resource ที่ต้องการ
422ข้อมูลไม่ผ่าน Validation หรือสถานะการแข่งขันไม่อนุญาต
429ส่งคำขอถี่เกินกำหนด