Updated on 2022-02-21 GMT+08:00

Importing APIs to a New API Group

Function

This API is used to import Swagger APIs to a new API group. 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

POST

/v1.0/apigw/openapi

The following table lists the parameter in the URI.

Table 2 Parameter description

Parameter

Location

Mandatory

Type

Description

extend_mode

query

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 22.

x-apigateway-ratelimits

No

Object

Request throttling information. For details, see Table 24.

Table 4 Parameter description of info

Parameter

Mandatory

Type

Description

title

Yes

String

API group name

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, and MOCK.

parameters

No

Object

Backend parameters. For details, see Table 17.

backend_define

Yes

Object

Backend definition

The following backend definitions are supported:

Table 16 Parameter description of x-apigateway-backend-policies

Parameter

Mandatory

Type

Description

type

Yes

String

Backend type. The options include HTTP, HTTP-VPC, 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:

conditions

Yes

Object

Policy conditions. For details, see Table 21.

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 mockEndpoints

Parameter

Mandatory

Type

Description

result-content

Yes

String

Mock response

description

No

String

Backend description

Table 21 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 22 Parameter description of x-apigateway-access-controls

Parameter

Mandatory

Type

Description

acl_name

No

Object

Access control policy. For details, see Table 23.

Table 23 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 24 Parameter description of x-apigateway-ratelimits

Parameter

Mandatory

Type

Description

throttle_name

No

Object

Request throttling policy. For details, see Table 25.

Table 25 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 26.

Table 26 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 27 Parameter description

Parameter

Type

Description

group_id

String

API group ID

success

Array

Import success information

failure

Array

Import failure information

Table 28 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 29 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"
    }
  ]
}

Status Codes

Table 30 Status codes

Status Code

Description

200

OK

400

Bad Request

403

Forbidden

500

Server Internal Error