API Gateway supports API import and export. The export function currently only supports API gateway custom yaml format export. The import function supports API gateway custom yaml format import and swagger format import.

The following describes the import and export functions of the API gateway.

Export Function

The export function currently only supports exporting in the yaml format customized by the API gateway. You can select the API you want to export in the API management interface of the console interface to export:

You can also export all the APIs of the entire group in the group management interface:

Import Function

You can import API on the group management and API management pages:

The import function supports API gateway custom yaml format import and swagger format import. You can select the import mode when importing. The API gateway import function supports three modes, namely:

• New mode: Ignore the conflicting API. Used to add an API in the group. If there is a conflict with an existing API, the import of the API will be ignored.
• Overwrite mode: Overwrite the conflicting API. When importing an API, if there is a conflict with an existing API, the existing API will be overwritten. It can be used to restore group API snapshots and other scenarios.
• Update mode: Only update existing APIs. In case of conflict, ignore the import of the corresponding API. To use this mode, you need to specify the API ID in the group for each API in the API definition to import.

You can select the import mode according to your needs.

API Gateway Custom Format Import

For import and export, the API gateway has a set of custom yaml format. You can export the API and import it in another group. Then, you do not need to perform additional configuration or modification, just import it directly. In the import interface, you can select yaml format as the import format, that is, use API gateway custom yaml to import. The group name indicates the group you want to import API into:

Swagger Format yaml Import

