ImportHttpApi - API Gateway - Alibaba Cloud Documentation Center

This topic is generated by a machine translation engine without any human intervention. ALIBABA CLOUD DOES NOT GUARANTEE THE ACCURACY OF MACHINE TRANSLATED CONTENT. To request a human-translated version of this topic or provide feedback on this translation, please include it in the feedback form.

Imports HTTP APIs. You can call this operation to import OpenAPI 2.0 and OpenAPI 3.0.x definition files to create REST APIs.

Debugging

You can run this interface directly in OpenAPI Explorer, saving you the trouble of calculating signatures. After running successfully, OpenAPI Explorer can automatically generate SDK code samples.

Debug

Authorization information

The following table shows the authorization information corresponding to the API. The authorization information can be used in the Action policy element to grant a RAM user or RAM role the permissions to call this API operation. Description:

Operation: the value that you can use in the Action element to specify the operation on a resource.
Access level: the access level of each operation. The levels are read, write, and list.
Resource type: the type of the resource on which you can authorize the RAM user or the RAM role to perform the operation. Take note of the following items:
- For mandatory resource types, indicate with a prefix of * .
- If the permissions cannot be granted at the resource level, All Resources is used in the Resource type column of the operation.
Condition Key: the condition key that is defined by the cloud service.
Associated operation: other operations that the RAM user or the RAM role must have permissions to perform to complete the operation. To complete the operation, the RAM user or the RAM role must have the permissions to perform the associated operations.

Operation	Access level	Resource type	Condition key	Associated operation
apig:ImportHttpApi	none	All Resources ``	none	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. OAS 2.0 and OAS 3.0 specifications are supported. YAML and JSON formats are supported. This parameter precedes over the specFileUrl parameter. However, if the file size exceeds 10 MB, use the specFileUrl parameter to pass the definition.	b3BlbmFwaTogMy4wLjAKaW5mbzoKICAgIHRpdGxlOiBkZW1vCiAgICBkZXNjcmlwdGlvbjogdGhpc2lzZGVtbwogICAgdmVyc2lvbjogIiIKcGF0aHM6CiAgICAvdXNlci97dXNlcklkfToKICAgICAgICBnZXQ6CiAgICAgICAgICAgIHN1bW1hcnk6IOiOt+WPlueUqOaIt+S/oeaBrwogICAgICAgICAgICBkZXNjcmlwdGlvbjog6I635Y+W55So5oi35L+h5oGvCiAgICAgICAgICAgIG9wZXJhdGlvbklkOiBHZXRVc2VySW5mbwogICAgICAgICAgICByZXNwb25zZXM6CiAgICAgICAgICAgICAgICAiMjAwIjoKICAgICAgICAgICAgICAgICAgICBkZXNjcmlwdGlvbjog5oiQ5YqfCiAgICAgICAgICAgICAgICAgICAgY29udGVudDoKICAgICAgICAgICAgICAgICAgICAgICAgYXBwbGljYXRpb24vanNvbjtjaGFyc2V0PXV0Zi04OgogICAgICAgICAgICAgICAgICAgICAgICAgICAgc2NoZW1hOiBudWxsCnNlcnZlcnM6CiAgICAtIHVybDogaHR0cDovL2FwaS5leGFtcGxlLmNvbS92MQo=
specFileUrl	string	No	The download URL of the API definition file. You can download the file over the Internet or by using an Object Storage Service (OSS) internal download URL that belongs to the current region. You must obtain the required permissions to download the file. For OSS URLs that are not publicly readable, refer to Download objects using presigned URLs to specify URLs that provide download permissions. Currently, only OSS URLs are supported.	https://my-bucket.oss-cn-hangzhou.aliyuncs.com/my-api/api.yaml
name	string	No	The API name. If you do not specify a name, a name is extracted from the definition file. If a name and a versioning configuration already exist, the existing API definition is updated based on the strategy field.	import-test
description	string	No	The API description, which cannot exceed 255 bytes in length. If you do not specify a description, a description is extracted from the definition file.	API for testing
versionConfig	HttpApiVersionConfig	No	The API versioning configuration. If versioning is enabled for an API and the version and name of an API to be imported are the same as those of the existing API, the existing API is updated by this import. If versioning is not enabled for an API and the name of an API to be imported are the same as that of the existing API, the existing API is updated by this import.
dryRun	boolean	No	Specifies whether to perform a dry run. If this parameter is set to true, a dry run is performed without importing the file.	false
strategy	string	No	The update policy when the API to be imported has the same version and name as an existing one. Valid values: SpectOnly: All configurations in the file take effect. SpecFirst: The file takes precedence. New APIs are created and existing ones are updated. APIs not included in the file remain unchanged. ExistFirst (default): The existing APIs take precedence. New APIs are created but existing ones remain unchanged. If this parameter is not specified, the ExistFirst policy takes effect.	ExistFirst
targetHttpApiId	string	No	The API to be updated. If this parameter is specified, this import updates only the specified API. New APIs are not created and unspecified existing APIs are not updated. Only REST APIs can be specified.	api-xxxx
resourceGroupId	string	No	The resource group ID.	rg-acfm3q4zjh7fkki
specOssConfig	object	No	The OSS information.
regionId	string	No	The region ID.	cn-hangzhou
bucketName	string	No	The bucket name.	api-1
objectKey	string	No	The full path of the file.	/test/swagger.json
deployConfigs	HttpApiDeployConfig	No	The deployment configuration.
mcpRouteId	string	No	The MCP route ID.

