API ของ Optifora ทำงานอย่างไร
หน้านี้อธิบายรูปร่างของ API ว่าพิสูจน์ตัวตนอย่างไร รุ่นเดินหน้าอย่างไร คำขอต้องอยู่ในขีดจำกัดใด ข้อผิดพลาดมีหน้าตาอย่างไร และแลกเปลี่ยนข้อมูลกับโลกภายนอกอย่างไร
ผลิตภัณฑ์อยู่ระหว่างการพัฒนาและพื้นผิว API ยังอยู่ระหว่างการทำให้สมบูรณ์ เอกสารอ้างอิงของปลายทางต่าง ๆ จะเผยแพร่แยกต่างหาก หน้านี้จึงไม่มีที่อยู่และไม่มีตัวอย่างการเรียก มีเพียงกลไกการทำงานเท่านั้น
การพิสูจน์ตัวตน
ทุกคำขอต้องเป็นของบุคคลหรือของแอปพลิเคชันที่ลงทะเบียนไว้ คำขอที่ไม่มีตัวตนและไปถึงปลายทางที่ป้องกันไว้ จะได้รับคำตอบว่าไม่ผ่านการพิสูจน์ตัวตน
- Bearer tokenโทเคนเข้าถึงเดินทางไปกับส่วนหัว authorization ของคำขอ โทเคนถูกลงลายเซ็นไว้ และบอกเพียงว่าคำขอนั้นเป็นของผู้ใด
- อายุสั้นโทเคนเข้าถึงหมดอายุภายในเวลาที่นับเป็นนาที ความยาวของอายุเป็นค่าตั้งของการติดตั้งระบบ และมีค่าเริ่มต้นที่ 30 นาที
- การต่ออายุและการหมุนเวียนโทเคนเซสชันต่ออายุด้วย refresh token และการต่ออายุทุกครั้งจะออกคู่โทเคนใหม่ หากมีการยื่น refresh token ที่ใช้ไปแล้วซ้ำอีกครั้ง เซสชันทั้งหมดของบุคคลนั้นจะถูกเพิกถอน
- สิทธิ์ไม่ได้ถูกฝังไว้ในโทเคนโทเคนบรรจุเพียงตัวตนเท่านั้น ส่วนสิ่งที่บุคคลนั้นมีสิทธิ์เห็นจะถูกถามจากฐานข้อมูลในทุกคำขอ สิทธิ์ที่ถูกยกเลิกจึงหยุดทำงานก่อนที่โทเคนในมือจะหมดอายุ
- กุญแจของผู้เชื่อมต่อระบบแอปพลิเคชันที่ลงทะเบียนแล้วเชื่อมต่อด้วยกุญแจของตนเอง ค่าจริงจะแสดงเพียงครั้งเดียวตอนสร้าง สิ่งที่จัดเก็บไว้คือค่าย่อยของกุญแจและส่วนนำหน้าที่ไม่เป็นความลับซึ่งใช้ระบุกุญแจได้
- องค์กรเป็นผู้ให้สิทธิ์เข้าถึงไม่ว่าแอปพลิเคชันจะถูกใช้งานกว้างขวางเพียงใด หากองค์กรไม่ได้บันทึกการให้สิทธิ์ไว้ แอปนั้นก็ไม่เห็นข้อมูลแม้แต่แถวเดียว การให้สิทธิ์มีวันที่กำกับ มีขอบเขต และเพิกถอนได้
การกำหนดรุ่น
- รุ่นอยู่ในเส้นทางปลายทางทั้งหมดเผยแพร่หลังส่วนนำหน้าที่ระบุรุ่น พื้นผิวของวันนี้คือรุ่นที่ 1
- การเปลี่ยนแปลงที่ทำลายความเข้ากันได้จะเปิดเส้นทางใหม่สัญญาของปลายทางที่มีอยู่แล้วจะไม่ถูกทำลายในที่เดิม การเปลี่ยนแปลงที่เข้ากันไม่ได้จะเผยแพร่บนเส้นทางรุ่นใหม่ ขณะที่รุ่นเดิมยังทำงานต่อไป
- เอกสารระบุรุ่นของตนเองเอกสารอ้างอิงบรรจุหมายเลขรุ่นที่ใช้สร้างเอกสารนั้นไว้ในตัว คำถามว่าคุณกำลังอ่านรุ่นใดจึงตอบได้จากตัวเอกสารเอง
สภาพแวดล้อมและขีดจำกัด
เอกสารอ้างอิงประกาศสภาพแวดล้อมสองแบบ คือ ระบบจริงและการพัฒนาบนเครื่องท้องถิ่น ที่อยู่รากมอบให้ผู้เชื่อมต่อระบบพร้อมกับกุญแจของเขา และไม่เผยแพร่บนหน้านี้
- วัดความมีชีวิตและความพร้อมแยกกันปลายทางหนึ่งบอกว่ากระบวนการยังทำงานอยู่ ปลายทางที่สองส่งคำสั่งค้นจริงไปยังฐานข้อมูลและยืนยันว่าเข้าถึงได้ มีเพียงปลายทางที่สองเท่านั้นที่ตัดสินว่าควรส่งทราฟฟิกเข้ามาหรือไม่
- ต้นทางของเบราว์เซอร์ถูกจำกัดด้วยรายการที่กำหนดคำขอข้ามต้นทางรับเฉพาะจากต้นทางที่ประกาศไว้ล่วงหน้าเท่านั้น ตราบใดที่รายการยังว่าง คำขอข้ามต้นทางจากเบราว์เซอร์จะถูกปฏิเสธ
- ขีดจำกัดขนาดเนื้อความเนื้อความของคำขอต้องไม่เกิน 5 เมกะไบต์ ชุดข้อมูลขนาดใหญ่เดินทางเป็นงานส่งข้อมูลจำนวนมากที่มีระเบียนสถานะของตนเอง ไม่ใช่คำขอเดียว
- ความลับไม่ถูกเขียนลงบันทึกบันทึกของเซิร์ฟเวอร์ไม่เก็บส่วนหัว authorization ไม่เก็บคุกกี้ ไม่เก็บรหัสผ่าน และไม่เก็บเลขประจำตัวประชาชน
ขีดจำกัดอัตราการเรียก
ขีดจำกัดคิดต่อที่อยู่และต่อนาที ค่าเริ่มต้นคือ 120 คำขอต่อนาที และกำหนดได้ตอนติดตั้งระบบ จำนวนที่เหลือรายงานไว้ในส่วนหัวของทุกคำตอบ
| ส่วนหัวของคำตอบ | ความหมาย |
|---|---|
| x-ratelimit-limit | โควตาทั้งหมดภายในช่วงเวลานั้น |
| x-ratelimit-remaining | จำนวนที่เหลืออยู่ในช่วงเวลานี้ |
| x-ratelimit-reset | จำนวนวินาทีจนกว่าโควตาจะถูกคืนใหม่ |
| retry-after | ต้องรอกี่วินาทีก่อนเรียกซ้ำ มีเฉพาะในคำตอบที่ปฏิเสธคำขอเท่านั้น |
เมื่อเกินขีดจำกัดแล้ว คำขอจะถูกปฏิเสธ และคำตอบจะระบุเป็นวินาทีว่าต้องรอนานเท่าใด การเรียกซ้ำทำหลังเวลานั้น ไม่ใช่ทันที
รูปแบบข้อผิดพลาด
ข้อผิดพลาดทุกรายการกลับมาในซองเดียวกัน มีฟิลด์รหัสสั้นให้เครื่องใช้แยกทาง และฟิลด์คำอธิบายให้คนอ่าน
- errorรหัสสั้นที่ฝั่งผู้เรียกใช้ตัดสินใจแยกทาง
- messageคำอธิบายว่าเกิดอะไรขึ้น
| สถานะ | ฟิลด์รหัส | ความหมาย |
|---|---|---|
| 400 | Bad Request | คำขอไม่ตรงกับโครงสร้างที่กำหนด คำอธิบายจะระบุชื่อฟิลด์ที่ขาดหายหรือไม่ถูกต้อง |
| 401 | unauthenticated | ไม่มีตัวตนที่ใช้ได้ ไม่ได้ส่งโทเคนมา โทเคนหมดอายุ หรือตรวจสอบลายเซ็นไม่ผ่าน |
| 404 | Not Found | ไม่มีปลายทางนี้ หรือไม่มีระเบียนนี้ |
| 429 | Too Many Requests | เกินขีดจำกัดอัตราการเรียก คำตอบจะระบุว่าต้องรอนานเท่าใด |
| 5xx | internal_error | ความล้มเหลวที่ไม่คาดคิด รายละเอียดจะไม่ถูกส่งให้ฝั่งผู้เรียก แต่ถูกเขียนไว้ในบันทึกของเซิร์ฟเวอร์ |
การแบ่งหน้า
ปลายทางที่คืนค่าเป็นรายการรับพารามิเตอร์สองตัวเดียวกันและคืนตัวนับชุดเดียวกัน ฝั่งผู้เรียกที่จัดการการแบ่งหน้าจึงไม่ต้องเขียนใหม่สำหรับทุกปลายทาง
- limitหนึ่งหน้าควรบรรจุกี่ระเบียน อย่างน้อย 1 อย่างมาก 200 และเป็น 50 เมื่อไม่ได้ระบุ
- offsetข้ามไปกี่ระเบียน เริ่มต้นที่ 0
- totalมีระเบียนที่ตรงกับตัวกรองทั้งหมดกี่รายการ
- countคำตอบนี้บรรจุระเบียนจริงกี่รายการ
คำตอบยังสะท้อนค่า limit และ offset ที่ใช้กลับมาด้วย ฝั่งผู้เรียกจึงอ่านตำแหน่งของตนจากคำตอบแทนการเดา
การแลกเปลี่ยนข้อมูลและ webhook
โหมดการแลกเปลี่ยนเป็นค่าตั้ง ไม่ใช่ผลิตภัณฑ์แยกต่างหาก แอปพลิเคชันที่ลงทะเบียนทุกตัวบรรจุโหมดที่ตนทำงานอยู่ไว้ในระเบียนของตนเอง
| โหมด | ความหมาย |
|---|---|
| ทางเดียว — ขาออก | Optifora เผยแพร่ข้อมูล ฝ่ายตรงข้ามอ่านข้อมูลนั้นหรือสมัครรับเหตุการณ์ |
| ทางเดียว — ขาเข้า | ฝ่ายตรงข้ามส่งข้อมูลเข้ามา Optifora ตรวจสอบความถูกต้องแล้วจึงบันทึก |
| สองทาง | ทั้งสองฝ่ายเขียนข้อมูลได้ กฎการชนกันของข้อมูลกำหนดไว้ล่วงหน้า |
| การจับมือแลกเปลี่ยน | การส่งข้อมูลทุกครั้งเปิดเป็นเซสชัน ได้แก่ การเสนอ การตรวจสอบ การอนุมัติ การส่ง และใบรับ ใบรับคงอยู่กับทั้งสองฝ่าย |
- เหตุการณ์ถูกส่งออกไปwebhook ส่งเหตุการณ์ไปยังที่อยู่เรียกกลับที่แอปพลิเคชันซึ่งลงทะเบียนไว้ได้ประกาศเอาไว้ เหตุการณ์ที่ส่งไม่สำเร็จจะคงอยู่ในคิวและถูกส่งซ้ำ ไม่มีการทิ้งไปอย่างเงียบ ๆ
- คำขอเดียวกันไม่เขียนข้อมูลซ้ำสองครั้งคำขอที่เขียนข้อมูลพกกุญแจกันซ้ำมาด้วย คำขอที่สองซึ่งใช้กุญแจเดียวกันจะไม่สร้างระเบียนที่สอง
- ทุกการเรียกถูกวัดใครเรียก เมื่อใด ด้วยขอบเขตใด และได้ผลอย่างไร ทั้งหมดถูกบันทึกไว้ ระเบียนเดียวกันนี้ตอบได้ทั้งการแก้จุดบกพร่องและคำถามว่าใครดึงข้อมูลนี้ไป
- แอปของเราเองก็ใช้ประตูเดียวกันไม่มีเส้นทางที่สองที่มีอภิสิทธิ์ การเชื่อมต่อของเราเองคือหลักฐานของพื้นผิวที่นักพัฒนาภายนอกได้พบ
แบบจำลองข้อมูลของชั้นการแลกเปลี่ยนพร้อมแล้ว แต่ปลายทางยังไม่เผยแพร่ เมื่อเผยแพร่แล้ว ส่วนนี้จะลิงก์ไปยังรายการของปลายทางเหล่านั้นในเอกสารอ้างอิง
เอกสารอ้างอิง
เอกสารอ้างอิงไม่ได้เขียนด้วยมือ แต่สร้างขึ้นจากโครงสร้างข้อมูลของปลายทาง เมื่อแต่ละปลายทางส่งมอบโครงสร้างของตน เอกสารก็เติมเต็มตัวเอง เอกสารกับพฤติกรรมจริงจึงแยกออกจากกันไม่ได้
- วันนี้: อยู่ระหว่างจัดทำโครงสร้างข้อมูลกำลังทยอยย้ายทีละโมดูล ก่อนเอกสารจะเผยแพร่ คำขอและคำตอบของทุกปลายทางจะปรากฏอยู่ในเอกสารนั้น
- จะเผยแพร่สองรูปแบบเอกสาร OpenAPI ที่เครื่องอ่านได้ และหน้าอ้างอิงที่สร้างจากเอกสารเดียวกันนั้นและเปิดดูได้ในเบราว์เซอร์
- การเข้าถึงแบ่งเป็นระดับภาพรวมเปิดให้ทุกคนอ่านได้ ส่วนเอกสารอ้างอิงฉบับเต็มอาจอยู่หลังโทเคนเอกสารที่มอบให้ผู้เชื่อมต่อระบบที่ลงทะเบียนแล้ว กุญแจของระบบจริงและที่อยู่เรียกกลับไม่ใช่เรื่องของเอกสารเลย แต่เป็นของระเบียนแอปพลิเคชัน
- มาตรฐานที่อยู่เอกสารอ้างอิงสองชุดจะถูกเผยแพร่และที่อยู่ถูกกำหนดตายตัว client-api.optifora.com/docs เปิดให้เข้าถึงได้ ส่วน admin-api.optifora.com/docs ต้องมีสิทธิ์และปิดจากภายนอก ทั้งสองยังไม่เปิดใช้งานในวันนี้ ลิงก์จะถูกเพิ่มในส่วนนี้เมื่อเปิดแล้ว
หากแผนการเชื่อมต่อของคุณชัดเจนแล้ว โปรดเขียนถึงเราจากหน้าติดต่อ คุณจะเป็นกลุ่มแรกที่ได้รับแจ้งเมื่อพื้นผิวนี้เปิด
คุณมีคำขอเฉพาะเรื่องหรือไม่
หน้าเหล่านี้อธิบายว่ากระบวนการสนับสนุนทำงานอย่างไร หากคุณมีคำขอหรือคำถาม เขียนถึงเราได้จากหน้าติดต่อ
ไปยังหน้าติดต่อ