Joomla Web services API規(guī)范

從Joomla 4 開始，joomla正式從核心開始支持web service API接口，本文將簡單的介紹一下API體系的規(guī)范。（可能會隨著joomla的版本升級會有少許修改）

認證（Authentication）

Joomla核心已經內置了API的認證插件（API Authentication - Joomla Token插件和User - Joomla Token插件），系統(tǒng)的認證插件并沒有完全按照oAuth 2規(guī)范來實現。（如果有需要，第三方開發(fā)者可以自己通過插件來實現）內置身份驗證插件使用Bearer Token來實現。系統(tǒng)提供了一個新的插件組（api-authentication），開發(fā)者可以基于自己的需求來開發(fā)認證規(guī)范。

HMAC(Keyed-Hashing for Message Authentication) 是Joomla的 Bearer token實現的主要安全保證， 基于RFC 2104 HMAC規(guī)則生成的一個種子數據作為joomla網站的安全密鑰(這個密鑰$secret保存在configuration.php文件中) .經過base64編碼的種子存儲在數據庫的用戶配置表中。

基于這種格式（算法:用戶ID:HMAC）得到一個字符串，然后將這個字符串經過base64 編碼后就生成了令牌。其中算法告訴我們使用哪個加密哈希函數來生成 HMAC，根據 RFC 6151 的安全規(guī)范，系統(tǒng)禁止使用不太安全的加密哈希函數，事實上，當前的實現只允許 SHA-256 和 SHA-512，其中 SHA-256 是用于生成顯示給用戶的令牌的（硬編碼）方法。 添加 SHA-512 是為了向前兼容。

出于安全和隱私原因，用戶只能查看自己的令牌，即使他們是超級用戶。具有 com_users.edit 權限的用戶還可以禁用、啟用或重置其他用戶的令牌,但他們仍然無法查看.用戶還可以選擇禁用自己的 API 密鑰。

Bearer Token是目前主流的訪問權限控制/認證模式。

：為了驗證使用者的身份，需要客戶端向服務器端提供一個可靠的驗證信息，稱為Token，這個token通常由Json數據格式組成，通過hash散列算法生成一個字符串，所以稱為Json Web Token（Json表示令牌的原始值是一個Json格式的數據，web表示是在互聯網傳播的，token表示令牌，簡稱JWT)

請求（Requests）

內容協(xié)商

默認情況下，當使用 Accept: application/json 標頭以及特定的 JSON API 標頭請求時，Joomla 將返回 JSON API 響應。通過開發(fā)插件，也可以使Joomla 支持其他內容類型的能力，添加此映射的系統(tǒng)插件將負責確保組件支持此映射，joomla核心不支持其他的內容類型。

語言協(xié)商

目前不支持語言協(xié)商，以后可能會添加支持。

路由

基本信息

Joomla CMS 需要為 API 使用單獨的路由器，因為 API 將是嚴格的 RESTful（即對同一個 URL 的 POST 和 GET 請求會產生不同的結果），Joomla 框架路由器已經滿足了RESTFUL規(guī)范，然后將對其的請求映射到 JInput 變量，這樣我們可以繼續(xù)使用 JInput 來獲得請求的參數。

由于 Joomla 的 API實現在Joomla 的 api 文件夾中，因此所有路由都將以 Joomla根目錄/api  開頭，這是不可以改變的，除非在joomla框架層面進行修改。

添加路由

路由通過類型為 webservice 的插件注冊，一個插件可以添加一個或多個路由（每個都應該滿足 RESTful 規(guī)范），雖然每個插件一個路由只添加一種路由最好，但是這樣會導致系統(tǒng)安裝非常多的插件，不利于開發(fā)管理。因此，我們建議每個組件使用一個插件來公開其接口數據。

響應（Responses）

API 響應格式

Joomla 評估了幾種響應 API 格式，其中包括JSON-LD, JSON API 和 Collection+JSON。最終決定使用 JSON API v1.0 規(guī)范。Joomla API 中的一些批處理交互也將使用 JSON API Partial Success 模塊進行錯誤處理。

Richardson 成熟度模型和超媒體

我們預計Joomla 將在很大程度上符合理查森成熟度模型的第 3 級，目前我們的實體系統(tǒng)（JTable 和 JModel）并不理想地適用于此，這意味著在某些地方，尤其是圍繞數據關系的地方，可能存在一些實現困難