Importing APIs to an Existing API Group

Function

This API is used to create or update APIs in an API group by importing Swagger definitions. Swagger files in JSON or YAML format are supported.

URI

The following table lists the HTTP/HTTPS request method and URI of the API.

**Table 1**
Request Method	URI
PUT	/v1.0/apigw/openapi?group_id={0}&mode={1}

The following table lists the parameters in the URI.

**Table 2** Parameter description
Parameter	Mandatory	Type	Description
group_id	Yes	String	API group ID
mode	Yes	String	Action to be taken if a conflict occurs. Options: merge and override. merge: Retains the original API. override: Overwrites the existing API.
extend_mode	No	String	Extended definition import mode. The options include merge and override. If the extended definition conflicts with existing API definition, you can choose to retain or override the existing definition.

Request

**Table 3** Parameter description
Parameter	Mandatory	Type	Description
swagger	Yes	String	The value is fixed at 2.0.
info	Yes	Object	See Table 4.
paths	Yes	Object	See Table 5.
responses	No	Object	Common response, which can be referenced in {method}. For details, see Table 9.
securityDefinitions	Yes	Object	Security authentication mode definition. For details, see Table 13.
x-apigateway-access-controls	No	Object	Access control information. For details, see Table 23.
x-apigateway-ratelimits	No	Object	Request throttling information. For details, see Table 25.

**Table 4** Parameter description of info
Parameter	Mandatory	Type	Description
title	No	String	Name of an API group. This parameter does not take effect when the API group is imported to an existing group.
version	No	String	Version number. You can specify a version number or use the current date and time by default.
description	No	String	Description of the API group

**Table 5** Parameter description of paths
Parameter	Mandatory	Type	Description
uri	Yes	Object	API access address. For details, see Table 6.

**Table 6** Parameter description of uri
Parameter	Mandatory	Type	Description
method	Yes	Object	API access method. For details, see Table 7.

**Table 7** Parameter description of method
Parameter	Mandatory	Type	Description
operationId	No	String	API name
description	No	String	API description
schemes	No	Object	API request protocol. HTTP and HTTPS are supported.
tags	No	Object	API tags
parameters	No	Object	Request parameter definitions. For details, see Table 8.
responses	No	Object	Response definition. For details, see Table 9.
security	No	Object	Security authentication mode. For details, see Table 10.
x-apigateway-access-control	No	Object	Access control policy bound to the API
x-apigateway-backend	No	Object	Backend information. For details, see Table 15.
x-apigateway-backend-policies	No	Object	Backend policy information. For details, see Table 16.
x-apigateway-cors	No	Boolean	Indicates whether CORS is supported.
x-apigateway-match-mode	No	String	Route matching mode
x-apigateway-ratelimit	No	String	Name of the request throttling policy bound to the API
x-apigateway-request-type	No	String	API type

**Table 8** Frontend parameter description
Parameter	Mandatory	Type	Description
maximum	No	Float	Maximum value of a number type parameter
minimum	No	Float	Minimum value of a number type parameter
maxLength	No	Integer	Maximum length of a string type parameter
minLength	No	Integer	Minimum length of a string type parameter
pattern	No	String	Regular expression of the parameter value
type	No	String	Type
default	No	String	Default value
description	No	String	Parameter description
name	No	String	Parameter name
in	No	String	Parameter location, which can be path, header, query, formData, or body
required	No	Boolean	Whether the parameter is required. The parameter is required when its location is path.

**Table 9** Parameter description of responses
Parameter	Mandatory	Type	Description
default	No	Object	Default response, which will be used when no status codes are defined
status_code	No	Object	Response status code. The value is a response object. For details, see Table 11.
x-apigateway-result-failure-sample	No	String	Example response for a failed request
x-apigateway-result-normal-sample	No	String	Example response for a successful request

**Table 10** Parameter description of security
Parameter	Mandatory	Type	Description
apig-auth-type	No	Object	Security authentication mode. This parameter is a null array. Options: apig-auth-app: App authentication apig-auth-iam: IAM authentication Null: No authentication required

**Table 11** Parameter description of status_code
Parameter	Mandatory	Type	Description
description	No	String	Response description
schema	No	Object	Response body. For details, see Table 12.

**Table 12** Parameter description of schema
Parameter	Mandatory	Type	Description
description	No	String	Body description
type	No	String	Body type, which can be FORM or STREAM

**Table 13** Parameter description of securityDefinitions
Parameter	Mandatory	Type	Description
name	Yes	Object	Security authentication mode. For details, see Table 14.

**Table 14** Parameter description of name
Parameter	Mandatory	Type	Description
type	Yes	String	Authentication type. apiKey is supported.
name	Yes	String	Name of apiKey
in	Yes	String	Location of apiKey
x-apigateway-auth-type	Yes	String	Authentication type extended based on apiKey. Authentication types AppSigv1, IAM, and IAM_NONE are supported.

