文档首页/ API网关 APIG/ API参考/ 共享版API（仅存量用户使用）/ API管理/ 创建API
更新时间：2023-02-27 GMT+08:00
查看PDF
分享

创建API

功能介绍

添加一个API，API即一个服务接口，具体的服务能力。

API分为两部分，第一部分为面向API使用者的API接口，定义了使用者如何调用这个API。第二部分面向API提供者，由API提供者定义这个API的真实的后端情况，定义了API网关如何去访问真实的后端服务。

API的真实后端服务目前支持三种类型：传统的HTTP/HTTPS形式的web后端、函数工作流、MOCK。

URI

HTTP/HTTPS请求方法以及URI如下表所示。

表1 HTTP/HTTPS请求方法以及URI

请求方法

URI

POST

/v1.0/apigw/apis

请求消息

表2 参数说明

参数

是否必选

类型

说明

group_id

是

String

API所属的分组编号

name

是

String

API名称

长度为3 ~ 64位的字符串，字符串由中文、英文字母、数字、“_”组成，且只能以英文或中文开头。

说明：

中文字符必须为UTF-8或者unicode编码。

type

是

Integer

API类型：

  • 1：公有API
  • 2：私有API

version

否

String

API的版本

字符长度不超过16

req_protocol

否

String

API的请求协议：

  • HTTP
  • HTTPS
  • BOTH：同时支持HTTP和HTTPS

默认：HTTPS

req_method

是

String

API的请求方式：

  • GET
  • POST
  • PUT
  • DELETE
  • HEAD
  • PATCH
  • OPTIONS
  • ANY

req_uri

是

String

API的访问地址

说明：

需要服从URI规范。

match_mode

否

String

API的匹配方式：

  • SWA：前缀匹配
  • NORMAL：正常匹配（绝对匹配）

默认：NORMAL

remark

否

String

API描述

字符长度不超过255

说明：

中文字符必须为UTF-8或者unicode编码。

auth_type

是

String

API的认证方式：

  • NONE：无认证
  • APP：APP认证
  • IAM：IAM认证
  • AUTHORIZER：自定义认证

auth_opt

否

AuthOpt object

认证方式参数

authorizer_id

否

String

前端自定义认证对象的ID

backend_type

是

String

后端类型：

  • HTTP：web后端
  • FUNCTION：函数工作流
  • MOCK：模拟的后端

tag

否

String

服务名称标签

待废弃字段

tags

否

Array of string

标签

包含一个服务名称标签和若干其它标签

服务名称标签非必填，必须以APIG-SN-开头

其它标签非必填，且不能以APIG-SN-开头

cors

否

Bool

是否支持跨域

  • TRUE：支持
  • FALSE：不支持

默认：FALSE

body_remark

否

String

API请求体描述，可以是请求体示例、媒体类型、参数等信息

字符长度不超过20480

说明：

中文字符必须为UTF-8或者unicode编码。

result_normal_sample

否

String

正常响应示例，描述API的正常返回信息

字符长度不超过20480

说明：

中文字符必须为UTF-8或者unicode编码。

result_failure_sample

否

String

失败返回示例，描述API的异常返回信息

字符长度不超过20480

说明：

中文字符必须为UTF-8或者unicode编码。

response_id

否

String

分组自定义响应ID

backend_api

backend_type = HTTP时必填

字典数据类型

web后端详情

mock_info

backend_type = MOCK时必填

字典数据类型

mock后端详情

func_info

backend_type = FUNCTION时必填

字典数据类型

函数工作流后端详情

req_params

否

字典数据类型

API的请求参数列表

backend_params

否

字典数据类型

API的后端参数列表

policy_https

backend_type = HTTP时选填

字典数据类型

web策略后端列表。

policy_mocks

backend_type = MOCK时选填

字典数据类型

mock策略后端列表

policy_functions

backend_type = FUNCTION时选填

字典数据类型

函数工作流策略后端列表
表3 backend_api参数说明

参数

是否必选

类型

说明

url_domain

后端服务不使用VPC通道时，必选

String

后端服务的地址。

由域名（或IP地址）和端口号组成，总长度不超过255。格式为域名:端口（如：apig.example.com:7443）。如果不写端口，则HTTPS默认端口号为443， HTTP默认端口号为80。

