API 與整合
Optifora API 如何運作
本頁說明 API 的樣貌：如何證明身分、版本如何往前推進、一個請求要守在哪些上限之內、錯誤長什麼樣子，以及資料如何與外界交換。
產品仍在開發中，API 介面尚在完備。端點的參考文件會另行發布；本頁不提供任何位址或範例呼叫，只說明運作機制。
身分驗證
每一個請求不是屬於某個人，就是屬於某個已登錄的應用程式。沒有身分卻抵達受保護端點的請求，會以未驗證退回。
- Bearer 權杖存取權杖放在請求的授權標頭中傳送。權杖經過簽章，而且只說明這個請求屬於誰。
- 短效期存取權杖在以分鐘計的時間後失效；長度屬於部署設定，預設為三十分鐘。
- 更新與輪替工作階段以更新權杖延長，每次延長都會發出一組新的權杖。若已用過的更新權杖被第二次提出，該人員的所有工作階段都會被撤銷。
- 權限不會寫死在權杖裡權杖只承載身分；一個人可以看到什麼，每次請求都要向資料庫詢問。因此被收回的權限，會在手上的權杖到期之前就停止作用。
- 整合者金鑰已登錄的應用程式以自己的金鑰連線。明文值只在建立當下顯示一次；系統儲存的是它的摘要，以及可用來辨識金鑰、不具機密性的前綴。
- 由組織授予存取權無論一個應用程式使用得多廣，只要組織沒有登錄授權，它就一列資料也看不到。授權有日期、有範圍，而且隨時可撤銷。
版本控管
- 版本寫在路徑裡端點發布在版本前綴之後；今日的介面為第一版。
- 破壞性變更另開新路徑既有端點的合約不會就地打破。不相容的變更會發布在新的版本路徑上，舊路徑繼續運作。
- 文件會標明自己的版本參考文件會標示自己是由哪個版本產生的；您正在讀的是哪個版本，由文件本身回答。
環境與上限
參考文件宣告兩個環境：正式環境與本機開發環境。根位址會連同金鑰一起交給整合者；本頁不公開。
- 存活與就緒分開量測一個端點說明程序仍在運行；第二個端點會向資料庫送出真實查詢，確認資料庫可以連通。只有第二個端點決定是否應該把流量導過來。
- 瀏覽器來源限於名單之內跨來源請求只接受事先宣告的來源；名單為空時，瀏覽器發出的跨來源請求一律拒絕。
- 主體大小上限請求主體不得超過五 MB。大量資料以具有自身狀態紀錄的批次傳輸作業傳送，而非塞進單一請求。
- 機密不寫入日誌伺服器日誌不保留授權標頭、Cookie、密碼與身分證字號。
流量上限
上限以位址為單位、以分鐘計。預設為每分鐘 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一頁應容納幾筆紀錄。最少一筆，最多兩百筆；未設定時為五十筆。
- offset要略過幾筆紀錄。從零開始。
- total符合篩選條件的紀錄總共有幾筆。
- count這個回應實際承載幾筆紀錄。
回應也會回報它所使用的 limit 與 offset；用戶端從答案讀取自己的位置，而不是用猜的。
資料交換與 Webhook
交換模式是一項設定，不是另一項產品：每個已登錄的應用程式，都在自己的紀錄上帶著它所採用的模式。
| 模式 | 代表什麼 |
|---|---|
| 單向—對外 | 由 Optifora 發布資料；另一方讀取資料或訂閱事件。 |
| 單向—對內 | 由另一方推送資料；Optifora 驗證後寫入。 |
| 雙向 | 雙方都會寫入；衝突規則事先定義。 |
| 交握 | 每次傳輸都會開啟一個工作階段：提出、驗證、核准、傳輸與回執。回執由雙方各自保存。 |
- 事件主動推送Webhook 會把事件送到已登錄應用程式所宣告的回呼位址。無法送達的事件會留在佇列中重試，絕不會被無聲丟棄。
- 同一個請求不會寫入兩次寫入請求會帶著一個冪等性金鑰。使用相同金鑰的第二次請求，不會建立第二筆紀錄。
- 每一次呼叫都被量測誰呼叫、何時呼叫、用哪個範圍、結果如何，全部都會記錄。同一份紀錄既回答除錯問題，也回答「這筆資料是誰調走的」。
- 我們自己的應用程式走同一道門不存在享有特權的第二條路徑。我們自己的整合，就是外部開發者所面對介面的證明。
交換層的資料模型已經就位，端點尚未發布。發布後，本節會連往它們在參考文件中的條目。
參考文件
參考文件不是手寫的，而是由端點結構描述產生。每個端點交出結構描述後，文件就自行補齊，因此文件與實際行為不會脫節。
- 目前：準備中結構描述正逐一模組推進。文件發布之前，每個端點的請求與回應都會在其中可見。
- 會發布兩種格式一份機器可讀的 OpenAPI 文件，以及一份由同一份文件產生、可在瀏覽器中閱覽的參考頁面。
- 存取分級概觀對所有人開放。完整參考文件可能置於文件權杖之後，只發給已登錄的整合者；正式環境金鑰與回呼位址完全不屬於文件範疇，它們屬於應用程式紀錄。
- 位址標準會發布兩份參考文件，位址固定：client-api.optifora.com/docs 對外開放，admin-api.optifora.com/docs 需要授權且不對外。兩者目前都尚未上線；上線後本節會補上連結。
若您的整合規劃已經明確，請從聯絡頁面來信：介面開放時，您會是最先收到通知的人之一。