API 属性说明

属性

必填项

说明

API 名称

是

• 用于识别 API。

• 支持中文、英文、数字、下划线（_）、连接符（-），且只能以英文和中文开头。32 个字符以内。

• 同一个 工作空间下 API 名称不能相同。

是否基于已有API创建

否

• 默认关闭

• 开启后可选择已创建的 API 作为模板。

API 分组

是

• 用于将 API 进行逻辑的分组，分组下的 API 相同的分组 ID 进行隔离。

• 同一个环境下，API 分组名称不能相同。

• API 分组名称：支持英文字母、中文、数字、下划线（_）、连接符（-），32 个字符以内。

API 描述

否

用于描述 API 的作用等，64 个字符以内。

应用

是

• 应用：表示 API 发布后支持 web 浏览器、H5 容器、小程序、JS、业务系统的调用。

• mPaas移动应用：表示 API 发布后支持 mPaaS 移动客户端（iOS、Android）的调用。

• 应用以及 mPaas 移动应用：表示 API 发布后支持 web 浏览器、H5 容器、小程序、JS、业务系统的调用，同时也支持 mPaaS 移动客户端（iOS、Android）的调用。

OperationType

是

• 针对 mPaaS 移动应用设置的 API 服务标识，用于定位要访问的资源。

• 支持英文字母、数字、英文句号（.），200 字符以内。

• 需按照 com.xxx.opt1的格式输入。

请求路径

是

• 表示请求的资源的 URL，通过请求路径可以定位到要请求的资源。

• 支持英文字母、数字、下划线（_）、连接符（-），200 字符以内。

• 以斜杠（/ ）开头，不能以斜杠（/ ）结尾，格式示例：/getUserInfo。

• 支持占位符模式 /home/{id}，如果需要占位符透传控制面，API 的后端请求路径需要为空。

方法

是

表明要对给定的 HTTP 资源执行的操作：

• GET：检索服务器中的数据。

• POST：将数据发送到服务器进行处理。

• PUT：更新服务器中存储的数据。

• DELETE：删除服务器中的数据。

路径匹配规则

是

• 绝对匹配：调用时完全匹配以上填写的路径，例如：/path。

