ImportHttpApi-阿里云帮助中心

Imports an HTTP API. This operation supports importing OpenAPI 2.0 and OpenAPI 3.0.x definition files as REST APIs.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.
API: The API that you can call to perform the action.
Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.
Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.
- For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.
- For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.
Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.
Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

apig:ImportHttpApi

none

*All Resource

*

None

Request syntax

POST /v1/http-apis/import HTTP/1.1

Request parameters

Parameter	Type	Required	Description	Example
body	object	No	Request body parameters.
specContentBase64	string	No	The Base64-encoded API definition. Supports OAS 2.0 and OAS 3.0 specifications in YAML or JSON format. This parameter takes precedence over specFileUrl. If the file size exceeds 10 MB, use specFileUrl instead.	b3BlbmFwaTogMy4wLjAKaW5mbzoKICAgIHRpdGxlOiBkZW1vCiAgICBkZXNjcmlwdGlvbjogdGhpc2lzZGVtbwogICAgdmVyc2lvbjogIiIKcGF0aHM6CiAgICAvdXNlci97dXNlcklkfToKICAgICAgICBnZXQ6CiAgICAgICAgICAgIHN1bW1hcnk6IOiOt+WPlueUqOaIt+S/oeaBrwogICAgICAgICAgICBkZXNjcmlwdGlvbjog6I635Y+W55So5oi35L+h5oGvCiAgICAgICAgICAgIG9wZXJhdGlvbklkOiBHZXRVc2VySW5mbwogICAgICAgICAgICByZXNwb25zZXM6CiAgICAgICAgICAgICAgICAiMjAwIjoKICAgICAgICAgICAgICAgICAgICBkZXNjcmlwdGlvbjog5oiQ5YqfCiAgICAgICAgICAgICAgICAgICAgY29udGVudDoKICAgICAgICAgICAgICAgICAgICAgICAgYXBwbGljYXRpb24vanNvbjtjaGFyc2V0PXV0Zi04OgogICAgICAgICAgICAgICAgICAgICAgICAgICAgc2NoZW1hOiBudWxsCnNlcnZlcnM6CiAgICAtIHVybDogaHR0cDovL2FwaS5leGFtcGxlLmNvbS92MQo=
specFileUrl	string	No	The download URL of the API definition file. The URL must be publicly accessible or use an internal download URL from OSS in the same region. Ensure the URL has download permissions. For non-public OSS files, see Use presigned URLs to download files and provide a URL with download permissions. Only API definition files stored in OSS are supported.	https://bucket.oss-cn-hangzhou.aliyuncs.com/*/.yaml
name	string	No	The name of the imported API. If not specified, the name is extracted from the API definition file. If an API with the same name and version configuration already exists, this import updates the existing API based on the strategy field.	import-test
description	string	No	The description of the imported API. If not specified, it is extracted from the API definition. Maximum length is 255 bytes.	测试专用API
versionConfig	HttpApiVersionConfig	No	API versioning configuration. If versioning is enabled and an API with the same name and version already exists, this import updates the existing API. If versioning is disabled and an API with the same name already exists, this import also updates the existing API.
dryRun	boolean	No	Perform a dry run. If enabled, the system only validates the import without performing the actual import.	false
strategy	string	No	Specify the update strategy when the imported API name and version configuration match an existing API. SpecOnly: Use the imported file as the sole source of truth. SpecFirst: Prefer the imported file. Add new endpoints and update existing ones. Keep endpoints not mentioned in the file unchanged. ExistFirst: Merge with priority on existing APIs. New APIs are created but existing ones remain unchanged. If this parameter is not specified, the ExistFirst policy takes effect.	ExistFirst
withGatewayExtension	boolean	No
targetHttpApiId	string	No	If specified, this import updates the target API instead of searching for an existing API by name and version configuration. The target API must be of type REST.	api-xxxx
resourceGroupId	string	No	Resource group ID.	rg-aek23nsa353vmra
specOssConfig	object	No	OSS information.
regionId	string	No	Region ID.	cn-shanghai
bucketName	string	No	Bucket name.	gms-service-prod
objectKey	string	No	Full path of the file.	/test/swagger.json
deployConfigs	array	No	API deployment configurations.
	HttpApiDeployConfig	No	Parameter
mcpRouteId	string	No	MCP route ID.	xxx
gatewayId	string	No	Gateway ID.	gw-xxx

Response elements

Element	Type	Description	Example
	object	Response.
requestId	string	Request ID.	CE857A85-251D-5018-8103-A38957D71E20
code	string	Response status code.	Ok
message	string	Response message.	success
data	object	API information.
name	string	API name.	import-test
httpApiId	string	Unique HTTP API ID.	api-xxx
dryRunInfo	object	Dry run results.
successOperations	array<object>	List of endpoints that passed the dry run.
	object	Endpoint information.
action	string	Action to perform after the dry run. Create: Create. Update: Update. Valid values: Create : Create Update : Update	Create
name	string	Endpoint name.	CreateUser
path	string	Endpoint path.	/v1/users
method	string	Endpoint method.	POST
failureOperations	array<object>	List of endpoints that failed the dry run.
	object	Endpoint information.