支持环境变量，使用环境变量时，每个变量名的长度为3 ~ 32位的字符串，字符串由英文字母、数字、“_”、“-”组成，且只能以英文开头。

version

否

String

web后端版本

字符长度不超过16

req_protocol

是

String

请求协议：

  • HTTP
  • HTTPS

req_method

是

String

请求方式：

  • GET
  • POST
  • PUT
  • DELETE
  • HEAD
  • PATCH
  • OPTIONS
  • ANY

req_uri

是

String

请求地址

总长度不超过512，且满足URI规范。

支持环境变量，使用环境变量时，每个变量名的长度为3 ~ 32位的字符串，字符串由英文字母、数字、“_”、“-”组成，且只能以英文开头。

说明：

需要服从URI规范。

timeout

是

Integer

API网关请求后端服务的超时时间，最大60000，最小为1

单位：毫秒

remark

否

String

描述

字符长度不超过255

说明：

中文字符必须为UTF-8或者unicode编码。

vpc_status

否

Integer

是否使用VPC通道：

  • 1 : 使用VPC通道
  • 2 : 不使用VPC通道

vpc_info

如果vpc_status=1，则这个字典类型为必填信息

字典类型

VPC通道详情

authorizer_id

否

String

后端自定义认证对象的ID
表4 VPC通道参数说明

参数

是否必选

类型

说明

vpc_id

是

String

VPC通道编号

vpc_proxy_host

否

String

代理主机
表5 mock_info参数说明

参数

是否必选

类型

说明

result_content

否

String

返回结果

version

否

String

版本

字符长度不超过64

remark

否

String

描述信息

长度不超过255个字符

说明：

中文字符必须为UTF-8或者unicode编码。
表6 func_info参数说明

参数

是否必选

类型

说明

function_urn

是

String

函数URN

invocation_type

是

String

调用类型:async|sync （异步|同步）

timeout

是

Integer

API网关请求函数服务的超时时间，最大60000，最小为1

单位：毫秒

version

否

String

版本信息

字符长度不超过64

remark

否

String

描述信息

长度不超过255个字符

说明：

中文字符必须为UTF-8或者unicode编码。
表7 req_params参数说明

参数

是否必选

类型

说明

name

是

String

参数名称

长度为1 ~ 32位的字符串，字符串由英文字母、数字、“_”、“-”、“.”组成，且只能以英文开头。

type

是

String

参数类型：

  • STRING
  • NUMBER

location

是

String

参数位置：

  • PATH
  • QUERY
  • HEADER

default_value

否

String

参数默认值

sample_value

否

String

参数示例值

required

否

Integer

是否必须：

  • 1：是
  • 2：否

lacation为PATH时，required默认为1，其他场景required默认为2

valid_enable

否

Integer

是否开启校验：

  • 1：开启校验
  • 2：不开启校验

默认为2

remark

否

String

描述

字符长度不超过255

说明：

中文字符必须为UTF-8或者unicode编码。

enumerations

否

String

参数枚举值

min_num

否

Integer

参数最小值（参数类型为NUMBER时有效）

max_num

否

Integer

参数最大值（参数类型为NUMBER时有效）

min_size

否

Integer

参数最小长度

max_size

否

Integer

参数最大长度

regular

否

String

正则校验规则（暂不支持）

json_schema

否

String

JSON校验规则（暂不支持）
表8 backend_params参数说明

参数

是否必选

类型

说明

name

是

String

参数名称

长度为1 ~ 32位的字符串，字符串由英文字母、数字、“_”、“-”、“.”组成，且只能以英文开头。

location

是

String

参数位置：

  • PATH
  • QUERY
  • HEADER

origin

是

String

参数类别：

  • REQUEST
  • CONSTANT
  • SYSTEM

value

是

String

参数值

字符长度不超过255

类别为REQUEST时，值为req_params中的参数名称；

类别为CONSTANT时，值为参数真正的值；

类别为SYSTEM时，值为网关参数名称

remark

否

String

描述

字符长度不超过255

说明：

中文字符必须为UTF-8或者unicode编码。
表9 policy_https参数说明

参数

是否必选

类型

说明

name

是

String

策略后端名称

长度为3 ~ 64位的字符串，字符串由中文、英文字母、数字、“_”组成，且只能以中文或英文开头。

url_domain

后端服务不使用VPC通道时，必选

String

策略后端的Endpoint。

