Help Center/ API Gateway/ Developer Guide (Paris Region)/ Importing and Exporting APIs/ Extended Definition

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

View PDF

Extended Definition

The extended definition of an API includes the API's special configurations on API Gateway, such as authentication mode and backend parameters.

The extended definition fields of API Gateway are as follows:

1 x-apigateway-auth-type

Meaning: Swagger-based apiKey authentication format, which defines an authentication mode provided by API Gateway.

Scope of effect: Security Scheme Object

Example:

securityDefinitions:
  apig-auth-app:
    in: header
    name: Authorization
    type: apiKey
    x-apigateway-auth-type: AppSigv1
  apig-auth-iam:
    in: header
    name: unused
    type: apiKey
    x-apigateway-auth-type: IAM

**Table 1** Parameter description
Parameter	Mandatory	Type	Description
type	Yes	String	Authentication type. Only apiKey is supported.
name	Yes	String	Name of the parameter for authentication.
in	Yes	String	Only header is supported.
description	No	String	Description about the authentication.
x-apigateway-auth-type	Yes	String	Authentication mode used on API Gateway. AppSigv1 and IAM are supported.

2 x-apigateway-request-type

Meaning: API request type, which can be public or private.

Scope of effect: Operation Object

Example:

paths:
  '/path':
    get:
      x-apigateway-request-type: 'public'

**Table 2** Parameter description
Parameter	Mandatory	Type	Description
x-apigateway-request-type	Yes	String	API visibility. The options include public and private. public: The API can be made available for sale. private: The API will not be available for sale.

3 x-apigateway-match-mode

Meaning: Request URL matching mode, which can be NORMAL or SWA.

Scope of effect: Operation Object

Example:

paths:
  '/path':
    get:
      x-apigateway-match-mode: 'SWA'

**Table 3** Parameter description
Parameter	Mandatory	Type	Description
x-apigateway-match-mode	Yes	String	API matching mode. The options include SWA and NORMAL. SWA: prefix match. For example, both /prefix/foo and /prefix/bar match /prefix, but /prefixpart does not match. NORMAL: exact match.

4 x-apigateway-cors

Meaning: Specifies whether CORS is supported. The value is of the Boolean type.

Scope of effect: Operation Object

Example:

paths:
  '/path':
    get:
      x-apigateway-cors: true

For the API request for enabling CORS, the headers listed in the following table will be added to the response.

Header	Value	Description
Access-Control-Max-Age	172800	Maximum time the response of a preflight request can be cached.
Access-Control-Allow-Origin	*	Requests from any domain are allowed.
Access-Control-Allow-Headers	X-Sdk-Date, X-Sdk-Nonce, X-Proxy-Signed-Headers, X-Sdk-Content-Sha256, X-Forwarded-For, Authorization, Content-Type, Accept, Accept-Ranges, Cache-Control, and Range	Headers that can be used by a formal request.
Access-Control-Allow-Methods	GET, POST, PUT, DELETE, HEAD, OPTIONS, and PATCH	Methods that can be used by a formal request.

5 x-apigateway-any-method

Meaning: API request method used by default if no HTTP request method is specified.

Scope of effect: Path Item Object

Example:

paths:
  '/path':
    get:
      produces:
        - application/json
      responses:
        "200":
          description: "get response"
    x-apigateway-any-method:
      produces:
        - application/json
      responses:
        "200":
          description: "any response"

6 x-apigateway-backend

Meaning: API backend definition.

Scope of effect: Operation Object

Example:

paths:
  '/users/{userId}':
    get:
      produces:
        - "application/json"
      responses:
        default:
          description: "default response"
      x-apigateway-request-type: "public"
      x-apigateway-backend:
        type: "backend endpoint type"

**Table 4** Parameter description
Parameter	Mandatory	Type	Description
type	Yes	String	Backend service type. The options include HTTP, HTTP-VPC, FUNCTION, and MOCK.
parameters	No	x-apigateway-backend.parameters	Backend parameters.
httpEndpoints	No	x-apigateway-backend.httpEndpoints	HTTP backend service definition.
httpVpcEndpoints	No	x-apigateway-backend.httpVpcEndpoints	HTTP VPC backend service definition.
functionEndpoints	No	x-apigateway-backend.functionEndpoints	Function backend service definition.
mockEndpoints	No	x-apigateway-backend.mockEndpoints	Mock backend service definition.

6.1 x-apigateway-backend.parameters

Meaning: API backend service definition.

Scope of effect: x-apigateway-backend

Example:

paths:
  '/users/{userId}':
    get:
      produces:
        - "application/json"
      parameters:
        - name: "X-Auth-Token"
                   description: "Authentication token"
          type: "string"
          in: "header"
          required: true
        - name: "userId"
                   description: "Username"
          type: "string"
          in: "path"
          required: true
      responses:
        default:
          description: "default response"
      x-apigateway-request-type: "public"
      x-apigateway-backend:
        type: "HTTP"
        parameters:
          - name: "userId"
            value: "userId"
            in: "query"
            origin: "REQUEST"
                       description: "Username"
          - name: "X-Invoke-User"
            value: "apigateway"
            in: "header"
            origin: "CONSTANT"
                       description: "Caller"

**Table 5** 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.

6.2 x-apigateway-backend.httpEndpoints

Meaning: HTTP backend service definition.

Scope of effect: x-apigateway-backend

Example:

paths:
  '/users/{userId}':
    get:
      produces:
        - "application/json"
      parameters:
        - name: "X-Auth-Token"
                   description: "Authentication token"
          type: "string"
          in: "header"
          required: true
      responses:
        default:
          description: "default response"
      x-apigateway-request-type: "public"
      x-apigateway-backend:
        type: "HTTP"
        httpEndpoints:
          address: "example.com"
          scheme: "http"
          method: "GET"
          path: "/users"
          timeout: 30000

**Table 6** Parameter description
Parameter	Mandatory	Type	Description
address	Yes	Array	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	Number	Backend request timeout in milliseconds. The range is 1–60,000, and the default value is 5000.

6.3 x-apigateway-backend.httpVpcEndpoints

Meaning: HTTP VPC backend service definition.

Scope of effect: x-apigateway-backend

Example:

paths:
  '/users/{userId}':
    get:
      produces:
        - "application/json"
      parameters:
        - name: "X-Auth-Token"
                   description: "Authentication token"
          type: "string"
          in: "header"
          required: true
      responses:
        default:
          description: "default response"
      x-apigateway-request-type: "public"
      x-apigateway-backend:
        type: "HTTP-VPC"
        httpVpcEndpoints:
          name: "vpc-test-1"
          scheme: "http"
          method: "GET"
          path: "/users"
          timeout: 30000

**Table 7** Parameter description
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	Number	Backend request timeout in milliseconds. The range is 1–60,000, and the default value is 5000.

6.4 x-apigateway-backend.functionEndpoints

Meaning: Function backend service definition.

Scope of effect: x-apigateway-backend

Example:

paths:
  '/users/{userId}':
    get:
      produces:
        - "application/json"
      parameters:
        - name: "X-Auth-Token"
                   description: "Authentication token"
          type: "string"
          in: "header"
          required: true
      responses:
        default:
          description: "default response"
      x-apigateway-request-type: "public"
      x-apigateway-backend:
        type: "FUNCTION"
        functionEndpoints:
          version: "v1"
          function-urn: ""
          invocation-type: "synchronous"
          timeout: 30000

**Table 8** Parameter description
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	Number	Function timeout in milliseconds. The range is 1–60,000, and the default value is 5000.

6.5 x-apigateway-backend.mockEndpoints

Meaning: Mock backend service definition.

Scope of effect: x-apigateway-backend

Example:

paths:
  '/users/{userId}':
    get:
      produces:
        - "application/json"
      parameters:
        - name: "X-Auth-Token"
                   description: "Authentication token"
          type: "string"
          in: "header"
          required: true
      responses:
        default:
          description: "default response"
      x-apigateway-request-type: "public"
      x-apigateway-backend:
        type: "MOCK"
        mockEndpoints:
          result-content: "mocked"

**Table 9** Parameter description
Parameter	Mandatory	Type	Description
result-content	Yes	String	Mock response.

7 x-apigateway-backend-policies

Meaning: API backend policy.

Scope of effect: Operation Object

Example:

paths:
  '/users/{userId}':
    get:
      produces:
        - "application/json"
      responses:
        default:
          description: "default response"
      x-apigateway-request-type: "public"
      x-apigateway-backend:
        type: "backend endpoint type"
      x-apigateway-backend-policies:
        - type: "backend endpoint type"
          name: "backend policy name"
          conditions: 
            - type: "equal/enum/pattern",
              value: "string",
              origin: "source/request_parameter",
              parameter_name: "string"

**Table 10** Parameter description
Parameter	Mandatory	Type	Description
type	Yes	String	Backend service type. The options include HTTP, HTTP-VPC, FUNCTION, and MOCK.
name	Yes	String	Backend policy name.
parameters	No	x-apigateway-backend.parameters	Backend parameters.
httpEndpoints	No	x-apigateway-backend.httpEndpoints	HTTP service definition.
httpVpcEndpoints	No	x-apigateway-backend.httpVpcEndpoints	HTTP-VPC service definition.
functionEndpoints	No	x-apigateway-backend.functionEndpoints	Function service definition.
mockEndpoints	No	x-apigateway-backend.mockEndpoints	Mock service definition.
conditions	Yes	x-apigateway-backend-policies.conditions	Policy condition array.

