跳到主要内容

自定义应用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 接口的形式对外提供服务，从而实现各种各样的功能，成为这互联网多彩的一部分。

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