SPK School Extension API · v1

ต่อยอดระบบโรงเรียนผ่าน API ที่ปลอดภัยและมีสัญญาคงที่

เอกสารสำหรับนักพัฒนา ระบบภายนอก และ AI agents ใช้ OpenAPI 3.1, API key แบบ least privilege, จำกัดขอบเขตตามห้อง และไม่ต้องแจก Supabase service-role key

เปิด OpenAPI JSON อ่านฉบับ Markdown เริ่มใช้งานเข้าสู่ระบบ

Least privilege

ผู้ดูแลเลือก scope, ห้อง, วันหมดอายุ, origin และ rate limit ให้แต่ละ client

AI-ready

OpenAPI 3.1 พร้อม operationId และ schema ใช้สร้าง client หรือให้ AI อ่านได้โดยตรง

Event-driven

Signed webhook แบบ HMAC ใช้ delivery ID เดิมเมื่อ retry เพื่อรองรับ idempotency

Quick start

  1. 1. ขอให้ผู้ดูแลสร้าง API client ที่หน้า “นักพัฒนาและระบบเสริม” โดยเลือกสิทธิ์เท่าที่จำเป็น
  2. 2. คัดลอกคีย์ spk_live_… ตอนที่แสดงครั้งเดียว แล้วเก็บไว้ใน secret manager ของ backend
  3. 3. ส่งคีย์ผ่าน Authorization: Bearer จาก backend เท่านั้น ห้ามฝังใน browser, mobile bundle, URL หรือ Git
curl --fail-with-body \
  -H "Authorization: Bearer $SPK_API_KEY" \
  "https://<your-domain>/api/v1/students?limit=50"

ผลสำเร็จอยู่ใต้ data; รายการแบ่งหน้ามี meta.next_cursor ซึ่งต้องส่งกลับเป็น cursor โดยไม่แก้ไขค่าเอง

Endpoints

GET/api/v1/studentsstudents:read

รายชื่อนักเรียนแบบ cursor pagination; กรองห้อง สถานะ และ updated_since

GET/api/v1/students/{id}students:read

โปรไฟล์นักเรียนแบบลดฟิลด์และไม่เปิดเผยข้อมูลอ่อนไหว

GET/api/v1/students/{id}/statusstudents:read

สถานะการศึกษาในปัจจุบัน

GET/api/v1/students/{id}/enrollmentsenrollments:read

ประวัติปีการศึกษา ห้อง และเลขที่

GET/api/v1/students/{id}/conductconduct:read

รายการคะแนนพฤติกรรมแบบแบ่งหน้า

GET/api/v1/students/{id}/attendanceattendance:read

การมาเรียนตามช่วงวันที่ สูงสุด 366 วัน

GET/api/v1/sectionssections:read

รายการห้องเรียนแบบแบ่งหน้า

GET/api/v1/sections/{id}/studentssections:read

รายชื่อนักเรียนที่กำลังเรียนในห้อง

POST/api/v1/extensions/exchangeone-time token

แลก launch token อายุสั้นสำหรับระบบเสริม

Scopes

students:read
ข้อมูลประจำตัวขั้นต่ำและสถานะนักเรียน
enrollments:read
ประวัติการลงทะเบียนเรียน
conduct:read
รายการคะแนนพฤติกรรม
attendance:read
ข้อมูลการมาเรียน
sections:read
ข้อมูลห้องและ roster

Errors และ retry

{
  "error": {
    "code": "insufficient_scope",
    "message": "ต้องมี scope students:read",
    "request_id": "…"
  }
}

ใช้ exponential backoff เฉพาะ network error, 429 และ 503 ไม่ retry 401/403 จนกว่าจะแก้คีย์หรือสิทธิ์ ใช้ request_id แจ้งผู้ดูแลโดยไม่ส่ง API key หรือข้อมูลนักเรียน

Versioning และความเป็นส่วนตัว

  • Breaking change จะออก path ใหม่ เช่น /api/v2; v1 จะไม่เปลี่ยนความหมายหรือลบ field โดยไม่ประกาศ
  • ประกาศยกเลิกอย่างน้อย 90 วัน พร้อมวัน sunset และ migration guide
  • ไม่ส่งเลขบัตรประชาชน password hash ข้อมูลผู้ปกครอง บันทึกทางการแพทย์ หรือ secrets
  • ทุก data request ถูก audit, จำกัด rate และตอบ Cache-Control: private, no-store
  • CORS เป็น defense-in-depth เท่านั้น ไม่ทำให้ long-lived API key ปลอดภัยใน JavaScript ฝั่ง browser