Bulk Import HTTP APIs from OpenAPI Specs - API Gateway - Alibaba Cloud - API Gateway

With the Import HTTP API, you can import an OpenAPI 2.0 or 3.0.x definition file to create a REST API.

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	The request body.
specContentBase64	string	No	The Base64-encoded API definition. This parameter supports OpenAPI Specification (OAS) 2.0 and 3.0 in both YAML and JSON formats. This parameter takes precedence over `specFileUrl`. If the file size exceeds 10 MB, use the `specFileUrl` parameter instead.	b3BlbmFwaTogMy4wLjAKaW5mbzoKICAgIHRpdGxlOiBkZW1vCiAgICBkZXNjcmlwdGlvbjogdGhpc2lzZGVtbwogICAgdmVyc2lvbjogIiIKcGF0aHM6CiAgICAvdXNlci97dXNlcklkfToKICAgICAgICBnZXQ6CiAgICAgICAgICAgIHN1bW1hcnk6IOiOt+WPlueUqOaIt+S/oeaBrwogICAgICAgICAgICBkZXNjcmlwdGlvbjog6I635Y+W55So5oi35L+h5oGvCiAgICAgICAgICAgIG9wZXJhdGlvbklkOiBHZXRVc2VySW5mbwogICAgICAgICAgICByZXNwb25zZXM6CiAgICAgICAgICAgICAgICAiMjAwIjoKICAgICAgICAgICAgICAgICAgICBkZXNjcmlwdGlvbjog5oiQ5YqfCiAgICAgICAgICAgICAgICAgICAgY29udGVudDoKICAgICAgICAgICAgICAgICAgICAgICAgYXBwbGljYXRpb24vanNvbjtjaGFyc2V0PXV0Zi04OgogICAgICAgICAgICAgICAgICAgICAgICAgICAgc2NoZW1hOiBudWxsCnNlcnZlcnM6CiAgICAtIHVybDogaHR0cDovL2FwaS5leGFtcGxlLmNvbS92MQo=
specFileUrl	string	No	The download URL for the API definition file. The URL must be accessible from the public network or from an OSS internal network in the same region. For private OSS files, you must provide a presigned URL with download permissions. For more information, see Use a presigned URL to download the file. 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 you omit this parameter, the name is extracted from the API definition file. If an API with the same name and versioning configuration exists, the import operation updates it based on the specified `strategy`.	import-test
description	string	No	The description of the imported API. If you omit this parameter, the description is extracted from the API definition. The maximum length is 255 bytes.	测试专用API
versionConfig	HttpApiVersionConfig	No	The API versioning configuration. An import is considered an update if it matches an existing API. A match is based on the API name and version number if versioning is enabled, or only on the API name if versioning is disabled.
dryRun	boolean	No	Specifies whether to perform a dry run. If you set this parameter to `true`, the system only validates the request without performing the import.	false
strategy	string	No	The update strategy to use when the imported API matches an existing API based on its name and versioning configuration. `SpecOnly`: Overwrites the existing API with the content from the imported file. `SpecFirst`: Merges the definitions. This strategy adds new operations from the file, updates existing ones, and retains any operations that exist in the current API but not in the imported file. `ExistFirst`: Merges the definitions. This strategy adds new operations from the file but keeps existing operations unchanged. This is the default strategy if the parameter is omitted.	ExistFirst
targetHttpApiId	string	No	If specified, the import operation updates the API with this ID instead of creating a new API or matching an existing one based on its name and versioning configuration. The target API must be a REST API.	api-xxxx
resourceGroupId	string	No	The resource group ID.	rg-aek23nsa353vmra
specOssConfig	object	No	Details of the API definition file stored in OSS.
regionId	string	No	The region ID.	cn-shanghai
bucketName	string	No	The bucket name.	gms-service-prod
objectKey	string	No	The full path to the file object.	/test/swagger.json
deployConfigs	array	No	A list of deployment configurations.
	HttpApiDeployConfig	No	A deployment configuration object.
mcpRouteId	string	No	The MCP route ID.	xxx
gatewayId	string	No	The gateway ID.	gw-xxx

Response elements

Element	Type	Description	Example
	object	The response body.
requestId	string	The request ID.	CE857A85-251D-5018-8103-A38957D71E20
code	string	The status code.	Ok
message	string	The response message.	success
data	object	The data returned by the operation.
name	string	The API name.	import-test
httpApiId	string	The unique ID of the HTTP API.	api-xxx
dryRunInfo	object	The dry run result.
successOperations	array<object>	The operations that passed the dry run.
	object	An operation that passed the dry run.
action	string	The action that will be performed on the operation if the import proceeds. Valid values: `Create`: A new operation will be created. `Update`: An existing operation will be updated. Valid values: Create : Creates the operation. Update : Updates the operation.	Create
name	string	The name of the operation.	CreateUser
path	string	The path of the operation.	/v1/users
method	string	The method of the operation.	POST
failureOperations	array<object>	The operations that failed the dry run.
	object	An operation that failed the dry run.
path	string	The path of the operation.	/v1/orders
method	string	The method of the operation.	GET
errorMessage	string	The error message.	缺少响应定义。
successComponents	array<object>	The data structures that passed the dry run.
	object	A data structure that passed the dry run.
action	string	The action that will be performed on the data structure if the import proceeds. Valid values: `Create`: A new data structure will be created. `Update`: An existing data structure will be updated. Valid values: Create : Creates the data structure. Update : Updates the data structure.	Create
name	string	The name of the data structure.	userDTO
failureComponents	array<object>	The data structures that failed the dry run.
	object	A data structure that failed the dry run.
name	string	The name of the data structure.	orderDTO
errorMessage	string	The error message.	数据结构定义有误。
errorMessages	array	Global error messages that prevent the import. If this parameter is not empty, the API cannot be imported.
	string	A global error message.	OpenAPI 3.1.x 版本不支持。
warningMessages	array	Warning messages from the dry run. If this parameter is not empty, some operations or data structures may not be imported correctly.
	string	A warning message.	GET /v1/orders 参数定义不完整。
existHttpApiInfo	HttpApiApiInfo	Details of a matching existing API. If this parameter is returned, the import operation will update this API instead of creating a new one.
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": "数据结构定义有误。"
        }
      ],
      "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"
            ],
            "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"
              }
            ],
            "subDomains": [
              {
                "domainId": "d-csmn42um******",
                "name": "test",
                "protocol": "HTTP",
                "networkType": "Intranet"
              }
            ]
          }
        ],
        "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.