Response parameters

Parameter	Type	Description	Example
	object	The response parameters.
requestId	string	The request ID.	CE857A85-251D-5018-8103-A38957D71E20
code	string	The status code.	Ok
message	string	The returned message.	success
data	object	The API information.
name	string	The API name.	import-test
httpApiId	string	The API ID.	api-xxx
dryRunInfo	object	The dry run result.
successOperations	array<object>	The operations that pass the dry run.
successOperation	object	The operation information.
action	string	The action that will be performed for the operation after the dry run. Create: The operation is created. Update: The operation is updated.	Create
name	string	The operation name.	CreateUser
path	string	The operation path.	/v1/users
method	string	The HTTP method of the operation.	POST
failureOperations	array<object>	The operations that fail the dry run.
failureOperation	object	The operation information.
path	string	The operation path.	/v1/orders
method	string	The HTTP method of the operation.	GET
errorMessage	string	The error message.	Missing response definition.
successComponents	array<object>	The data structs that pass the dry run.
successComponent	object	The data struct information.
action	string	The action that will be performed for the data struct after the dry run. Create: The data struct is created. Update: The data struct is updated.	Create
name	string	The data struct name.	userDTO
failureComponents	array<object>	The data structs that fail the dry run.
failureComponent	object	The data struct information.
name	string	The data struct name.	orderDTO
errorMessage	string	The error message.	The data struct is incorrectly defined.
errorMessages	array	The error messages. If an error message is returned, the API fails to be imported.
errorMessage	string	The error message.	OpenAPI 3.1.x is not supported.
warningMessages	array	The alerts. If an alert is returned, specific operations or structs may fail to be imported.
warningMessage	string	The alert.	Parameter definition is incomplete for GET /v1/orders.
existHttpApiInfo	HttpApiApiInfo	The existing APIs. If an existing API is returned, the import updates the existing API.

Examples

Sample success responses

JSONformat

{
  "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": "Missing response definition.\n"
        }
      ],
      "successComponents": [
        {
          "action": "Create",
          "name": "userDTO"
        }
      ],
      "failureComponents": [
        {
          "name": "orderDTO",
          "errorMessage": "The data struct is incorrectly defined.\n"
        }
      ],
      "errorMessages": [
        "OpenAPI 3.1.x is not supported.\n"
      ],
      "warningMessages": [
        "Parameter definition is incomplete for GET /v1/orders.\n"
      ],
      "existHttpApiInfo": {
        "httpApiId": "api-xxx",
        "name": "test",
        "protocols": [
          "HTTP"
        ],
        "basePath": "/v1",
        "description": "for test only",
        "versionInfo": {
          "enable": true,
          "scheme": "Query",
          "headerName": "my-version",
          "queryName": "myVersion",
          "version": "v1"
        },
        "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"
              }
            ]
          }
        ],
        "ingressInfo": {
          "sourceId": "src-xxx",
          "ingressClass": "mse",
          "watchNamespace": "default",
          "environmentInfo": {
            "environmentId": "env-xxx"
          },
          "k8sClusterInfo": {
            "clusterId": "ca435c77cba1547cca9311957bcxxxxxx"
          },
          "overrideIngressIp": true
        },
        "type": "Rest",
        "resourceGroupId": "rg-xxx",
        "aiProtocols": [
          "OpenAI/v1"
        ],
        "deployConfigs": [
          {
            "customDomainIds": [
              "d-xxx"
            ],
            "environmentId": "env-xxx",
            "backendScene": "SingleService",
            "serviceConfigs": [
              {
                "serviceId": "svc-xxx",
                "weight": 100,
                "modelNamePattern": "qwen-*",
                "modelName": "qwen-max"
              }
            ],
            "policyConfigs": [
              {
                "type": "AiFallback",
                "enable": true,
                "aiFallbackConfig": {
                  "serviceIds": [
                    "svc-xxx"
                  ]
                }
              }
            ],
            "autoDeploy": true
          }
        ],
        "enabelAuth": true,
        "authConfig": {
          "authType": "Jwt",
          "authMode": "NoAuth"
        }
      }
    }
  }
}

Error codes

For a list of error codes, visit the Service error codes.

Change history

Change time	Summary of changes	Operation
2025-08-13	The internal configuration of the API is changed, but the call is not affected	View Change Details
2025-08-12	The internal configuration of the API is changed, but the call is not affected	View Change Details
2025-04-25	The internal configuration of the API is changed, but the call is not affected	View Change Details