由域名（或IP地址）和端口号组成，总长度不超过255。格式为域名:端口（如：apig.example.com:7443）。如果不写端口，则HTTPS默认端口号为443， HTTP默认端口号为80。

支持环境变量，使用环境变量时，每个变量名的长度为3 ~ 32位的字符串，字符串由英文字母、数字、“_”、“-”组成，且只能以英文开头。

req_protocol

是

String

请求协议：

  • HTTP
  • HTTPS

req_method

是

String

请求方式：

  • GET
  • POST
  • PUT
  • DELETE
  • HEAD
  • PATCH
  • OPTIONS
  • ANY

req_uri

是

String

请求地址

总长度不超过512，且满足URI规范。

支持环境变量，使用环境变量时，每个变量名的长度为3 ~ 32位的字符串，字符串由英文字母、数字、“_”、“-”组成，且只能以英文开头。

说明：

需要服从URI规范。

timeout

否

Integer

API网关请求后端服务的超时时间，最大60000，最小为1

单位：毫秒

vpc_status

否

Integer

是否使用VPC通道：

  • 1 : 使用VPC通道
  • 2 : 不使用VPC通道

vpc_info

如果vpc_status=1，则这个字典类型为必填信息

字典类型

VPC通道详情

effect_mode

是

String

关联的策略组合模式

  • ALL
  • ANY

conditions

是

字典数据类型

策略条件列表

backend_params

否

字典数据类型

后端参数列表
表10 policy_mocks参数说明

参数

是否必选

类型

说明

name

是

String

策略后端名称

长度为3 ~ 64位的字符串，字符串由中文、英文字母、数字、“_”组成，且只能以中文或英文开头。

result_content

否

String

返回结果

effect_mode

是

String

关联的策略组合模式

  • ALL
  • ANY

conditions

是

字典数据类型

策略条件列表

backend_params

否

字典数据类型

后端参数列表
表11 policy_functions参数说明

参数

是否必选

类型

说明

name

是

String

策略后端名称

长度为3 ~ 64位的字符串，字符串由中文、英文字母、数字、“_”组成，且只能以中文或英文开头。

function_urn

是

String

函数URN

invocation_type

是

String

调用类型:

  • async（异步）
  • sync （同步）

timeout

否

Integer

API网关请求函数服务的超时时间，最大60000，最小为1

单位：毫秒

version

否

String

版本信息

字符长度不超过64

effect_mode

是

String

关联的策略组合模式

  • ALL
  • ANY

conditions

是

字典数据类型

策略条件列表

backend_params

否

字典数据类型

后端参数列表
表12 conditions参数说明

参数

是否必选

类型

说明

condition_type

策略类型为param时必选

String

策略条件：

  • exact：绝对匹配
  • enum：枚举
  • pattern：正则

condition_value

是

String

策略值

condition_origin

是

String

策略类型：

  • param：参数
  • source：源IP

req_param_name

策略类型为param时必选

String

关联的请求参数对象名称
表13 AuthOpt

参数

是否必选

类型

说明

app_code_auth_type

否

String

AppCode简易认证类型，仅在auth_type为APP时生效，默认为DISABLE：

  • DISABLE：不开启简易认证
  • HEADER：开启简易认证且AppCode位置在HEADER

请求消息样例：

{
  "auth_type": "app",
  "auth_opt": {
    "app_code_auth_type": "HEADER"
  },
  "backend_api": {
    "req_method": "get",
    "req_protocol": "http",
    "req_uri": "/test",
    "timeout": 1000,
    "url_domain": "xxxxxxxxxxx"
  },
  "backend_params": [
    {
      "location": "query",
      "name": "project_id",
      "origin": "request",
      "value": "project_id"
    },
    {
      "location": "query",
      "name": "city",
      "origin": "request",
      "value": "city"
    }
  ],
  "backend_type": "http",
  "group_id": "f71f69876f90456ca6fd18ed012fdc11",
  "name": "test",
  "req_method": "get",
  "req_params": [
    {
      "location": "path",
      "name": "project_id",
      "required": 1,
      "type": "string"
    },
    {
      "location": "query",
      "name": "city",
      "required": 2,
      "type": "string"
    }
  ],
  "req_uri": "/test/{project_id}",
  "tags": ["APIG-SN-test", "test"],
  "type": 1,
  "result_normal_sample": "hello world!"
}