7.1 x-apigateway-backend-policies.conditions

Meaning: API backend policy conditions.

Scope of effect: x-apigateway-backend-policies

Example:

paths:
  '/users/{userId}':
    get:
      produces:
        - "application/json"
      responses:
        default:
          description: "default response"
      x-apigateway-request-type: "public"
      x-apigateway-backend:
        type: "backend endpoint type"
      x-apigateway-backend-policies:
        - type: "backend endpoint type"
          name: "backend policy name"
          conditions: 
            - type: "equal/enum/pattern",
              value: "string",
              origin: "source/request_parameter",
              parameter_name: "string"

**Table 11** Parameter description
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.

8 x-apigateway-ratelimit

Meaning: Request throttling policy.

Scope of effect: Operation Object

Example:

paths:
  '/path':
    get:
      x-apigateway-ratelimit: 'customRatelimitName'

9 x-apigateway-ratelimits

Meaning: Mapping between a request throttling policy name and limit values.

Scope of effect: Swagger Object

Example:

x-apigateway-ratelimits:
  customRatelimitName:
    api-limit: 200
    app-limit: 200
    user-limit: 200
    ip-limit: 200
    interval: 1
    unit: second/minute/hour
    shared: true
    special: 
      - type: APP
        limit: 100
        instance: xxxxxxxxx

**Table 12** Parameter description
Parameter	Mandatory	Type	Description
customRatelimitName	No	x-apigateway-ratelimits.policy	Name of a request throttling policy. To use a request throttling policy, set x-apigateway-ratelimit to the name of the policy.

9.1 x-apigateway-ratelimits.policy

Meaning: Definition of a request throttling policy.

Scope of effect: x-apigateway-ratelimits

Example:

x-apigateway-ratelimits:
  customRatelimitName:
    api-limit: 200
    app-limit: 200
    user-limit: 200
    ip-limit: 200
    interval: 1
    unit: MINUTE
    shared: false
    special: 
      - type: USER
        limit: 100
        instance: xxxxxxx

**Table 13** Parameter description
Parameter	Mandatory	Type	Description
api-limit	Yes	Number	Limit of API access.
user-limit	No	Number	Limit of API access for users.
app-limit	No	Number	Limit of API access for apps.
ip-limit	No	Number	Limit of API access for source IP addresses.
interval	Yes	Number	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	x-apigateway-ratelimits.policy.special Array	Special request throttling policy.

9.2 x-apigateway-ratelimits.policy.special

Meaning: Definition of a special request throttling policy.

Scope of effect: x-apigateway-ratelimits.policy

Example:

x-apigateway-ratelimits:
  customRatelimitName:
    api-limit: 200
    app-limit: 200
    user-limit: 200
    ip-limit: 200
    interval: 1
    unit: MINUTE
    shared: false
    special: 
      - type: USER
        limit: 100
        instance: xxxxxxxx

**Table 14** Parameter description
Parameter	Mandatory	Type	Description
type	Yes	String	Special request throttling policy type, which can be APP or USER.
limit	Yes	Number	Access limit.
instance	Yes	String	Object ID of an excluded app or user.

10 x-apigateway-access-control

Meaning: Access control policy.

Scope of effect: Operation Object

Example:

paths:
  '/path':
    get:
      x-apigateway-access-control: 'customAccessControlName'

11 x-apigateway-access-controls

Meaning: Mapping between an access control policy name and limit settings.

Scope of effect: Swagger Object

Example:

x-apigateway-access-controls:
  customAccessControlName:
    acl-type: "DENY"
    entity-type: "IP"
    value: 127.0.0.1,192.168.0.1/16

**Table 15** Parameter description
Parameter	Mandatory	Type	Description
customAccessControlName	No	x-apigateway-access-controls.policy	Name of an access control policy. To use a request throttling policy, set x-apigateway-access-control to the name of the policy.

11.1 x-apigateway-access-controls.policy

Meaning: Definition of an access control policy.

Scope of effect: x-apigateway-access-controls

Example:

x-apigateway-access-controls:
  customAccessControlName:
    acl-type: "DENY"
    entity-type: "IP"
    value: 127.0.0.1,192.168.0.1/16

**Table 16** Parameter description
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 are supported.
value	Yes	String	Access control values, which are separated with commas (,).