• 前缀匹配：以请求路径为前缀，可匹配多个前缀一样的不同路径，例如：填写 /path的匹配效果为 /path/*。

安全认证

是

• 根据实际需要自行选择。支持密钥认证、无需认证、OAuth 认证、Key-Auth 认证、Basic-Auth 认证和 JWT 认证。

接口名称

是

• 客户端 RPC 服务或者 DUBBO 服务需要订阅的接口名称。

• API 接口名称，支持英文字母、数字、英文句号（.）、冒号（:）、@，以小写字母作为开头。

• 格式示例：com.alipay.testapp.facade.ConfigFacade:1.0@DEFAULT。

服务标识

否

选填，支持通过 uniqueId 指定服务。

方法名

是

• 客户端 RPC 服务或者 DUBBO 服务需要订阅的接口名称。

• API 服务方法名，支持英文字母、数字组成，以字母作为开头。

• 格式示例：getUserID。

报文类型

是

表示请求和响应中的媒体类型信息，用来告诉服务端如何处理请求的数据，以及告诉客户端（一般是浏览器）如何解析响应的数据。

报文编码

是

表示客户端接受文本内容的字符集样式。

实体参数

否

客户端 DUBBO 服务接口方法使用的实体参数全路径，例如：Ljava/lang/String，自定义参数实体时注意以分号（；）结尾。

返回参数

否

客户端 DUBBO 服务接口方法返回参数全路径，例如：Ljava/lang/String，自定义参数实体时注意以分号（；）结尾。

DUBBO 分组

否

客户端 DUBBO 服务接口订阅时的服务分组。

属性

必填项

说明

参数名

否

参数的唯一标识。

参数位置

否

• Header：自定义 API 请求头。例如 X-MyHeader: Value。

• Query：参数在请求 URL 末尾的问号 ?之后以 name=value形式出现。参数之间以 &分隔。例如 /users?role=admin&id=12345。

类型

否

• String

• Int

• Long

• Double

• Float

• Boolean

默认值

否

在 API 请求的参数值为空时使用的默认值。 默认值类型必须和参数类型一致。

描述

否

参数的业务描述。

请求 Body 类型

否

请求 Body 类型表示客户端向网关发起请求时要配置的参数，可以依赖已经创建数据模型。

API 在使用编排功能时必须选择数据模型才能实现参数转换以及透传，在 API 分组中若想要生成 SDK 必须在请求 Body 或者响应 Body 选择数据模型才能成功。

• Long

• Int

• Float

• Double

• Boolean

• Byte

• Short

• String

• List：可以选择基础类型或者数据模型作为参数模板。

• Object：需要选择数据模型作为参数模板。

• Map：可以选择基础类型或者数据模型作为参数模板。

属性

必填项

说明

成功响应示例

否

为 API 订阅者提供请求成功时的返回数据参考。

失败响应示例

否

为 API 订阅者提供请求失败时的返回数据参考。

错误码

否

HTTP 默认错误代码。

错误信息

否

自定义错误提示信息。

描述

否

错误码的业务描述。

响应body类型

否

响应的参数，可以依赖数据模型

API 在使用编排功能时必须选择数据模型才能实现参数转换以及透传，在 API 分组中若想要生成 SDK 必须在请求 Body 或者响应 Body 选择数据模型才能成功。

• Long

• Int

• Float

• Double

• Boolean

• Byte

• Short

• String

• List：可以选择基础类型或者数据模型作为参数模板。

• Object：需要选择数据模型作为参数模板。

• Map：可以选择基础类型或者数据模型作为参数模板。

属性

必填项

说明

后端服务类型

是

表示网关接收到请求后转发给的后端服务类型：

• Mock：表示如果接口后端还没有提供，使用 Mock 用于模拟一个后端服务。

• 系统集群：表示网关接收到前端请求后转发到真实业务系统的集群。

协议类型

是

表示网关接收到请求后转发给的后端服务使用的通信协议类型：

• HTTP

• SOFARPC

• SOFAREST

• DUBBO

• DUBBOX

请求路径

否

服务端的实际请求路径，不填默认使用 API 定义中的请求路径。

路径截取级数

否

仅支持数字格式。

拼接路径前缀

否

表示请求到后端时显示的路径信息，必须以 / 开头，但不能以 / 结尾。

超时时间

是

API 请求超时时间，单位为毫秒（ms），默认 3000 毫秒。

路由策略

是

表示当网关接收到语法后使用的路由策略：

• 根据 Header 路由：根据 Header 里带的参数路由

• 根据 LDC 路由：使用 LDC 单元化路由。

• 根据权重路由：数值范围为 0-100，所有规则加起来为 100。

• 根据请求路径路由：直接转发。

接口名称

是

• 服务端 RPC 服务、SOFAREST、DUBBO 服务发布的接口名称。

• API 接口名称，支持英文字母、数字、英文句号（.）、冒号（:）、@，以小写字母作为开头。

• 格式示例：com.alipay.testapp.facade.ConfigFacade:1.0@DEFAULT。

方法名

是

• 服务的 RPC 服务或者 DUBBO 服务需要订阅的接口方法名称。

• API 服务方法名，支持英文字母、数字组成，以字母作为开头。

• 格式示例：getUserID。

实体参数

否

服务端 DUBBO 服务接口方法使用的实体参数全路径，例如：Ljava/lang/String，自定义参数实体时注意以分号（；）结尾。

返回参数

否

服务端 DUBBO 服务接口方法返回参数全路径，例如：Ljava/lang/String，自定义参数实体时注意以分号（；）结尾。

DUBBO 分组

否

服务端 DUBBO 服务接口订阅时的服务分组。

系统集群

是

选择后端需要绑定的系统集群。

参数映射配置

否

配置响应参数和请求参数映射，可选已创建的参数映射规则。