ย้ายไปใช้ที่อยู่ API เฉพาะ

ระบบที่เชื่อมต่อรุ่นก่อนเรียก API บนที่อยู่หลักของ Sursa ซึ่งเป็นที่อยู่ที่ผู้คนเปิดในเบราว์เซอร์ เช่น https://app.sursa.com/v1/… ตอนนี้ API มีที่อยู่ของตัวเองด้วย คือ https://api.sursa.com ในคลาวด์ หรือ https://api.<your domain> ในระบบที่ติดตั้งเอง ที่อยู่นี้สร้างมาเพื่อระบบที่เชื่อมต่อโดยเฉพาะ ขยายกำลังได้ด้วยเซิร์ฟเวอร์หลายเครื่องหลังตัวกระจายโหลด และให้บริการเฉพาะ API เท่านั้น

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

สิ่งที่คงเดิม

• พาธ พารามิเตอร์ ฟิลด์ รหัสข้อผิดพลาด และอีเวนต์ GET /v1/cards เป็นคำขอเดียวกันบนทั้งสองที่อยู่
• คีย์ API คีย์ kb_ และ kbsrc_ ชุดเดิมใช้ได้บนทั้งสองที่อยู่ โดยมีบทบาท ขอบเขตสิทธิ์ และโปรไฟล์ข้อมูลเหมือนเดิม
• คีย์ป้องกันการทำซ้ำ ขีดจำกัดอัตราการเรียก และโควตา คำขอบนทั้งสองที่อยู่นับรวมในโควตาเดียวกันขององค์กร
• เว็บฮุก การส่ง ลายเซ็น และข้อมูลลับไม่ขึ้นอยู่กับที่อยู่ที่คุณเรียก
• ลิงก์ในการตอบกลับ doc_url ของข้อผิดพลาดชี้ไปยังพอร์ทัลนี้ และเฮดเดอร์ Link ของหน้ารายการชี้ไปยังที่อยู่ API เฉพาะ ไม่ว่าคุณจะเรียกที่อยู่ใด

สิ่งที่ต่างไปบนที่อยู่ API เฉพาะ

แถวสุดท้ายมีผลเพียงกรณีเดียว คือคำตอบแบบสตรีมของ POST /v1/chat สตรีมที่ขาดจะไล่ต่อจาก Last-Event-ID ได้เฉพาะบนเซิร์ฟเวอร์ที่กำลังเขียนคำตอบนั้น หากระบบที่เชื่อมต่อทำต่อจากสตรีมที่ขาด ให้กำหนด request_id ให้ทุกคำถาม เพื่อให้การลองใหม่บนเซิร์ฟเวอร์อื่นได้รับคำตอบที่บันทึกไว้แทนคำตอบใหม่ ดู ทำต่อจากสตรีมที่ขาด

ก่อนย้าย

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

curl -s https://api.sursa.com/openapi.json \
  | jq -r '.paths | to_entries[] | .key as $p | .value | keys[] | ascii_upcase + " " + $p' \
  | sort > public-operations.txt

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

ตรวจวิธียืนยันตัวตน หากระบบที่เชื่อมต่อลงชื่อเข้าใช้ด้วยรหัสผ่านของผู้ใช้และคุกกี้เซสชัน ให้เปลี่ยนไปใช้ คีย์ API ก่อน หากส่ง X-API-Key แนะนำให้เปลี่ยนเป็น Authorization: Bearer แต่ไม่บังคับ

ตรวจเครือข่าย อนุญาต HTTPS ขาออกไปยังชื่อโฮสต์ใหม่ในไฟร์วอลล์และพร็อกซีของคุณ

ย้ายทีละขั้นตอน

1. ทำให้ URL ฐานเป็นค่าที่ตั้งค่าได้ ในระบบที่เชื่อมต่อ หากยังไม่ได้ทำ

2. ลองที่อยู่ใหม่ ด้วยคำขออ่าน:

   curl https://api.example.com/v1/me -H "Authorization: Bearer $SURSA_API_KEY"
   

3. รันชุดทดสอบ ของระบบที่เชื่อมต่อกับที่อยู่ใหม่ โดยใช้คีย์ทดสอบและคอลเลกชันทดสอบ

4. สลับทราฟฟิกบางส่วน เช่น เวิร์กเกอร์ตัวเดียวหรือสภาพแวดล้อมเดียว แล้วเฝ้าดู 404 api.not_found 401 และ 5xx ในล็อก ทุกการตอบกลับมี X-Request-Id ให้เก็บค่านี้ไว้กับล็อกของคุณ

5. สลับส่วนที่เหลือ เก็บ URL ฐานเดิมไว้ในการตั้งค่าสักระยะ เพื่อให้สลับกลับได้ภายในไม่กี่วินาที

สิ่งที่ควรตรวจหลังย้าย

• GET /v1/health บนที่อยู่ใหม่ส่งคืน version เดียวกับบนที่อยู่เดิม
• การตอบกลับมีเฮดเดอร์ RateLimit หากระบบที่เชื่อมต่อชะลอตัวเองตาม X-RateLimit-* ก็ทำต่อไปได้ เพราะระบบส่งทั้งสองชุด ดู ขีดจำกัดอัตราการเรียกและโควตา
• หากระบบที่เชื่อมต่อทำงานในเบราว์เซอร์ ก็ไม่ต้องใช้พร็อกซีของคุณเองสำหรับ CORS อีกต่อไป เพราะที่อยู่ API เฉพาะอนุญาตคำขอจากทุกออริจินโดยไม่ใช้คุกกี้