Joomla Web services API規(guī)范

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

認證（Authentication）

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

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

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

出于安全和隱私原因，用戶只能查看自己的令牌，即使他們是超級用戶。具有 com_users.edit 權(quán)限的用戶還可以禁用、啟用或重置其他用戶的令牌,但他們?nèi)匀粺o法查看.用戶還可以選擇禁用自己的 API 密鑰。

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

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

請求（Requests）

內(nèi)容協(xié)商

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

語言協(xié)商

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

路由

基本信息

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

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

添加路由

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

響應（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）并不理想地適用于此，這意味著在某些地方，尤其是圍繞數(shù)據(jù)關(guān)系的地方，可能存在一些實現(xiàn)困難