Restrictions and Compatibility

Note the following restrictions and compatibility issues when importing or exporting APIs on APIG:

Restrictions

  • APIG parameter restrictions:

    • APIG does not support the configuration of request parameters in the formData and body locations.

    • APIG does not support the configuration of parameters consumes and produces.

    • The names of header parameters are not case-sensitive.

  • Backend policy restrictions are as follows:

    • Default backend type HTTP: The HTTP and HTTP-VPC backends are supported.

    • Default backend type HTTP-VPC: The HTTP and HTTP-VPC backends are supported.

    • Default backend type function: Only the function backend is supported.

    • Default backend type mock: Only the mock backend is supported.

Compatibility

  • OpenAPI is supported.

    The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to RESTful APIs. OAS is formerly known as Swagger. APIG supports two OpenAPI specifications: Swagger 2.0 and OpenAPI 3.0. For easy understanding, in the following sections, OAS refers to OpenAPI Specification (including Swagger 2.0 and OpenAPI 3.0), Swagger refers to Swagger 2.0, and OpenAPI refers to OpenAPI 3.0.

  • Mappings between imported or exported OAS objects and APIG's objects

  • Differences in request parameter types

  • Differences in API request path template syntax

  • Extended fields supported for APIG when importing APIs

Table 1 Mappings between OAS objects and APIG's objects

Swagger Object

OpenAPI Object

(3.0.0)

APIG Object

Import

Export

info.title

info.title

API group name

Importing to a new API group: a new API group name

Importing to an existing API group: not used

An API group name consists of 3-64 characters, starting with a letter. Only letters, digits, and underscores (_) are allowed.

API group name

info.description

info.description

API group description

Importing to a new API group: description about the new group

Importing to an existing API group: not used

API group description

info.version

info.version

Version

Not used

User-defined version

The current time is used as the API group name if no name is specified.

host

server.url

API group domain name

Not used

The first user-defined domain name of an API group is preferentially used.

The independent domain name of the API group is used if the API group is not bound with any user-defined domain names.

basePath

-

-

Merged with the request path of each API

Not used

paths.path

paths.path

API request path

Merged with basePath to use as an API request path

API request path

operation.operationId

operation.operationId

API name

API name

API name

operation.description

operation.description

API description

API description

API description

operation.parameters

operation.parameters

API frontend request parameters

API request parameters

API request parameters

operation.schemes

-

API frontend request protocol

API request protocol

API request protocol

operation.responses

operation.responses

-

Not used

Default response

operation.security

operation.security

API authentication mode

API authentication mode

Used together with x-apigateway-auth-type

API authentication mode

Used together with x-apigateway-auth-type

Table 2 Differences in request parameter types

OAS

APIG

Supported Attribute

integer

long

float

double

number

maximum

minimum

default

enum

required

description

string

string

maxLength

minLength

default

enum

required

description

Other

None

None

Table 3 Differences in API request path template syntax

Syntax

OAS

APIG

/users/{userName}

Supported

Supported

/users/prefix-{userName}

/users/{userName}-suffix

/users/prefix-{userName} -suffix

Supported

Not supported for frontend request definition

Supported for backend request definition

/users/{proxy+}

Not supported

Supported for frontend request definition

Not supported for backend request definition

last updated: 2024-12-13 16:21 UTC - commit: 9ff5103dad551eb3fcc6439582ab3ab13e6670f5