Enabling distributed throttling

  1. Let's create a Microgateway project.

    Create a project using the command given below.

    micro-gw init <project_name>
    micro-gw init petstore
    Project 'petstore' is initialized successfully.
  2. Add the API definition(s) to petstore/api_definitions directory. A sample open API definition can be found here. Then provide the API throttling tier using the following extension at the API level or resource level.

    x-wso2-throttling-tier : "5PerMin"    
  3. Create and deploy the throttling policy in the Traffic Manager. For this example you should deploy "5PerMin" policy in Traffic Manager. You can define following throttling policies:

    • Advanced policies
    • Application policies
    • Subscription policies

    The relevant documentation can be found here.

  4. Build the Microgateway distribution for the project using the following command:

    micro-gw build <project_name>
    micro-gw build petstore
    Target: /Users/praminda/Documents/workspace/mgw/320/rc2/petstore/target/petstore.jar

    Once the above command is executed, An executable file (petstore/target/petstore.jar) is created to expose the API via WSO2 API Microgateway

  5. Open <MGW-RUNTIME-HOME>/conf/micro-gw.conf file.

  6. Enable the enabledGlobalTMEventPublishing property found inside the throttlingConfig tag. This will allow the API Microgateway to connect with the central traffic manager.

  7. In the "micro-gw.conf" file under [throttlingConfig]  configure the following. The purpose here is to configure the message broker.

    Property Default Value Description
    jmsConnectioninitialContextFactory wso2mbInitialContextFactory The message broker context factory of WSO2 API/Traffic Manager
    jmsConnectionProviderUrl amqp://admin:admin@carbon/carbon?brokerlist='tcp://localhost:5672' The message broker connection URL of WSO2 API/Traffic Manager
    jmsConnectionUsername "" The username used to establish the message broker connection
    jmsConnectionPassword "" The password used to establish the message broker connection

    The message broker connection URL. For e.g. a WSO2 API instance can be used as the Traffic Manager. In such an instance, the URL will point to the message broker inside the API Traffic Manager instance. In the micro-gw.conf file under [throttlingConfig.binary], we should list down all the configurations related to event publishing.

    Property Default value Description
    enabled true Enable the binary event publisher. If it is false, http event publisher will be enabled
    username "admin" The user name used for authentication prior to publishing events via binary publisher
    password "admin" The password used for authentication prior to publishing events via binary publisher

    The binary receiver URL(s) needs to be added as an Array using the key [[throttlingConfig.binary.URLGroup]]. If multiple receivers are provided, the Microgateway will publish events to all of them in parallel.

    Property Default value Description
    receiverURL "tcp://localhost:9611" The URL to which the thorttle events are sent.
    authURL "ssl://localhost:9711" The URL to which the credentials required for authentication, are sent.


    You can refer configurations under throttlingConfig in <MGW_HOME>/conf/default-micro-gw.conf.template to identify all the configurable components in distributed throttling. All the configurations are available in the default-micro-gw.conf.template file with their default values. If you need to change any configuration, you can add them to the micro-gw.conf file with the desired values.

  8. If you are using API Manager 3.2.0 or later version, you need to configure the API Manager Eventhub. This step is not required if you need to do only the resource level throttling or API level throttling. Refer Eventhub configuration documentation for more details.

  9. Finally, the added configurations in micro-gw.conf would look like this.

      jmsConnectionProviderUrl = "amqp://admin:admin@carbon/carbon?brokerlist='tcp://localhost:5672'"
        enabled = true
        username = "admin"
        password = "admin"
          receiverURL = "tcp://localhost:9611"
          authURL = "ssl://localhost:9711"
      enable = true
      serviceUrl = "https://localhost:9443"
      eventListeningEndpoints = "amqp://admin:admin@carbon/carbon?brokerlist='tcp://localhost:5672'"
  10. Execute the following command to start WSO2 API Microgateway with new configurations.

    gateway <path-to-executable-file>
    gateway /Users/kim/petstore/target/petstore.jar

Conditional throttling

There can be situations where certain APIs require more granular level of throttling. Assume you want to provide limited access to a certain IP range or a type of client application (identified by User-Agent header). For these scenarios, a simple throttle policy with API/resource level limits is not sufficient. To address complex throttling requirements as above, Microgateway is capable of throttling requests based on several conditions. The following types of conditions are supported.

  1. Specific IP or IP range conditions.
    This condition can be used to provide specific limits to a certain IP address or a range of IP addresses.

  2. Header conditions.
    This condition can be used to set specific limits to a certain header value.

  3. Query parameter conditions.
    Same as the header conditions, this allows applying a specific limit to a certain query parameter value.

  4. JWT claim conditions.
    This type of condition will evaluate the backend jwt and check if it has a specific claim value in it to set the throttle limit.

Configure and enable conditional throttling

  1. Open micro-gw.conf file in <MGW_HOME>/conf directory.
  2. Add/Enable below configurations to enable the required condition type.

      enabledGlobalTMEventPublishing = true
      enableHeaderConditions = true
      enableQueryParamConditions = true
      enableJwtClaimConditions = true
  3. Define the Advance Throttle Policy containing the required conditions in WSO2 API Manager. To do this follow Adding a new advanced throttling policy

  4. Conditional throttle policies are an advanced set of API and Resource level policies. Therefore you need to define the required policy to apply in the OpenAPI definition. To do that, define x-wso2-throttling-tier extension with the Advance Throttle Policy name you defined in API Manager in the above step. This extension can be defined in both API and Resource levels.

    x-wso2-basePath: /petstore/v1
    x-wso2-throttling-tier: IPPolicy
        - https://petstore.swagger.io/v2
            summary: Finds Pets by status
            x-wso2-throttling-tier: 10kPerMin