Overview

1. Plugin usage rules

• You can attach only one plugin of a given type to an API.

• Plugins are region-specific. You can attach a plugin only to an API in the same region. Each user can create a maximum of 1,000 plugins per region.

• Plugin policies and APIs are managed independently. A plugin policy takes effect on an API only after you attach the plugin to the API in a specified environment.

• An API must be published before you can attach a plugin to its corresponding environment.

• Attaching, detaching, or updating a plugin takes effect immediately without requiring you to republish the API. For high-risk APIs, test the plugin on a non-production API first.

• Taking an API offline does not detach its plugins. The plugins are automatically reattached when the API is republished.

• You cannot delete a plugin if it is attached to an API that is currently published or was previously published and has not been deleted.

2. Supported plugins

API Gateway supports the following plugins. The plugins are executed in the order they appear below. For configuration details, click the name of a plugin.

• CORS

• Basic auth plugin

• JWT authentication plugin

• Third-party authentication plugin

• IP-based access control

• Traffic control

• Parameter-based access control

• Caching

• Backend routing

• Circuit breaker

• Backend signature plugin

• Transformer plugin (for request transformation)

• Error code mapping

• Transformer plugin (for response transformation)

• Log masking plugin

3. Quick start

• Go to the API Gateway plugin console.

• Click Create Plugin. On the Create Plugin page, select China (Hangzhou) for the Region, enter a plugin name, such as test, and select a type from the Plugin Type drop-down list. Options include: traffic control, IP-based access control, backend signature, JWT authentication, basic auth, CORS, caching, backend routing, parameter-based access control, error code mapping, circuit breaker (dedicated instance only), third-party authentication (dedicated instance only), log masking (dedicated instance only), and Transformer (dedicated instance only). After you select a plugin type, a YAML configuration template appears in the Script Configuration section. For example, the basic configuration for traffic control includes parameters such as unit, apiDefault, userDefault, appDefault, and specials. Modify the configuration as needed.

• In the plugin console, attach the plugin to a published API.

In the Bind API dialog box, select the target API group and environment, and then click Search to find the API. Click + Add to add the API to the selected list, and then click OK to complete the binding. This action overwrites any existing plugin of the same type that is already attached to the API.

• The plugin takes effect immediately after you attach it.

4. OpenAPI reference

You can call the following API operations to manage plugins:

• CreatePlugin: Creates a plugin.

• ModifyPlugin: Modifies a plugin.

• DeletePlugin: Deletes a plugin.

• DescribePlugins: Queries plugins.

• AttachPlugin: Attaches a plugin to an API.

• DetachPlugin: Detaches a plugin from an API.

• DescribePluginApis: Queries the APIs to which a plugin is attached.

• DescribePluginsByApi: Queries the plugins that are attached to an API.

5. Limitations

• The metadata of a single plugin cannot exceed 50 KB.

• Each user can create a maximum of 1,000 plugins in each region.

• The API debugging feature in the console currently does not support the JWT authentication plugin. We recommend using Postman or the curl command for debugging.