ระนาบควบคุมที่สงบกว่า

โมเดลทรัพยากรที่ชัดเจน

การเชื่อมต่อควรทำงานกับตัวระบุเซิร์ฟเวอร์ ภูมิภาค อิมเมจ แพ็กเกจ และการดำเนินการที่ชัดเจน คำขอสร้างและติดตั้งใหม่ควรคืนค่าการดำเนินการที่สามารถตรวจสอบจนเสร็จสมบูรณ์ คำขอ HTTP ที่สำเร็จไม่ใช่สิ่งเดียวกับเครื่องที่พร้อมใช้งาน

ข้อมูลรับรองที่มีงานจำกัด

โทเคน API ควรเพิกถอนได้อย่างอิสระและจำกัดเฉพาะทรัพยากรและการกระทำขั้นต่ำที่จำเป็น จัดเก็บไว้ในตัวจัดการความลับหรือสภาพแวดล้อมที่ได้รับการป้องกัน อย่าส่งโทเคนไปยังเบราว์เซอร์เพียงเพื่อหลีกเลี่ยงการเขียนแบ็กเอนด์เล็ก ๆ

การลองใหม่ต้องปลอดภัย

การหมดเวลาของเครือข่ายอาจเกิดขึ้นได้หลังจากการดำเนินการได้รับการยอมรับ ใช้คีย์ idempotency สำหรับคำขอสร้างและคำขอที่อ่อนไหวต่อการชำระเงิน ตรวจสอบสถานะการดำเนินการ และเคารพขีดจำกัดอัตรา การลองใหม่ควรแก้ไขความไม่แน่นอน ไม่ใช่สร้างเซิร์ฟเวอร์ที่เรียกเก็บเงินได้เพิ่มเติม

ตรวจสอบความเข้ากันได้ก่อนการผสานรวม

ตรวจสอบเวอร์ชัน API ที่เผยแพร่ รูปแบบการยืนยันตัวตน รูปแบบข้อผิดพลาด การแบ่งหน้า ขีดจำกัดอัตรา และขอบเขตโทเค็นก่อนสร้างการเชื่อมต่อ ใช้เฉพาะแพ็กเกจ KoalaVPS SDK ที่เผยแพร่แล้วจากลิงก์เผยแพร่ที่ตรวจสอบแล้วเท่านั้น

แผนงาน API

แผนงาน API ครอบคลุมการค้นพบแคตตาล็อก การยืนยันตัวตน สถานะบัญชี การเรียกเก็บเงินด้วยคริปโต วงจรชีวิตเซิร์ฟเวอร์ คีย์ SSH สาธารณะ และเว็บฮุก เส้นทางด้านล่างอธิบายสัญญาของอินเทอร์เฟซ การเข้าถึงในโปรดักชันยังไม่พร้อมใช้งาน

เส้นทางการยืนยันตัวตนและบัญชี

สัญญา API แยกเซสชันการเข้าสู่ระบบและคีย์ API ตรวจสอบสคีมาการตอบกลับ ข้อผิดพลาด อายุการใช้งานโทเค็น และการดำเนินการกู้คืนที่รองรับเทียบกับเวอร์ชันที่เผยแพร่สำหรับการเชื่อมต่อของคุณ

• POST /v1/auth/register
• POST /v1/auth/login
• POST /v1/auth/login/totp
• POST /v1/auth/token/refresh
• POST /v1/auth/recover
• GET /v1/auth/sessions
• DELETE /v1/auth/sessions/{token_id}
• POST /v1/auth/totp/setup
• POST /v1/auth/totp/enable
• POST /v1/auth/totp/disable
• POST /v1/auth/password
• POST /v1/auth/api-keys
• GET /v1/auth/api-keys
• DELETE /v1/auth/api-keys/{key_id}
• GET /v1/account
• PATCH /v1/account
• GET /v1/account/usage
• GET /v1/account/audit-log

เส้นทางแคตตาล็อกและการเรียกเก็บเงิน

การอ่านแคตตาล็อกไม่ควรต้องชำระเงิน การสร้างการชำระเงินต้องใช้ขอบเขตการเรียกเก็บเงินที่จำกัด สถานะใบแจ้งหนี้ที่ชัดเจน และการจัดการแบบ idempotent การยืนยันต้องเสร็จสมบูรณ์ก่อนเปิดใช้งานบริการ

• GET /v1/catalog
• GET /v1/catalog/vps
• GET /v1/catalog/dedicated
• GET /v1/catalog/regions
• GET /v1/catalog/images
• GET /v1/catalog/{code}
• GET /v1/billing/coins

เส้นทางเซิร์ฟเวอร์และการเข้าถึง

วงจรชีวิตจำเป็นต้องมีการยืนยันอย่างชัดเจนสำหรับการดำเนินการยกเลิกและติดตั้งใหม่ คีย์ SSH ส่วนตัวควรอยู่ที่ไคลเอนต์ บริการต้องการเพียงคีย์สาธารณะที่คู่กันเท่านั้น

