

Enabling distributed throttling¶

Let's create a Microgateway project.

Create a project using the command given below.
Format
```
micro-gw init <project_name>
```
Example
```
micro-gw init petstore
```
Response
```
Project 'petstore' is initialized successfully.
```
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.
Sample
```
x-wso2-throttling-tier : "5PerMin"    
```
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.
Build the Microgateway distribution for the project using the following command:
Format
```
micro-gw build <project_name>
```
Example
```
micro-gw build petstore
```
Response
```
BUILD SUCCESSFUL
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
Open <MGW-RUNTIME-HOME>/conf/micro-gw.conf file.
Enable the enabledGlobalTMEventPublishing property found inside the throttlingConfig tag. This will allow the API Microgateway to connect with the central traffic manager.
```
[throttlingConfig]
  enabledGlobalTMEventPublishing=true
```

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.

Note

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.

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.

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

Sample

[throttlingConfig]
  enabledGlobalTMEventPublishing=true
  jmsConnectionProviderUrl = "amqp://admin:admin@carbon/carbon?brokerlist='tcp://localhost:5672'"

  [throttlingConfig.binary]
    enabled = true
    username = "admin"
    password = "admin"
    [[throttlingConfig.binary.URLGroup]]
      receiverURL = "tcp://localhost:9611"
      authURL = "ssl://localhost:9711"

[apim.eventHub]
  enable = true
  serviceUrl = "https://localhost:9443"
  internalDataContext="/internal/data/v1/"
  username="admin"
  password="admin"
  eventListeningEndpoints = "amqp://admin:admin@carbon/carbon?brokerlist='tcp://localhost:5672'"

Execute the following command to start WSO2 API Microgateway with new configurations.
Format
```
gateway <path-to-executable-file>
```
Example
```
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.

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.
Header conditions.
This condition can be used to set specific limits to a certain header value.
Query parameter conditions.
Same as the header conditions, this allows applying a specific limit to a certain query parameter value.
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¶

Open micro-gw.conf file in <MGW_HOME>/conf directory.

Add/Enable below configurations to enable the required condition type.

[throttlingConfig]
  enabledGlobalTMEventPublishing = true
  enableHeaderConditions = true
  enableQueryParamConditions = true
  enableJwtClaimConditions = true

Define the Advance Throttle Policy containing the required conditions in WSO2 API Manager. To do this follow Adding a new advanced throttling policy
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.
API level sample
```
x-wso2-basePath: /petstore/v1
x-wso2-throttling-tier: IPPolicy
x-wso2-production-endpoints:
  urls:
    - https://petstore.swagger.io/v2
```
Resource level sample
```
paths:
  "/pet/findByStatus":
      get:
        summary: Finds Pets by status
        x-wso2-throttling-tier: 10kPerMin
```

Top