响应消息

表14 参数说明

参数

类型

说明

id

String

API编号

name

String

API名称

group_id

String

API所属分组的编号

group_name

String

API所属分组的名称

status

Integer

API的状态

type

Integer

API类型

version

String

API版本

req_protocol

String

API访问协议

req_method

String

API请求方式

req_uri

String

API访问地址

auth_type

String

API认证方式

auth_opt

字段数据类型

API认证方式参数

match_mode

String

API匹配方式

register_time

Timestamp

API创建时间

update_time

Timestamp

API修改时间

remark

String

API描述

bakend_type

String

后端类型

arrange_necessary

Integer

是否需要编排

tag

String

服务名称标签，待废弃字段

tags

[]String

标签

cors

Bool

是否支持跨域访问

body_remark

String

API请求体描述，可以是请求体示例、媒体类型、参数等信息

result_normal_sample

String

正常响应示例，描述API的正常返回信息

result_failure_sample

String

失败返回示例，描述API的异常返回信息

response_id

String

分组自定义响应ID

backend_api

字典数据类型

后端服务：web后端详情

mock_info

字典数据类型

后端服务：MOCK详情

func_info

字典数据类型

后端服务：函数工作流后端详情

req_params

字典数据类型

API的请求参数列表

backend_params

字典数据类型

API的后端参数列表

policy_https

字典数据类型

web策略后端列表

policy_mocks

字典数据类型

mock策略后端列表

policy_functions

字典数据类型

函数工作流策略后端列表
表15 backend_api参数说明

参数

类型

说明

id

String

编号

status

Integer

状态

url_domain

String

后端endpoint

version

String

版本

req_protocol

String

访问协议

req_method

String

访问方式

req_uri

String

访问地址

timeout

Integer

访问超时时间，单位：毫秒

register_time

Timestamp

创建时间

update_time

Timestamp

修改时间

remark

String

描述

vpc_status

String

是否使用VPC通道

vpc_info

String

VPC通道信息
表16 mock_info参数说明

参数

类型

说明

id

String

编号

status

Integer

状态

version

String

版本

result_content

String

返回结果

register_time

Timestamp

创建时间

update_time

Timestamp

修改时间

remark

String

描述
表17 func_info参数说明

参数

类型

说明

id

String

编号

status

Integer

状态

version

String

版本

function_urn

String

函数URN

invocation_type

String

调用类型:async|sync

register_time

Timestamp

创建时间

update_time

Timestamp

更新时间

timeout

Integer

超时时间，单位：毫秒

remark

String

描述
表18 req_params参数说明

参数

类型

说明

id

String

参数编号

name

String

参数名称

type

String

参数类型

location

String

参数位置

default_value

String

参数默认值

sample_value

String

参数示例值

required

Integer

是否必须

valid_enable

Integer

是否开启校验

remark

String

描述

enumerations

String

参数枚举值

min_num

Integer

参数最小值（参数类型为NUMBER时有效）

max_num

Integer

参数最大值（参数类型为NUMBER时有效）

min_size

Integer

参数最小长度

max_size

Integer

参数最大长度

regular

String

正则校验规则（暂不支持）

json_schema

String

JSON校验规则（暂不支持）
表19 backend_params参数说明

参数

类型

说明

id

String

参数编号

req_param_id

String

对应的请求参数编号

name

String

参数名称

location

String

参数位置

origin

String

参数类别

value

String

参数值

remark

String

描述
表20 policy_https参数说明

参数

类型

说明

id

String

编号

name

String

策略后端名称

url_domain

String

策略后端endpoint

req_protocol

String

访问协议

req_method

String

访问方式

req_uri

String

访问地址

timeout

Integer

访问超时时间，单位：毫秒

vpc_status

String

是否使用VPC通道

vpc_info

String

VPC通道信息

effect_mode

String

关联的策略组合模式

conditions

字典数据类型

策略条件列表

backend_params

字典数据类型

后端参数列表
表21 policy_mocks参数说明

参数

类型

说明

id

String

编号

name

String

策略后端名称

result_content

String

返回结果

effect_mode

String

关联的策略组合模式

conditions

字典数据类型

策略条件列表

backend_params

字典数据类型

后端参数列表
表22 policy_functions参数说明

参数

类型

说明

id

String

编号

name

