Joomla Web services API规范

从Joomla 4 开始，joomla正式从核心开始支持web service API接口，本文将简单的介绍一下API体系的规范。（可能会随着joomla的版本升级会有少许修改）

认证（Authentication）

Joomla核心已经内置了API的认证插件（API Authentication - Joomla Token插件和User - Joomla Token插件），系统的认证插件并没有完全按照oAuth 2规范来实现。（如果有需要，第三方开发者可以自己通过插件来实现）内置身份验证插件使用Bearer Token来实现。系统提供了一个新的插件组（api-authentication），开发者可以基于自己的需求来开发认证规范。

HMAC(Keyed-Hashing for Message Authentication) 是Joomla的 Bearer token实现的主要安全保证， 基于RFC 2104 HMAC规则生成的一个种子数据作为joomla网站的安全密钥(这个密钥$secret保存在configuration.php文件中) .经过base64编码的种子存储在数据库的用户配置表中。

基于这种格式（算法:用户ID:HMAC）得到一个字符串，然后将这个字符串经过base64 编码后就生成了令牌。其中算法告诉我们使用哪个加密哈希函数来生成 HMAC，根据 RFC 6151 的安全规范，系统禁止使用不太安全的加密哈希函数，事实上，当前的实现只允许 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）

内容协商

默认情况下，当使用 Accept: application/json 标头以及特定的 JSON API 标头请求时，Joomla 将返回 JSON API 响应。通过开发插件，也可以使Joomla 支持其他内容类型的能力，添加此映射的系统插件将负责确保组件支持此映射，joomla核心不支持其他的内容类型。

语言协商

目前不支持语言协商，以后可能会添加支持。

路由

基本信息

Joomla CMS 需要为 API 使用单独的路由器，因为 API 将是严格的 RESTful（即对同一个 URL 的 POST 和 GET 请求会产生不同的结果），Joomla 框架路由器已经满足了RESTFUL规范，然后将对其的请求映射到 JInput 变量，这样我们可以继续使用 JInput 来获得请求的参数。

由于 Joomla 的 API实现在Joomla 的 api 文件夹中，因此所有路由都将以 Joomla根目录/api  开头，这是不可以改变的，除非在joomla框架层面进行修改。

添加路由

路由通过类型为 webservice 的插件注册，一个插件可以添加一个或多个路由（每个都应该满足 RESTful 规范），虽然每个插件一个路由只添加一种路由最好，但是这样会导致系统安装非常多的插件，不利于开发管理。因此，我们建议每个组件使用一个插件来公开其接口数据。

响应（Responses）

API 响应格式

Joomla 评估了几种响应 API 格式，其中包括JSON-LD, JSON API 和 Collection+JSON。最终决定使用 JSON API v1.0 规范。Joomla API 中的一些批处理交互也将使用 JSON API Partial Success 模块进行错误处理。

Richardson 成熟度模型和超媒体

我们预计Joomla 将在很大程度上符合理查森成熟度模型的第 3 级，目前我们的实体系统（JTable 和 JModel）并不理想地适用于此，这意味着在某些地方，尤其是围绕数据关系的地方，可能存在一些实现困难