**Table 15** Parameter description of x-apigateway-backend
Parameter	Mandatory	Type	Description
type	Yes	String	Backend type. The options include HTTP, HTTP-VPC, FUNCTION, and MOCK.
parameters	No	Object	Backend parameters. For details, see Table 17.
backend_define	Yes	Object	Backend definition The following backend definitions are supported: httpEndpoints: See Table 18. httpVpcEndpoints: See Table 19. functionEndpoints: See Table 20. mockEndpoints: See Table 21.

**Table 16** Parameter description of x-apigateway-backend-policies
Parameter	Mandatory	Type	Description
type	Yes	String	Backend type. The options include HTTP, HTTP-VPC, FUNCTION, and MOCK.
name	No	String	Backend policy name
parameters	No	Object	Backend parameters. For details, see Table 17.
backend_define	Yes	Object	Backend definition The following backend definitions are supported: httpEndpoints: See Table 18. httpVpcEndpoints: See Table 19. functionEndpoints: See Table 20. mockEndpoints: See Table 21.
conditions	Yes	Object	Policy conditions. For details, see Table 22.
effectMode	Yes	String	Effective mode of the backend policy. The options include ANY and ALL.

**Table 17** Backend parameter description
Parameter	Mandatory	Type	Description
name	Yes	String	Parameter name, which consists of a maximum of 32 bytes, starting with a letter. Only letters, digits, periods (.), hyphens (-), and underscores (_) are allowed. The names of header parameters are not case-sensitive.
value	Yes	String	Parameter value, which is a parameter name if the parameter comes from a request
in	Yes	String	Parameter location, which can be header, query, or path
origin	Yes	String	Parameter mapping source. The options include REQUEST and CONSTANT.
description	No	String	Parameter meaning

**Table 18** Parameter description of backend httpEndpoints
Parameter	Mandatory	Type	Description
address	Yes	String	Backend service address. The format is <Domain name or IP address>:[Port number]
scheme	Yes	String	Backend request protocol. HTTP and HTTPS are supported.
method	Yes	String	Backend request method. The options include GET, POST, PUT, DELETE, HEAD, OPTIONS, PATCH, and ANY.
path	Yes	String	Backend request path, which can contain variables.
timeout	No	Integer	Backend request timeout in milliseconds. The value ranges from 1 to 60,000, and the default value is 5000.
description	No	String	Backend description

**Table 19** Parameter description of backend httpVpcEndpoints
Parameter	Mandatory	Type	Description
name	Yes	Array	VPC channel name
scheme	Yes	String	Backend request protocol. HTTP and HTTPS are supported.
method	Yes	String	Backend request method. The options include GET, POST, PUT, DELETE, HEAD, OPTIONS, PATCH, and ANY.
path	Yes	String	Backend request path, which can contain variables.
timeout	No	Integer	Backend request timeout in milliseconds. The value ranges from 1 to 60,000, and the default value is 5000.
host	No	String	VPC channel proxy host
description	No	String	Backend description

**Table 20** Parameter description of backend functionEndpoints
Parameter	Mandatory	Type	Description
function-urn	Yes	String	Function URN
version	Yes	String	Function version
invocation-type	Yes	String	Function invocation type. The value can be async or sync.
timeout	No	Integer	Function timeout in milliseconds. The value ranges from 1 to 60,000, and the default value is 5000.
description	No	String	Backend description

**Table 21** Parameter description of backend mockEndpoints
Parameter	Mandatory	Type	Description
result-content	Yes	String	Mock response
description	No	String	Backend description

**Table 22** Parameter description of conditions
Parameter	Mandatory	Type	Description
type	Yes	String	Policy condition type. The options include equal, enum, and pattern.
value	Yes	String	Policy condition value
origin	Yes	String	Policy condition source. The options include source and request.
parameter	No	String	Input parameter name if the origin parameter is set to request.

**Table 23** Parameter description of x-apigateway-access-controls
Parameter	Mandatory	Type	Description
acl_name	No	Object	Access control policy. For details, see Table 24.

**Table 24** Parameter description of acl_name
Parameter	Mandatory	Type	Description
acl-type	Yes	String	Access control effect. The options include PERMIT and DENY.
entity-type	Yes	String	Access control object. Only IP addresses and accounts are supported.
value	Yes	String	Access control values, which are separated with commas (,).

**Table 25** Parameter description of x-apigateway-ratelimits
Parameter	Mandatory	Type	Description
throttle_name	No	Object	Request throttling policy. For details, see Table 26.

