ที่อยู่ API เฉพาะและสภาพแวดล้อม
Sursa API มีที่อยู่ของตัวเอง แยกจากที่อยู่ที่ผู้คนใช้เปิด Sursa ในเบราว์เซอร์ ทุกพาธขึ้นต้นด้วย /v1
| Sursa ทำงานที่ใด | ที่อยู่ API เฉพาะ | พอร์ทัลนี้ |
|---|---|---|
| คลาวด์ของ Sursa | https://api.sursa.com | https://developers.sursa.com |
| ระบบที่ติดตั้งเอง | https://api.<your domain> ตามที่ผู้ดูแลระบบของคุณตั้งค่าไว้ | /developers/ บนที่อยู่ API เฉพาะ |
| ระบบที่ติดตั้งเองซึ่งไม่มีที่อยู่ API แยก | ที่อยู่หลักของระบบที่ติดตั้ง | /developers/ บนที่อยู่หลัก |
ที่อยู่ API ให้บริการเฉพาะ API ไม่มีหน้าลงชื่อเข้าใช้ ไม่มีคุกกี้ และไม่มีหน้าจอเว็บ ทุกคำขอยืนยันตัวตนด้วย คีย์ API หรือ โทเค็นเข้าถึง OAuth ที่อยู่นี้อาจให้บริการโดยเซิร์ฟเวอร์หลายเครื่องที่อยู่หลังตัวกระจายโหลด ระบบที่เชื่อมต่อไม่จำเป็นต้องรู้ว่ามีกี่เครื่อง
ระบบที่เชื่อมต่อซึ่งเรียก API บนที่อยู่หลัก (เช่น https://app.sursa.com/v1) ยังทำงานได้ตามปกติ ดูความแตกต่างเล็กน้อยและขั้นตอนการย้ายทีละขั้นได้ใน ย้ายไปใช้ที่อยู่ API เฉพาะ
URL ฐาน
สร้างทุกคำขอจาก URL ฐานเดียวในการตั้งค่าของคุณ เพื่อให้โค้ดชุดเดียวกันทำงานกับสภาพแวดล้อมใดก็ได้:
export SURSA_API="https://api.sursa.com"
curl "$SURSA_API/v1/me" -H "Authorization: Bearer $SURSA_API_KEY"
ใช้ HTTPS เท่านั้น และอย่าให้คีย์ปรากฏในล็อกของคำขอที่คุณส่ง
เวอร์ชันและข้อกำหนด
GET /v1/health บอกว่าที่อยู่นั้นทำงานอยู่หรือไม่ และส่งคืนเวอร์ชันของ Sursa ที่ให้บริการที่อยู่นั้น เอนด์พอยต์นี้ตอบกลับโดยไม่ต้องใช้คีย์ คุณจึงใช้ในระบบเฝ้าระวังได้:
curl https://api.sursa.com/v1/health{"ok": true, "version": "v1.4.0"}
นี่คือเวอร์ชันของรุ่นเผยแพร่ Sursa ไม่ใช่เวอร์ชันของ API เวอร์ชันของ API คือ info.version ในข้อกำหนดของ API ข้อกำหนด OpenAPI 3.1 ของ API เผยแพร่อยู่ที่ที่อยู่เดียวกันโดยไม่ต้องยืนยันตัวตน:
| พาธ | เนื้อหา |
|---|---|
GET /openapi.json | ข้อกำหนดสาธารณะ โดยมีที่อยู่นี้อยู่ใน servers |
GET /v1/openapi-public.json | ข้อกำหนดเดียวกัน รองรับ ETag และ If-None-Match |
ใช้ข้อกำหนดนี้สร้างไคลเอ็นต์ นำเข้า API ไปยังเครื่องมืออย่าง Postman หรือตรวจใน CI ว่าระบบที่เชื่อมต่อใช้เฉพาะการดำเนินการของเวอร์ชันที่คุณคาดไว้ เอกสารอ้างอิง API ของพอร์ทัลนี้ก็สร้างจากไฟล์เดียวกัน
การทดสอบ
Sursa ไม่มีโหมดทดสอบแยกต่างหาก ทุกคำขอที่ใช้คีย์มีผลกับข้อมูลจริงขององค์กรของคีย์นั้น หากต้องการพัฒนาและทดสอบอย่างปลอดภัย:
- สร้างคีย์แยกสำหรับการพัฒนา โดยให้บทบาทและขอบเขตสิทธิ์แคบที่สุดเท่าที่งานต้องการ
- เขียนข้อมูลลงในคอลเลกชันเฉพาะ เช่น
sandboxที่มีเพียงทีมของคุณมองเห็น และลบทิ้งเมื่อทำงานเสร็จ - หากบริษัทของคุณมีองค์กรหรือระบบที่ติดตั้ง Sursa แยกไว้สำหรับทดสอบ ให้ชี้ URL ฐานและคีย์ไปที่นั่น โดยไม่ต้องเปลี่ยนส่วนอื่นในโค้ด
- ทำให้การลองใหม่ปลอดภัยตั้งแต่แรก โดยส่ง Idempotency-Key ไปกับทุกคำขอ
POSTและPATCH
คอนโซล ลองใช้ ในแต่ละหน้าเอนด์พอยต์ของ เอกสารอ้างอิง API ส่งคำขอจริงด้วยคีย์ที่คุณวางลงไป คีย์เก็บอยู่ในหน่วยความจำของแท็บเบราว์เซอร์และส่งไปยังที่อยู่ API เท่านั้น
ข้อกำหนดด้านเครือข่าย
- อนุญาตการเชื่อมต่อ HTTPS ขาออก (พอร์ต 443) จากเซิร์ฟเวอร์ของคุณไปยังที่อยู่ API
- ในกฎของไฟร์วอลล์ ให้อนุญาตด้วยชื่อโฮสต์แทนที่อยู่ IP ตายตัวหากเครือข่ายของคุณทำได้ เพราะเซิร์ฟเวอร์ที่อยู่หลังที่อยู่นั้นอาจเปลี่ยนไปเมื่อมีการเพิ่มกำลังการให้บริการ
- แอปพลิเคชันในเบราว์เซอร์เรียก API ได้โดยตรง การตอบกลับอนุญาตทุกออริจิน (
Access-Control-Allow-Origin: *) โดยไม่ใช้คุกกี้ อย่าลืมว่าคีย์ที่ใช้ในเบราว์เซอร์จะมองเห็นได้โดยผู้ใช้เบราว์เซอร์นั้น