path	string	Endpoint path.	/v1/orders
method	string	Endpoint method.	GET
errorMessage	string	Error message.	缺少响应定义。
successComponents	array<object>	List of data structures that passed the dry run.
	object	Data structure information.
action	string	Action to perform after the dry run. Create: Create. Update: Update. Valid values: Create : Create Update : Update	Create
name	string	Data structure name.	userDTO
failureComponents	array<object>	List of data structures that failed the dry run.
	object	Data structure information.
name	string	Data structure name.	orderDTO
errorMessage	string	Error message.	数据结构定义有误。
successRoutes	array<object>
	object
action	string
name	string
failureRoutes	array<object>
	object
name	string
errorMessage	string
errorMessages	array	Error messages. If this field is not empty, the API cannot be imported successfully.
	string	A single error message.	OpenAPI 3.1.x 版本不支持。
warningMessages	array	Alert information. If this field is not empty, some endpoints or data structures might fail to import.
	string	A single alert message.	GET /v1/orders 参数定义不完整。
existHttpApiInfo	HttpApiApiInfo	Information about the existing API. If this field is not empty, the import updates this API.
mcpToolsDefinition	string

Examples

Success response

JSON format

{
  "requestId": "CE857A85-251D-5018-8103-A38957D71E20",
  "code": "Ok",
  "message": "success",
  "data": {
    "name": "import-test",
    "httpApiId": "api-xxx",
    "dryRunInfo": {
      "successOperations": [
        {
          "action": "Create",
          "name": "CreateUser",
          "path": "/v1/users",
          "method": "POST"
        }
      ],
      "failureOperations": [
        {
          "path": "/v1/orders",
          "method": "GET",
          "errorMessage": "缺少响应定义。"
        }
      ],
      "successComponents": [
        {
          "action": "Create",
          "name": "userDTO"
        }
      ],
      "failureComponents": [
        {
          "name": "orderDTO",
          "errorMessage": "数据结构定义有误。"
        }
      ],
      "successRoutes": [
        {
          "action": "",
          "name": ""
        }
      ],
      "failureRoutes": [
        {
          "name": "",
          "errorMessage": ""
        }
      ],
      "errorMessages": [
        "OpenAPI 3.1.x 版本不支持。"
      ],
      "warningMessages": [
        "GET /v1/orders 参数定义不完整。"
      ],
      "existHttpApiInfo": {
        "httpApiId": "api-xxx",
        "name": "test",
        "basePath": "/v1",
        "description": "测试专用API",
        "versionInfo": {
          "enable": true,
          "scheme": "Query",
          "headerName": "my-version",
          "queryName": "myVersion",
          "version": "v1"
        },
        "ingressInfo": {
          "sourceId": "src-xxx",
          "ingressClass": "mse",
          "watchNamespace": "default",
          "environmentInfo": {
            "environmentId": "env-xxx"
          },
          "k8sClusterInfo": {
            "clusterId": "ca435c77cba1547cca9311957bcxxxxxx"
          },
          "overrideIngressIp": true
        },
        "type": "Rest",
        "resourceGroupId": "rg-xxx",
        "enabelAuth": true,
        "authConfig": {
          "authType": "Jwt",
          "authMode": "NoAuth"
        },
        "gatewayId": "gw-cpv4sqdl****",
        "modelCategory": "Text",
        "protocols": [
          "HTTP"
        ],
        "environments": [
          {
            "environmentId": "env-xxx",
            "backendScene": "SingleService",
            "backendType": "Service",
            "serviceConfigs": [
              {
                "gatewayServiceId": "gs-xxx",
                "name": "demo-service",
                "protocol": "HTTP",
                "port": "8080",
                "weight": 100,
                "version": "v1",
                "match": {
                  "default": true,
                  "conditions": [
                    {
                      "type": "Query",
                      "key": "color",
                      "value": "gray",
                      "operator": "equal"
                    }
                  ]
                },
                "serviceId": "svc-xxx"
              }
            ],
            "customDomains": [
              {
                "domainId": "d-xxx",
                "name": "www.example.com",
                "protocol": "HTTP"
              }
            ],
            "name": "test",
            "alias": "test",
            "gatewayInfo": {
              "gatewayId": "gw-xxx",
              "name": "test"
            },
            "deployStatus": "Deployed",
            "subDomains": [
              {
                "domainId": "d-xxx",
                "name": "www.example.com",
                "protocol": "HTTP",
                "networkType": "Internet"
              }
            ]
          }
        ],
        "aiProtocols": [
          "OpenAI/v1"
        ],
        "deployConfigs": [
          {
            "environmentId": "env-xxx",
            "backendScene": "SingleService",
            "autoDeploy": true,
            "gatewayId": "gw-xx",
            "routeBackend": {
              "scene": "Single",
              "services": [
                {
                  "serviceId": "service-cq2bmmdlhtgj***",
                  "name": "item-service",
                  "protocol": "HTTP",
                  "port": 0,
                  "weight": 49,
                  "version": "v1"
                }
              ]
            },
            "gatewayInfo": {
              "gatewayId": "gw-cq7og15lhtgi6qasrj60",
              "name": "apitest-gw",
              "vpcInfo": {
                "vpcId": "vpc-uf664nyle5kh***",
                "name": "商品中心预发环境专有网络"
              },
              "engineVersion": "2.0.7"
            },
            "mock": {
              "enable": false,
              "responseCode": 200,
              "responseContent": "Mock测试"
            },
            "gatewayType": "API",
            "customDomainIds": [
              "d-xxx"
            ],
            "envDomainIds": [
              "d-xxx"
            ],
            "serviceConfigs": [
              {
                "serviceId": "svc-xxx",
                "weight": 100,
                "modelNamePattern": "qwen-*",
                "modelName": "qwen-max",
                "intentCode": "INQUIRY",
                "match": {
                  "default": true,
                  "conditions": [
                    {
                      "type": "Query",
                      "key": "color",
                      "value": "gray",
                      "operator": "equal"
                    }
                  ]
                },
                "port": 80,
                "protocol": "HTTP",
                "gatewayServiceId": "gw-svc-abc123",
                "name": "Qwen-Max-Service",
                "version": "V2",
                "multiServiceRouteStrategy": "ByWeight",
                "observabilityRouteConfig": {
                  "mode": "LeastBusy",
                  "rateLimit": 0.8,
                  "queueSize": 100
                }
              }
            ],
            "policyConfigs": [
              {
                "type": "AiFallback",
                "enable": true,
                "aiFallbackConfig": {
                  "serviceConfigs": [
                    {
                      "serviceId": "svc-******",
                      "targetModelName": "gpt-4/llama3-70b"
                    }
                  ]
                },
                "aiSecurityGuardConfig": {
                  "serviceAddress": "https://api.example.com/v1",
                  "checkRequest": true,
                  "checkResponse": true,
                  "checkRequestImage": true,
                  "checkResponseImage": true,
                  "requestCheckService": "https://checker.example.com/validate-request",
                  "responseCheckService": "https://checker.example.com/validate-response",
                  "requestImageCheckService": "https://image-checker.example.com/scan",
                  "responseImageCheckService": "https://image-checker.example.com/scan-response",
                  "riskAlertLevel": "low/medium/high",
                  "riskConfig": [
                    {
                      "type": "K8S",
                      "level": "Critical",
                      "consumerRules": {
                        "pattern": "first",
                        "matchType": "term"
                      }
                    }
                  ],
                  "bufferLimit": 50,
                  "consumerRequestCheckService": [
                    {
                      "name": "API",
                      "requestCheckService": "https://checker.example.com/validate",
                      "requestImageCheckService": "https://image-check.example.com/scan",
                      "matchType": "exact/prefix",
                      "modalityType": "text/image"
                    }
                  ],
                  "consumerResponseCheckService": [
                    {
                      "name": "AI_API",
                      "responseCheckService": "https://checker.example.com/validate-response",
                      "responseImageCheckService": "https://image-check.example.com/scan-response",
                      "matchType": "term",
                      "modalityType": "text/image"
                    }
                  ],
                  "consumerRiskLevel": [
                    {
                      "name": "APIG-UI",
                      "matchType": "term",
                      "type": "K8S",
                      "level": "Critical"
                    }
                  ]
                },
                "aiTokenRateLimitConfig": {
                  "rules": [
                    {
                      "limitType": "request/token",
                      "matchKey": "user_id/api_path",
                      "matchType": "term",
                      "matchValue": "user123",
                      "limitMode": "local",
                      "limitValue": 100
                    }
                  ],
                  "globalRules": [
                    {
                      "limitType": "request",
                      "matchKey": "user_id",
                      "matchType": "term",
                      "matchValue": "user123",
                      "limitMode": "local",
                      "limitValue": 100
                    }
                  ],
                  "enableGlobalRules": true
                },
                "aiStatisticsConfig": {
                  "logRequestContent": false,
                  "logResponseContent": false
                }
              }
            ],
            "customDomainInfos": [
              {
                "domainId": "d-cshee6dlhtgk******",
                "name": "hello-server.com",
                "protocol": "HTTP"
              }
            ],
            "envDomainInfos": [
              {
                "domainId": "",
                "name": "",
                "protocol": ""
              }
            ],
            "subDomains": [
              {
                "domainId": "d-csmn42um******",
                "name": "test",
                "protocol": "HTTP",
                "networkType": "Intranet"
              }
            ],
            "builtinRouteNames": [
              ""
            ]
          }
        ],
        "deployCntMap": {
          "key": {
            "deployedCnt": 3,
            "Cnt": 5
          }
        },
        "agentProtocols": [
          "DashScope"
        ]
      },
      "mcpToolsDefinition": ""
    }
  }
}

Error codes

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.