跳到主要内容

自定义应用API详情

我们在创建应用章节中已经学会了如何创建 API,本章即对 API 的各部分详细说明。

如图所示:

getManyPost

在 API 模块中,有五个区域。

API 列表#

API 列表按字母顺序罗列该应用的所有 API,搜索框输入 API 可以进行检索,点击某个 API 后可对其进行编辑。

点击“新建 API”按钮可以创建新的 API,如图所示:

createApi

API:对应用户的实际请求 api,必填,尽量以英文字母为主,也可加数字。

API 名称:可省略,但加上更容易阅读理解。

API 描述:当该 API 的名称不足以说明功能时,需要描述来补充,一般在 API 文档中展示。

API 文档补充:当自动生成的 API 文档不足以让用户理解或者有一些地方需要进一步说明,或者调用该 API 有一些前提条件,那么就需要文档补充来解释,提供给用户注意。

API 分组:当该应用的 API 较多时,为了用户更容易检索、跳转、理解各部分,可以给 API 加个分组。

基础信息#

在编辑 API 时,点击[基础信息]按钮,可以看到下图所示:

base

四个字段上面讲过了,忽略不计,删除按钮分别为删除当前 API 版本和整个 API。

右侧是 API 版本选择框和新建版本按钮。

我们来详细说下版本功能。

有第三方服务开发经验的同学可能深有体会版本功能的重要性,当你的产品作为第三方服务提供给其他人用时,一开始还好,但是在后续功能迭代时,你需要改变某个现有的 API。这时候如果没有版本控制,那么需要联系到所有使用该 API 的客户一一通知、协调,对方可能还不愿意改变或无法改变。

而有了版本控制后,只需要为该应用发布一个新版本即可,老版本依然被客户使用,客户收到通知时可以根据自身情况和进度慢慢将业务切换到新版本 API 上。

开发者创建 API 时会新建一个dev 版本的 API,在控制台对 API 的修改会实时更新到dev版本,调试功能将默认调用dev版本。

应用的默认版本为latest,指向最新发布的一个版本,前端在调用 API 时如果未指定 API 版本,将会默认使用latest

当开发者发布应用版本后,所有 API 都会创建一个该版本的镜像供用户使用,类似于 NPM 包的概念,而且镜像版本不支持修改和删除。

发布应用版本将会为当前 dev 版本的创建两个镜像,一个是以版本号为基础的镜像,一个是latest版本。

点击发布时可以选择版本号,假如我们已经拥有一个1.0.0版本的应用修改后即将发布版本,那么版本号有三种选择,选大版本则是2.0.0,适用于有大量更新的情况;选中版本是1.1.0,适用于有特性更新的情况;选小版本是1.0.1,适用于小修小补的情况。

createVersion

API 配置#

API 配置区域如图所示:

apiSetting

最上面的是 API 开关,关闭时将不再提供服务。

API 成本由系统自动根据步骤计算得出。

API 定价是开发者自定义的,不能低于成本。

当用户的一个请求过来时,用户的环境会扣除 API 定价的 RU,开发者会收到 API 定价-API 成本的 RU 利润。开发者可以兑换赚取的 RU 到自己的环境,或者在财务中心进行提现。

尽量将定价设置为合理范围,用户在选择应用时也会考虑是否有不合理的定价 API,10000×1 > 100×10,所以用的人多比定价贵更好,但是部分非常有价值的 API 可以合理调高。

再下方是选择返回的步骤数据,比如说右侧步骤中有两个 check 和 user ,一个是你进行逻辑判断的步骤,一个是查询相关数据步骤,而应用使用者在这里其实并不需要知道 check 的结果,那么只选择 user 步骤返回就行。步骤数据默认是全部返回的。

当你将是否需要token开关打开时,就说明这个 API 需要从请求 headers 中的 authorization 鉴权用户 token 来证明该请求是正常来自用户的,同时在后面的步骤中才能在值来源中拿到token数据userId等信息。用户的 token 来自于 jwt 步骤,是用户登录时得到并保存在用户本地的。

所有非公开的 API 都要打开这一项,从而保护你的 API 不受恶意攻击。

如需了解更详细的 token 解释,可以查看用户系统最佳实践。

有 token 后可以进一步设置该 API 所需要的的权限。

apiRight

选择无需权限代表不会前置检查权限,由后续的步骤中做相应处理。

选择简单权限后需要设置权限组,填写相关权限项点击对号添加到权限组内。这会检查用户 token 中的数据项rights,两者都是数组类型,如果有一项相符,则权限通过。这种由 token 包含权限信息的模式比较简单。

选择管理员权限则代表该 API 只能由管理员 token 和步骤中的其他API步骤调用。

选择用户系统就是将会使用用户系统 Id:user应用去检测权限。这是一个内置的权限处理,如果你有其他类型的权限系统应用,想接入这里,可以联系我们。

apiUserRight

用户系统有一个表UserRight,主键为userId appId target,列为rights

此处的权限逻辑是这样的:

userId 来自于请求的 token 解析出来的数据。

appId 是本应用的 ID。

target 由下方两项决定。

这里的 目标参数来源 和步骤中的 值来源 一样,可以确定权限目标target来自于哪里,比如此处我们设置为API 参数,target 设为orgId,那么查询用户权限的target就是 API 请求中args对象的orgId值。模拟一个请求格式如下所示,那么此处要查询用户权限的target就是firstOrg

{  "body": {    "appId": "example",    "api": "test",    "version": "latest",    "args": {      "orgId": "firstOrg"    }  }}

然后下方是权限组,这里类似于简单权限,但是比较的对象就不是 token 中的数据,而是通过该用户 ID 加本应用 ID 再加上述target的值查询到的用户权限数据rights

如果还是觉得不太清晰,可以查看组织系统最佳实践文章,有实际案例解释。

API 参数#

API 参数的意思就是调用该 API 需要哪些参数,包含在上面的模拟格式中的args中。

同时,也可以自动生成 API 文档和自动检测必要参数。

如图所示:

apiArgs

它会自动生成以下文档中的参数表:

docs

当然,如果开发者要求参数为必填但请求中没有时,那么会报错:Missing required parameters

还有一些特殊参数,具体可以查看API 格式

步骤#

最后就是 API 的核心 步骤 了。

如图所示:

apiFlow

点击 添加步骤 可以增加一个步骤卡片,步骤卡片的右下角有两个按钮,左侧为 在该步骤前添加一个新步骤,右侧为 删除该步骤

我们首先输入 步骤ID 以便区分不同步骤,再选择不同的步骤类型。

各种步骤类型有不同的功能,有的 API 可能一个步骤就完成了,有的可能需要几十个步骤(当然不推荐这样做,尽量将不同功能分为多个 API)。

所有的步骤组合形成了完整的逻辑,以一个 API 接口的形式对外提供服务,从而实现各种各样的功能,成为这互联网多彩的一部分。

至于步骤的所有类型详细介绍因为字数较多,所以放在下一章。