REST API¶

在 XenForo 2.1 中，添加了 REST API。這使您可以通過編程的方式與 XenForo 安裝的許多區域進行交互。

要訪問 API，需要通過管理員控制面板產生密鑰。未經認證的 API 沒有辦法訪問，此時用戶也不能自己產生密鑰來訪問 API。

特定 XenForo 安裝的 API 可通過 <XenForo 基本 URL>/api/ 訪問。所有端點都以該 URL 為前綴。例如，如果 XenForo 安裝在 https://example.com/community/，那麼API URL將以 https://example.com/community/api/ 開頭。在本例中，訪問執行緒列表可通過 https://example.com/community/api/threads/ 進行。

默認情況下 API 是啟用的。如果需要，可以通過在 src/config.php 中添加以下內容來快速關閉所有 API 訪問：

$config['enableApi'] = false;

API 密鑰¶

通過管理員控制面板到 設定 > API 密鑰 建立 API 密鑰。由於產生 API 密鑰可以允許訪問高度特權的資料，因此只有超級管理員可以訪問本系統。當產生 API 密鑰時，所有超級管理員都會收到一封郵件，以確保請求有效。

創建密鑰後，將生成一個隨機字串，該字串將用於通過 API 進行身份驗證。將此密鑰保密是很重要的。如果您認為 API 密鑰已被盜用，你應該立即重新生成新的密鑰並更新任何使用舊密鑰的程式碼。

密鑰類型¶

所有的 API 訪問都是在特定用戶的 Context 中進行的。例如，如果我以 "John" 的身份訪問 API，並且我提出了一個發佈主題的請求，那麼這個主題將由 "John" 建立。在大多數情況下，API 也會遵守為這個用戶指定對應的權限，所以他們不能訪問他們在正常瀏覽論壇時看不到的資料。

為了對此進行控制，共有三種類型的 API 密鑰：

訪客密鑰 - 此密鑰總是以訪客用戶身份存取 API。這些請求將始終遵守訪客的權限。例如，如果客人不能回覆主題，那麼回覆主題的 API 請求將產生一個沒有權限的錯誤。
用戶密鑰 - 這個密鑰總是以指定用戶的身份訪問 API，並始終遵守該用戶的權限，類似於訪客密鑰。
超級用戶密鑰 - 這個密鑰可以通過傳遞一個額外的值，以任何用戶的身份訪問 API。（可選）此密鑰可以繞過用戶發出請求的權限，從而允許他們執行操作或查看通常不具有訪問權限的內容。

超級用戶密鑰對於與其他系統或應用程式的整合非常有用。例如，您可能會與第三方 CMS 整合，每當您發佈一篇新文章時，該 CMS 就會建立一個主題。這種類型的密鑰將允許您根據文章作者或在用戶通常不能發佈的論壇中建立一個不同用戶的主題。

密鑰作用域¶

為了幫助限制被洩露的密鑰所造成的損害，每個密鑰都可以控制其可以訪問的 API 作用域。作用域限制了對 API 區域的訪問，與用戶的請求權限無關。

API 中的每個端點都會被一個或多個作用域所覆蓋。如果 API 沒有被授予任何這些作用域，則請求將失敗。

為了安全起見，我們建議您僅為密鑰授予所需的作用域。如果您在以後需要其他的作用域，則可以在需要時添加它們。

訪問 API¶

一旦知道訪問 API 的 URL 並獲得密鑰後，就可以開始對其發出請求。

所有的 API Response 都將以 JSON 格式返回，除非是特別要求二進制檔案（例如，下載附件時）。錯誤將返回一個 400 範圍內的 Response 狀態碼。成功的請求將返回一個 200 狀態碼。雖然不常用，但重定向將返回一個 300 範圍的狀態碼。

Request body 必須使用 application/x-www-form-urlencoded 編碼發送，或者，如果是上傳檔案，則使用 multipart/form-data 編碼發送。參數也可以通過查詢字串來傳遞。

所有 Request 資料必須使用 UTF-8 字符集。

Request 必須通過 XF-API-Key Header 傳遞要使用的 API 密鑰。所有 Request 中都必須有這個密鑰。

如果選擇的 API 密鑰是超級用戶密鑰，你可以通過 XF-API-User Header 傳遞 Context User 的用戶ID。如果沒有傳遞用戶 ID，Context 將默認為訪客。

如果 Request 是用超級用戶密鑰發出的，並且你希望繞過 Context User 的權限，則可以通過將 api_bypass_permissions 參數設定為 1 來實現。(這個參數可以通過 query string 或作為 Request body 的一部分來進行傳遞。)

錯誤處理¶

當遇到 Error 時，response 狀態碼將在 400 範圍內。有時，可能會出現 500 範圍的錯誤，不過這表明伺服器無法處理該 request。 API 可能被暫時關閉，或者發生了其他伺服器錯誤。

錯誤訊息具有標準格式。這是一個例子：

{
    "errors": [
        {
            "code": "api_key_not_found",
            "message": "未找到 Request 中提供的 API 密鑰。",
            "params": []
        }
    ]
}

最上層將是一個帶有 errors key 的物件。這將是包含 1 個或多個 entry 的陣列。每個 entry 都是一個物件，參數如下：

code - 這是機器可以讀懂的錯誤碼。有許多可能的錯誤碼，因為它們取決於情況。
message - 人類可以讀懂的錯誤訊息。這可能會改變，也可能會被翻譯，不應該用於識別錯誤類型。
params - 這是觸發錯誤相關的 key-value 參數列表。它們可以補充錯誤碼和訊息，以提供有關錯誤的更多明確的詳細訊息。

API 端點¶

該 API 具有許多 Endpoints 和可以採取的措施。將來可能會新增其他 Endpoint 和資料。

查看 API 端點文件

該 Endpoint 文件是根據 API 資料和程式碼中的註釋生成的。它將隨著時間的推移進行擴展和更新。