• POST /v1/servers
• GET /v1/servers
• GET /v1/servers/{order_number}
• PATCH /v1/servers/{order_number}
• DELETE /v1/servers/{order_number}
• POST /v1/ssh-keys
• GET /v1/ssh-keys
• GET /v1/ssh-keys/{id}
• DELETE /v1/ssh-keys/{id}

เหตุการณ์และข้อมูลสาธารณะ

เว็บฮุกต้องมีลายเซ็นที่ตรวจสอบได้ การลองใหม่แบบจำกัดจำนวน และการป้องกันการเล่นซ้ำ ปลายทางความน่าเชื่อถือสาธารณะควรส่งคืนหลักฐานจริงที่ระบุวันที่ ไม่ใช่การรับประกันแบบสังเคราะห์

• POST /v1/webhooks
• GET /v1/webhooks
• DELETE /v1/webhooks/{id}
• POST /v1/webhooks/{id}/test
• GET /v1/transparency/canary
• GET /v1/transparency/peering
• GET /v1/transparency/status
• GET /v1/agents/directory
• POST /v1/agents/directory

การอนุญาตและขีดจำกัดทราฟฟิก

รูปแบบขอบเขตสิทธิ์ที่เสนอประกอบด้วย read, servers, billing และ full โดยมีคีย์ที่ใช้งานได้สูงสุดสิบรายการต่อบัญชี สัญญา API เสนองบประมาณคำขอที่ 120 ต่อนาที และ 3,000 ต่อชั่วโมงสำหรับคีย์ API และ 30 ต่อนาทีสำหรับทราฟฟิกสาธารณะ ตรวจสอบ HTTP 429, Retry-After และช่วงเวลาการบังคับใช้ในเอกสาร API ที่เผยแพร่แล้ว งบประมาณตามแผนงานเหล่านี้ไม่ใช่คำมั่นเรื่องความจุในการใช้งานจริง

• POST /v1/oauth/register
• POST /v1/oauth/token
• POST /v1/oauth/revoke
• GET /v1/oauth/introspect

SDK และการเผยแพร่โปรโตคอล

แผนงานการผสานรวมประกอบด้วย REST, ปลายทาง MCP แบบโฮสต์, แพ็กเกจ stdio ที่มีเวอร์ชัน, SDK และ CLI ตรวจสอบความพร้อมของรีลีส รันไทม์ที่รองรับ เช็กซัม และความเข้ากันได้กับ API ก่อนติดตั้งไคลเอนต์ การดาวน์โหลดสำหรับโปรดักชันยังไม่พร้อมใช้งาน

ทรัพยากร API จัดกลุ่มตามความรับผิดชอบ

API ที่ตั้งใจไว้แยกการเข้าถึงบัญชี การอ่านแคตตาล็อก การเรียกเก็บเงิน วงจรชีวิตเซิร์ฟเวอร์ คีย์ SSH และการเรียกกลับ การเรียกแบบอ่านอย่างเดียวไม่ควรสร้างคำสั่งซื้อ และข้อมูลรับรองการเรียกเก็บเงินไม่ควรอนุญาตการเปลี่ยนแปลงความปลอดภัยของบัญชีโดยอัตโนมัติ นี่อธิบายสัญญาการเชื่อมต่อ ไม่มีปลายทางการจัดเตรียมสำหรับการใช้งานจริงและ SDK ที่เผยแพร่แล้วผ่านไซต์นี้

• บัญชี: เซสชัน การใช้งาน และเหตุการณ์ตรวจสอบความปลอดภัย
• แคตตาล็อก: แพ็กเกจ ภูมิภาค และอิมเมจที่มีให้ใช้
• เซิร์ฟเวอร์: สร้าง ตรวจสอบ เปลี่ยนแปลง และยกเลิก
• คีย์ SSH: ลงทะเบียนข้อมูลสาธารณะและเพิกถอนคีย์ที่ล้าสมัย
• เว็บฮุก: ลงทะเบียน ตรวจสอบ ทดสอบ และลบการเรียกกลับที่ลงนามแล้ว

คำขอจากเซิร์ฟเวอร์ควรมีขนาดเล็ก

เลือกตัวระบุแพ็กเกจมาตรฐาน ภูมิภาค อิมเมจระบบปฏิบัติการ และชื่อโฮสต์ ขีดจำกัดชื่อโฮสต์ที่ตั้งใจไว้คือ 64 ตัวอักษร บริการที่ใช้งานอยู่สามารถสร้างรหัสลับผู้ดูแลแบบส่วนตัวหรือรับคีย์สาธารณะ SSH ที่ลงทะเบียนไว้ การเพิ่มดิสก์ GPU NIC และ IP ตามอำเภอใจไม่ใช่สิ่งที่รวมอยู่ในการขอแพ็กเกจมาตรฐาน ปฏิเสธฟิลด์ที่ไม่รองรับแทนที่จะเรียกเก็บเงินเงียบ ๆ สำหรับการอัปเกรดที่เดาเอง