[Swagger](https://swagger.io/docs/specification/about/? spm=a2c4g.11186623.2.35.42ca38293zFQzI) is a specification used to describe API definitions and is widely used to define and describe APIs for back-end application services. Currently, API Gateway supports importing Swagger 2.0 files (currently only supports yaml format) to import APIs. In order to adapt to the API definition of the API gateway, we have extended Swagger. The Swagger extension of the API gateway is based on Swagger 2.0, which can create Swagger definitions of API entities and import Swagger into the API gateway for batch creation or update of API entities.

This chapter mainly introduces the Swagger-based API gateway extension and provides corresponding examples to illustrate the usage.

Swagger Extension Description

The Swagger extension of the API Gateway is based on Swagger 2.0, which can create Swagger definitions of API entities, and import Swagger into the API Gateway to create or update API entities in batches.

Swagger extension is mainly to extend swagger native Operation Object, adding extensions such as authentication, parameter mapping, and back-end services. In addition, an extension to handle any method is added to capture any http(s) request method. All extensions start with x-bce-apigw-, and the specific extension content is as follows:

Necessary Extension

This type of configuration is the configuration that the user must perform when importing the API in the API gateway.

x-bce-apigw-backend-services

Applied to Operation Object. Used to set back-end service information. The specific attributes are determined according to the back-end service type. Because the gateway supports multiple backends, multiple backend services of the same type can be configured. The backend services have multiple common attributes, such as path, type, etc., which are explained below for x-bce-apigw-backend-services.

Public property (non-mock type)

Public property (mock type)

SwaggerBackendServer and MockHeader are describled as follows

SwaggerBackendServer

MockHeader

Configuration example

x-bce-apigw-backend-services:
  path: '/a' 
  timeout: 80000 
  method: any 
  type: HTTP 
  hosts: 
  - address: 'http://baidu.com' 
    qps: 200 
    region: DEFAULT 
    subType: INSTANCE 

Optional Extension

This part is extended as an optional extension. You can add it according to your API configuration. If you don't fill it in, the gateway will fill it with corresponding default values.

x-bce-apigw-auth

Applied to Operation Object. Used to specify the authorization type of the API.

Sub-configuration item

• None

Value

• ANONYMOUS: No verification
• APP: APP's ak and sk verification (default)

Example

x-bce-apigw-auth:APP 

x-bce-apigw-api-id

Applied to Operation Object. The uuid of the API, the configuration takes effect when the import mode is update, and it is used to specify the updated api. It only takes effect in a single api configuration, and there is no global configuration.

Sub-configuration item

• None

Value

• API uuid, the uuid of the API to modify

Example

x-bce-apigw-api-id:GWAI-pxCkY5sLyMm

x-bce-apigw-mkt-enable

Applied to Operation Object. Used to specify whether releasing the API on the cloud market is allowed.

Sub-configuration item

• None

Value

• false: Not allowed (default)
• true: Allowed

Example

x-bce-apigw-mkt-enable:true 

x-bce-apigw-request-mode

Applied to Operation Object. Used to specify the mapping relationship between query parameters and back-end service parameters. Without this configuration, when there is parameter configuration, the default is mapping; when there is no parameter configuration, the default is passthrough. The three self-options do not have to co-exist, and they can be configured as required.

Sub-configuration item

• path
• query
• header
• body

Value

• PASSTHROUGH: Passthrough
• MAPPING: Mapping

Example

x-bce-apigw-requestmode:
  query:PASSTHROUGH 
  header:MAPPING 

x-bce-apigw-request-type

Applied to Operation Object. Used to specify the mapping relationship between body parameters and back-end service parameters.

Sub-configuration item

• None

Value

• FORM (default): Indicate that the request body is in the "application/x-www-form-urlencoded" format.
• STREAM: Indicate that the request body is in a non-form format. For example, if the request body is a binary file, etc., the gateway does not support mapping the body parameter of this format.

Example

x-bce-apigw-requestmode:FROM 

x-bce-apigw-backend-params

Applied to Operation Object. Constant parameters used to define back-end services.

Sub-configuration item

• constant-params: Constant parameters used to define the backend.
• system-params: System parameters used to define the backend.

Detailed description of the two configurations constant-params Configure

system-params Configure

Value

None 

Example

x-bce-apigw-backend:
  constant-params:
    - name:constanttest 
      value:5 
      location:query 
      type:String 
  system-para:
    - name:systemtest 
      location:head 
      type:BceAppId 

x-bce-apigw-backend-request-content-type

Applied to Operation Object. content type used to define the backend request value. It takes effect only when the body mapping mode is MAPPING.

Sub-configuration item

• category
• value

Value

• category Value:
     CLIENT (default): Use the content type of the client
    CUSTOM： Use the custom
    DEFAULT： Use the default gateway
  
• value： Required when the category is selected as custom.

x-bce-apigw-backend-response-content-type

Applied to Operation Object. content type used to define the backend return value.

Sub-configuration item

• None

Value

• JSON (default): application/json;chartset=utf-8
• TEXT: text/plain;chartset=utf-8
• BINARY: application/octet-stream;chartset=utf-8
• XML: application/xml;chartset=utf-8
• HTML: text/html;chartset=utf-8

Example

x-bce-apigw-backend-response-content-type: JSON 

x-bce-apigw-backend-mapping

Applied to Parameter Object. Used to set the mapping of back-end request parameters. The sub-configurations, not all, are configured as required.

Sub-configuration item

• location: This attribute only takes effect when the sub-configuration item of x-bce-apigw-requestmode is configured as the MAPPING setting, and is used to set the parameter position in the back-end service request after parameter mapping. Value taken as: path、header、query.
• name: This attribute only takes effect when the sub-configuration item of x-bce-apigw-requestmode is configured as the MAPPING setting, and is used to set the parameter name in the back-end service request after parameter mapping. If not set, use the same name as the request parameter.

Value

• Please see the description of the sub-configuration items above.

Example

x-bce-apigw-backend-mapping:
  location:query 
  name:newname 

x-bce-apigw-request-param

Applied to Parameter Object. Used to set the verification of gateway request parameters. The sub-configurations, not all, are configured as required.

Sub-configuration item

• fixed: Used to set the input parameter as a fixed value type. It shall not co-exist with the parameter attribute "required=true" at the same time. true is a fixed parameter.
• fixed-value: Used to set the fixed value of the input parameter. It takes effect only when the sub-configuration item of x-bce-apigw-request-param is fixed to true. This configuration should not co-exist at the same time as the default value.
• check: Used to set the parameter check of the input parameters.
• json-check: Used to set the json verification of the input parameters.

Value

• Please see the description of the sub-configuration items above.

Example

x-bce-apigw-request-param:
  fixed:true 
  fixed-value:5

x-bce-apigw-any-method:

Applied to [Path Item Object](https://swagger.io/specification/v2/? spm=a2c4g.11186623.2.52.5f263829AU2YBY#pathItemObject), used to set the API to accept any type of http request.

Sub-configuration item

• None

Value

• None

Example

x-bce-apigw-any-method:

x-bce-apigw-backend-error-msg

Applied to Response Object, because the gateway requires that the wrong return must contain code, message and description. So for 4xx and 5xx returns, this field must be configured.

Sub-configuration item

• None

Value

• None

Example

x-bce-apigw-backend-error-msg: 400 error 

Description

• About the use of swagger's own fields: Please use the description field built in swagger for the description of the parameters; use the enum field built in swagger for the default value of the parameter. For the use of the above fields, please refer to swagger2.0 official documents: [swagger description about parameter](https://swagger.io/specification/v2/? spm=a2c4g.11186623.2.45.39023829txUozJ#ItemsObject).
• The gateway only supports mapping body parameter in form format, and it does not support mapping but passthrough in other formats (json, binary files), etc. When the formdata type parameter exists in the Swagger configuration file, the consumes node needs to be configured. API Gateway now only supports application/x-www-form-urlencoded type. Other types of bodies should be adapted to swagger's body for marking, and the body should select passthrough.
• For mapping configuration, when there is no specific configuration, with parameter configuration, the default is mapping; without parameter configuration, the default is passthrough.
• The global parameter and response configuration is not currently supported. Please put these two configurations in the specific api.

Type Conversion Instructions

There are certain differences between the gateway and the Swagger specification in defining data types, including:

Overall Example

In order to fully explain each extension, a complete API configuration example is now provided. You can refer to the example to use the extension field.

swagger: '2.0' 
basePath: / 
info: 
  version: '0.9' 
  title: BCE Api Gateway Swagger Sample 
schemes: 
  - http 
  - https 
x-bce-apigw-auth: APP 
x-bce-apigw-mkt-enable: false 
x-bce-apigw-backend-services:
  path: '/a' 
  timeout: 80000 
  method: any 
  type: HTTP 
  hosts: 
  - address: 'http://baidu.com' 
    qps: 200 
    region: DEFAULT 
    subType: INSTANCE 
paths: 
  '/swagger/apigw/get/{userId}': 
    get: 
      operationId: swaggerget 
      schemes: 
        - http 
        - https 
      x-bce-apigw-request-mode:
        header: MAPPING 
      x-bce-apigw-mkt-enable: true 
      x-bce-apigw-api-id: GWAI-pxCkY5sLyMm
      x-bce-apigw-auth: APP 
      parameters: 
        - name: userId 
          in: path 
          required: true 
          type: string 
        - name: swaggerQuery 
          in: query 
          required: false 
          type: integer 
          format: int32 
          minimum: 0 
          maximum: 100 
          x-bce-apigw-request-param:
            fixed: true 
            fixed-value: 12
        - name: swaggerHeader 
          in: header 
          required: false 
          type: number 
          format: double 
          minimum: 0.1 
          maximum: 0.5 
          x-bce-apigw-backend-mapping:
            location: query 
            name: backendQuery 
      x-bce-apigw-backend-params:
        constant-params:
          - name: swaggerConstant 
            value: swaggerConstant 
            location: header 
            type: STRING 
        system-params:
          - name: BceAppId 
            location: header 
            type: BceAppId 
      x-bce-apigw-backend-response-content-type: JSON 
      x-bce-apigw-backend-services:
        type: MOCK 
        mockStatusCode: 200 
        mockResult: 2 
        mockHeaders: 
        - name: mockHeader 
          value: mock 
      responses: 
        '200': 
          description: 200 description 
        '400': 
          description: 400 description 
          x-bce-apigw-backend-error-msg: 4XX error 
  '/swagger/apigw/postany/{userId}': 
    post: 
      operationId: swaggerpost 
      schemes: 
        - http 
        - https 
      x-bce-apigw-request-mode:
        header: MAPPING 
        query: MAPPING 
      consumes: 
        - application/x-www-form-urlencoded
      parameters: 
        - name: userId 
          required: true 
          in: path 
          type: string 
          x-bce-apigw-backend-mapping:
            location: query 
            name: path2query 
        - name: swaggerQuery1 
          in: query 
          required: false 
          default: '1' 
          type: integer 
          format: int32 
          minimum: 0 
          maximum: 100 
          enum: [1,2,3] 
        - name: swaggerQuery2 
          in: query 
          required: false 
          type: string 
        - name: swaggerHeader 
          in: header 
          required: false 
          type: number 
          format: double 
          minimum: 0.1 
          maximum: 0.5 
          x-bce-apigw-backend-mapping:
            location: query 
            name: headtoquery 
        - name: swaggerBody 
          in: formData 
          required: true 
          type: string 
          x-bce-apigw-backend-mapping:
            location: query 
            name: bodytoquery 
      responses: 
        '200': 
          description: 200 description 
        '400': 
          description: 400 description 
          x-bce-apigw-backend-error-msg: 4XX error 
    x-bce-apigw-any-method:
      operationId: swaggerany 
      x-bce-apigw-request-mode:
        header: MAPPING 
      schemas: 
        - http 
        - https 
      x-bce-apigw-backend-services:
        path: '/a/{userId}' 
        timeout: 80000 
        method: any 
        type: HTTP 
        hosts: 
        - address: 'http://baidu.com' 
          qps: 200 
          region: DEFAULT 
          subType: INSTANCE 
      parameters: 
        - name: userId 
          in: path 
          required: true 
          default: '123465' 
          type: integer 
          format: int32 
          minimum: 0 
          maximum: 100 
        - name: swaggerHeader 
          in: header 
          required: false 
          type: number 
          format: double 
          minimum: 0.1 
          maximum: 0.5 
          x-bce-apigw-backend-mapping:
            location: query 
            name: anyheader 
      responses: 
        '200': 
          description: 200 description 
        '400': 
          description: 400 description 
          x-bce-apigw-backend-error-msg: 4XX error 
  '/swagger/apigw/vpc/{userId}': 
    get: 
      operationId: vpc 
      schemes: 
        - http 
        - https 
      x-bce-apigw-request-mode:
        header: MAPPING 
      x-bce-apigw-mkt-enable: true 
      x-bce-apigw-auth: APP 
      parameters: 
        - name: userId 
          in: path 
          required: true 
          type: string 
        - name: swaggerQuery 
          in: query 
          required: false 
          type: integer 
          format: int32 
          minimum: 0 
          maximum: 100 
          x-bce-apigw-request-param:
            fixed: true 
            fixed-value: 12
        - name: swaggerHeader 
          in: header 
          required: false 
          type: number 
          format: double 
          minimum: 0.1 
          maximum: 0.5 
          x-bce-apigw-backend-mapping:
            location: query 
            name: backendQuery 
      x-bce-apigw-backend-params:
        constant-params:
          - name: swaggerConstant 
            value: swaggerConstant 
            location: header 
            type: STRING 
        system-params:
          - name: BceAppId 
            location: header 
            type: BceAppId 
      x-bce-apigw-backend-response-content-type: JSON 
      x-bce-apigw-backend-services:
        path: '/a/{userId}' 
        timeout: 80000 
        method: any 
        type: HTTP 
        hosts: 
        - address: 'vpc-gk9p7gq8q6xf:192.168.1.1:8' 
          qps: 200 
          region: bj 
          subType: VPC 
      responses: 
        '200': 
          description: 200 description 
        '400': 
          description: 400 description 
          x-bce-apigw-backend-error-msg: 4XX error 
  '/swagger/apigw/websocket/{userId}': 
    get: 
      operationId: swaggerwesocket 
      schemes: 
        - ws 
      x-bce-apigw-backend-services:
        path: '/a' 
        timeout: 80000 
        method: get 
        type: WEBSOCKET 
        hosts: 
        - address: 'ws://baidu.com' 
          qps: 200 
          region: DEFAULT 
          subType: INSTANCE 
      x-bce-apigw-request-mode:
        header: MAPPING 
        query: MAPPING 
      consumes: 
        - application/x-www-form-urlencoded
      parameters: 
        - name: userId 
          required: true 
          in: path 
          type: string 
          x-bce-apigw-backend-mapping:
            location: query 
            name: path2query 
        - name: swaggerQuery1 
          in: query 
          required: false 
          default: '1' 
          type: integer 
          format: int32 
          minimum: 0 
          maximum: 100 
          enum: [1,2,3] 
        - name: swaggerQuery2 
          in: query 
          required: false 
          type: string 
        - name: swaggerHeader 
          in: header 
          required: false 
          type: number 
          format: double 
          minimum: 0.1 
          maximum: 0.5 
          x-bce-apigw-backend-mapping:
            location: query 
            name: headtoquery 
      responses: 
        '200': 
          description: 200 description 
        '400': 
          description: 400 description 
          x-bce-apigw-backend-error-msg: 400 error