String

策略后端名称

version

String

版本

function_urn

String

函数URN

invocation_type

String

调用类型:async|sync

timeout

Integer

超时时间，单位：毫秒

effect_mode

String

关联的策略组合模式

conditions

字典数据类型

策略条件列表

backend_params

字典数据类型

后端参数列表
表23 conditions参数说明

参数

类型

说明

id

String

编号

condition_type

String

策略条件

condition_value

String

策略值

condition_origin

String

策略类型

req_param_name

String

关联的请求参数对象名称

req_param_id

String

关联的请求参数对象编号

req_param_location

String

关联的请求参数对象位置
表24 auth_opt参数说明

参数

类型

说明

app_code_auth_type

String

AppCode简易认证类型

响应消息样例：

{
  "name": "test",
  "type": 1,
  "version": "V0.0.1",
  "req_protocol": "HTTPS",
  "req_method": "GET",
  "req_uri": "/test/{tenant_id}",
  "auth_type": "APP",
  "auth_opt": {
    "app_code_auth_type": "HEADER"
  },
  "tags": ["APIG-SN-test", "test"],
  "cors": false,
  "match_mode": "NORMAL",
  "backend_type": "HTTP",
  "group_id": "f71f69876f90456ca6fd18ed012fdc11",
  "result_normal_sample": "hello world!",
  "id": "81efcfd94b8747a0b21e8c04144a4e8c",
  "status": 1,
  "arrange_necessary": 2,
  "register_time": "2018-08-15T03:41:11.0239936Z",
  "update_time": "2018-08-15T03:41:11.0239936Z",
  "group_name": "group0002",
  "backend_api": {
    "url_domain": "xxxxxxxxxxx",
    "req_protocol": "HTTP",
    "req_method": "GET",
    "req_uri": "/test",
    "timeout": 1000,
    "vpc_status": 2,
    "id": "3442ffd031814e3a8f133a9f1ea08453",
    "status": 1,
    "register_time": "2018-08-15T03:41:11.1019236Z",
    "update_time": "2018-08-15T03:41:11.1019236Z"
  },
  "req_params": [
    {
      "name": "tenant_id",
      "type": "STRING",
      "location": "PATH",
      "required": 1,
      "valid_enable": 2,
      "id": "593c5560e0924e00af08fb458f850ecb"
    },
    {
      "name": "city",
      "type": "STRING",
      "location": "QUERY",
      "required": 2,
      "valid_enable": 2,
      "id": "e0b91bc81ae54f8ea850848d782d6e1e"
    }
  ],
  "backend_params": [
    {
      "name": "tenant_id",
      "location": "QUERY",
      "origin": "REQUEST",
      "value": "tenant_id",
      "id": "44e03de2351e43a8b18ba9ec1e71d2e9",
      "req_param_id": "593c5560e0924e00af08fb458f850ecb"
    },
    {
      "name": "city",
      "location": "QUERY",
      "origin": "REQUEST",
      "value": "city",
      "id": "b60fbcb5b86f4f5c8705c445b9bd6325",
      "req_param_id": "e0b91bc81ae54f8ea850848d782d6e1e"
    }
  ],
  "policy_https": [{
    "conditions": [{
      "id": "44e03de2351e43a8b18ba9ec1e71d2e9",
      "condition_type": "pattern",
      "condition_value": "^[0-9]$",
      "condition_origin": "param",
      "req_param_name": "project_id",
      "req_param_id": "b60fbcb5b86f4f5c8705c445b9sda325",
      "req_param_location": "PATH"
    }],
    "backend_params": [{
      "name": "project_id",
      "value": "bbbb",
      "location": "QUERY",
      "origin": "REQUEST",
      "id": "44e03de2351e43a8b18ba9ec1e71d2e8",
      "req_param_id": "593c5560e0924e00af08fb458f850ecb"
    }],
    "effect_mode": "ANY",
    "id": "44e03de2351e43a8b18ba9ec1e71d2e8",
    "name": "policy001",
    "req_method": "GET",
    "req_protocol": "http",
    "req_uri": "/test/policy",
    "timeout": 10000,
    "url_domain": "xxxxxxxxxxx",
    "vpc_status": 2
  }]
}

状态码

表25 返回消息说明

状态码

说明

201

Created

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

500

Server Internal Error
父主题： API管理

相关文档