{
  "plan": "KV-D3",
  "region": "hel",
  "image": "ubuntu-24",
  "hostname": "private-node-01"
}
// Example request schema; validate against a released API before integration.

ขอบเขตและขีดจำกัดคีย์เป็นส่วนหนึ่งของสัญญา

กลุ่มสิทธิ์ที่เสนอคือ การอ่าน เซิร์ฟเวอร์ การเรียกเก็บเงิน และการบริหารบัญชีแบบเต็ม ควรแสดงคีย์หนึ่งครั้งเมื่อสร้าง เก็บไว้เป็นส่วนตัว และเพิกถอนได้แยกจากรหัสผ่านของผู้ใช้ ขีดจำกัดบัญชีที่ตั้งใจไว้คือคีย์ที่ใช้งานได้สิบรายการ ก่อนเผยแพร่การใช้งาน ให้ตรวจสอบว่าทุกการดำเนินการปฏิเสธคีย์ที่ไม่มีขอบเขตสิทธิ์ที่จำเป็น

เผยแพร่ขีดจำกัดอัตราและพฤติกรรมการลองใหม่ร่วมกัน

ขีดจำกัดที่เสนอคือ 120 คำขอต่อนาที และ 3,000 ต่อชั่วโมงสำหรับคีย์ API และ 30 คำขอต่อนาทีสำหรับคำขอแคตตาล็อกสาธารณะที่ไม่ผ่านการรับรองความถูกต้อง ค่าเหล่านี้เป็นค่านโยบายที่วางแผนไว้ ไม่ใช่ความจุ API ที่วัดได้ การใช้งานจริงต้องมีการตอบกลับ 429 ที่สอดคล้องกัน คำแนะนำ Retry-After และการถอยกลับของไคลเอนต์แบบมีขอบเขต คำขอสร้างและชำระเงินยังต้องมีคีย์ idempotency ที่เสถียร

เว็บฮุกคือข้อความที่อาจมาถึงมากกว่าหนึ่งครั้ง

ตัวรับ callback ควรตรวจสอบลายเซ็นบนเนื้อหาต้นฉบับ ปฏิเสธการประทับเวลาที่อยู่นอกช่วงที่อนุญาต และจดจำตัวระบุเหตุการณ์ที่ประมวลผลแล้ว บันทึกเหตุการณ์ไว้ก่อนตอบรับ แล้วนำการเปลี่ยนแปลงไปใช้แบบ idempotent เก็บความพยายามในการส่งและเส้นทางการเล่นซ้ำด้วยตนเองให้มองเห็นได้ callback คือการสังเกตเกี่ยวกับการดำเนินการ ไม่ใช่การอนุญาตให้ดำเนินการตามคำสั่งที่ไม่เกี่ยวข้องซึ่งอยู่ในเพย์โหลด

ตรวจสอบโดยไม่เปลี่ยนบันทึกเป็นที่เก็บความลับ

บันทึกตัวระบุผู้กระทำ ประเภทการดำเนินการ ทรัพยากรที่ได้รับผลกระทบ ผลลัพธ์ และเวลา ตามที่จำเป็นสำหรับความปลอดภัยของบัญชี หลีกเลี่ยงการบันทึกรหัสผ่าน โทเค็น bearer คีย์ส่วนตัว หรือเนื้อหาคำขอการชำระเงินและแอปพลิเคชันแบบเต็มโดยค่าเริ่มต้น กำหนดระยะเวลาการเก็บรักษา การเข้าถึง และประวัติที่ลูกค้ามองเห็นได้อย่างชัดเจน เส้นทางการตรวจสอบความปลอดภัยกับสิทธิ์ในการตรวจสอบเนื้อหาแอปพลิเคชันของลูกค้าเป็นคนละเรื่องกัน

เผยแพร่ไฟล์ build เฉพาะเมื่อมีอยู่จริง

การเปิดตัว API สาธารณะควรมีเอกสาร OpenAPI ที่มีเวอร์ชัน คำแนะนำการรับรองความถูกต้อง ตัวอย่างข้อผิดพลาด และกระบวนการเลิกใช้ CLI ในอนาคต แพ็กเกจ Python ไคลเอนต์ TypeScript หรือเซิร์ฟเวอร์ MCP ต้องมีการเผยแพร่จริง เช็กซัม และเอกสารที่ดูแลรักษา แพ็กเกจการจัดเตรียม KoalaVPS หรือปลายทางการจัดการการผลิตไม่ได้เผยแพร่ผ่านไซต์นี้

ความชัดเจนอีกเล็กน้อย