**Table 26** Parameter description of throttle_name
Parameter	Mandatory	Type	Description
api-limit	Yes	Integer	Maximum number of times an API can be called
user-limit	No	Integer	Number of times the API can be called by a user
app-limit	No	Integer	Number of times the API can be called by an app
ip-limit	No	Integer	Number of times the API can be called by an IP address
interval	Yes	Integer	Throttling period
unit	Yes	String	Throttling unit, which can be SECOND, MINUTE, HOUR, or DAY
shared	No	Boolean	Whether to share the throttling limits among APIs
special	No	Object	Excluded request throttling configurations. For details, see Table 27.

**Table 27** Parameter description of special
Parameter	Mandatory	Type	Description
type	Yes	String	Excluded request throttling type, which can be APP or USER
limit	Yes	Integer	Access limit
instance	Yes	String	Excluded app or user

Example request:

{
	"swagger": "2.0",
	"info": {
		"description": "api group test",
		"title": "APIGroup_test",
		"version": "2019-09-12-17:38:10"
	},

	"paths": {
		"/test/{path}": {
			"get": {
				"security": [
					{
						"apig-auth-app": []
					}
				],
				"description": "api test",
				"schemes": [
					"https"
				],
				"operationId": "API_test",
				"parameters": [
					{
						"type": "string",
						"description": "header parameter",
						"name": "header",
						"in": "header",
						"required": true
					},
					{
						"type": "string",
						"description": "path parameter",
						"name": "path",
						"in": "path",
						"required": true
					},
					{
						"type": "number",
						"default": "123",
						"description": "query parameter",
						"name": "query",
						"in": "query"
					}
				],
				"responses": {
					"default": {
						"$ref": "#/responses/default"
					},
					"x-apigateway-result-failure-sample": "",
					"x-apigateway-result-normal-sample": "success"
				},
				"x-apigateway-backend": {
					"httpEndpoints": {
						"address": "1.1.1.1:443",
						"description": "",
						"method": "GET",
						"path": "/test/{path}",
						"scheme": "https",
						"timeout": 5000
					},
					"parameters": [
						{
							"description": "",
							"in": "HEADER",
							"name": "header",
							"origin": "REQUEST",
							"value": "header"
						},
						{
							"description": "",
							"in": "PATH",
							"name": "path",
							"origin": "REQUEST",
							"value": "path"
						},
						{
							"description": "",
							"in": "QUERY",
							"name": "query",
							"origin": "REQUEST",
							"value": "query"
						}
					],
					"type": "HTTP"
				},
				"x-apigateway-backend-policies": [
					{
						"conditions": [
							{
								"origin": "param",
								"parameter": "path",
								"type": "exact",
								"value": "path"
							},
							{
								"origin": "source",
								"parameter": "",
								"type": "",
								"value": "1.0.0.0/8"
							}
						],
						"effectMode": "ANY",
						"httpVpcEndpoints": {
							"method": "POST",
							"name": "VPC_n9ct",
							"path": "/",
							"scheme": "HTTPS",
							"timeout": 5000
						},
						"name": "policy_test",
						"type": "HTTP-VPC"
					}
				],
				"x-apigateway-cors": false,
				"x-apigateway-match-mode": "NORMAL",
				"x-apigateway-request-type": "public"
			}
		}
	},
	"responses": {
		"default": {
			"description": "response example"
		}
	},
	"securityDefinitions": {
		"apig-auth-app": {
			"type": "apiKey",
			"name": "Authorization",
			"in": "header",
			"x-apigateway-auth-type": "AppSigv1"
		},
		"apig-auth-iam": {
			"type": "apiKey",
			"name": "unused",
			"in": "header",
			"x-apigateway-auth-type": "IAM"
		}
	}
}

Response

**Table 28** Parameter description
Parameter	Type	Description
group_id	String	API group ID
success	Array	Import success information
failure	Array	Import failure information

**Table 29** Parameter description of success
Parameter	Type	Description
id	String	ID of a successfully imported API
action	String	Import type. Options: update: Updates the APIs in an existing API group. create: Creates APIs for a new API group.
method	String	Request method
path	String	Request path

**Table 30** Parameter description of failure
Parameter	Type	Description
error_code	String	Error code
error_msg	String	Error message
method	String	Request method
path	String	Request path

Example response:

{
  "group_id": "27aa2317e3514c5bb5aab5587a5e50ea",
  "success": [
    {
      "id": "aea39194d8db46408be0174b0bd15931",
      "action": "create",
      "method": "GET",
      "path": "/test01"
    }
  ],
  "failure": [
    {
      "error_code": "APIG.2011",
      "error_msg": "Parameter value does not match the rules,parameterName:backend_type",
      "method": "GET",
      "path": "/test02"
    }
  ]
}