上架API项目

如果你是API供应商，提供优质的API资源，只需要以下几步便可方便接入本平台。

准备工作

为了更好的统一管理维护API，我们对接入的API有以下要求

1. 需返回JSON格式
2. response的顶层字段需要满足以下要求

字段名称	描述
code	(必填)返回码，整数类型，根据此字段判断返回业务状态，详细含义见下方表格
forceDeduct	(可选)返回true则强制扣费，如果返回false或不传则以code值进行判断是否扣费
result	(可选)完整的原始返回结果，其字段结构与解释应由供应商提供
msg	(可选)请求失败原因
creditsDeduct	(可选)使用动态定价计划时, 通过此字段返回本次API调用扣除的积分数量, 此值默认不能超过 0.2

扣费规则

某些场景下code字段不适合用于判断是否应该扣费，针对这种情况，我们增加了forceDeduct字段

当forceDeduct = true 或 code = 0的时候进行扣费

考虑到现实场景，我们会根据forceDeduct = true 或 code = 0来统计成功请求次数

我们会根据以上的字段构造返回给用户的结果，举例如下:

供应商返回给平台

{
  "code": 0,
  "result": {
    "data": "sample"
  },
  "otherField1": "value1",  // 此字段会被忽略
  "otherField2": "value2"  // 此字段会被忽略
}

平台返回给用户

{
  "code": 0,
  "credits": 0.001,  // 假定单价为0.001USD
  "result": {
    "data": "sample"
  }
}

对于请求失败的返回样例如下:

供应商返回给平台

{
  "code": 1000,
  "msg": "Reason for request failure",
  "otherField1": "value1",  // 此字段会被忽略
  "otherField2": "value2"  // 此字段会被忽略
}

平台返回给用户

{
  "code": 1000,
  "msg": "Reason for request failure",
}

提示

注意，这里不会检查 response status

3. code字段的含义与解释

code	描述
0	请求成功，会根据定价计划进行扣费
1000	内部错误
1001	参数错误
1002	请求资源不存在，可能被删除
1003	内部处理较忙，请稍后重试
1004	权限不足（通常由平台返回）
1005	余额（通常由平台返回）

步骤

提示

截图使用英文作为默认语言，但并不影响流程以及页面布局

1. 创建项目

进入控制台商户中心，点击创建项目，产品类型选择API

创建完成后，点击项目进入管理页面

2. 填写项目基础信息

进入项目主页可以完善相关配置，你可以上传自己的项目封面图，最后点击保存以生效

3. 创建API接入点

提示

为了给用户更好的使用体验，强烈建议填写文档链接，描述result里的字段结构与解释。

Slug 字段为接入点的API子路径，不能重复，建议填写具有业务含义的path。

后端URL 是供应商提供的API URL，此字段不对外公开。

关于Params Schema与Json Schema的填写

Params Schema与Json Schema（GET请求不应该配置Json Schema）的结构一样，用于描述参数信息以及自动生成文档

本平台会检查必传参数是否缺失，这只是最基础的参数检查，无法保证用户一定传递了正确的参数，因此供应商也应该对参数进行校验

字段	是否必传	描述
name	必须	参数名称
required	必须	判断参数是否必传，bool取值
type	可选	类型,取值范围为:["number", "string", "file", "array", "object", "int", "long", "date", "boolean"]
defaultValue	可选	默认值，当参数为非必传时建议填写
desc	可选	字段解释
example	可选	字段示例

示例

[
  {
    "name": "bindId",
    "desc": "绑定用户ID",
    "required": true,
    "defaultValue": "",
    "type": "string",
    "example": "123"
  },
  {
    "name": "productId",
    "desc": "产品ID",
    "required": true,
    "defaultValue": "",
    "type": "string",
    "example": "123456"
  }
]

4. 配置定价计划

提示

阶梯定价 将最后阶梯价格设置为0时，可以等效于包天价

动态定价 需要API返回结果里的 creditsDeduct 字段指定本次调用的费用

动态定价限制

由于动态定价计划带来的不确定性和扣费风险, 我们规定单次请求动态价格最大不能超过 0.2 USD, 超过的话依旧会以 0.2 USD 进行计费

如果选择动态定价计划但是没有传 creditsDeduct 字段, 将不进行扣费

5. 上线

进入项目主页，将状态设置为在线，即可完成上线。平台还会根据API的配置信息自动生成接口文档。

最后

API的配置在修改后会立即生效，所以请谨慎操作，尤其是不要轻易修改 Slug 、Status 等会对当前使用用户产生影响的配置。