上架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. 填写项目基础信息

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

提示

当项目 Public = false 时，表示所有 APIs 均不能公开访问

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文档不会受到严格的访问限制保护，即只要知道文档链接的话都能访问（包括非公开的Endpoint）。

最后

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