This documentation is for WSO2 API Manager 1.9.0. View documentation for the latest release.

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

  • To protect your APIs from common types of security attacks such as denial of service (DOS)
  • To regulate traffic according to infrastructure availability
  • To make an API, application or a resource available to a consumer at different levels of service, usually for monetization purpose

The following topics explain throttling:

Table of Contents
maxLevel5
minLevel5
typeflat

API-level throttling

API-level throttling tiers are defined when managing APIs using the API Publisher portal. The UI looks as follows:

Image Removed

After API-level throttling tiers are set and the API is published, at subscription time, the consumers of the API can log in to the API Store and select which tier they are interested in as follows:

Image Removed 

According to the tiers the subscriber selects, s/he is granted a maximum number of requests to the API. The default tiers are as follows:

  • Bronze: 1 request per minute
  • Silver: 5 requests per minute
  • Gold: 20 requests per minute
  • Unlimited: Allows unlimited access (you can disable the Unlimited tier by editing the <TierManagement> node of the <APIM_HOME>/repository/conf/api-manager.xml file)

Setting tier permissions: Users with Manage Tiers permission can set role-based permissions to API-level access throttling tiers. This is done using the Tier Permissions menu in the API Publisher as shown below. For each tier, you can specify a comma-separated list of roles and either Allow or Deny access to the list.

Image Removed

A subscriber logged into the API Store can consume APIs using a specific tier only if s/he is assigned to a role that is allowed access. In the API Store, the subscriber sees a list of tiers that is filtered based on the subscriber's role. Only the ALLOWED roles appear here. By default, all tiers are allowed to everyone.

Application-level throttling

Application-level throttling tiers are defined at the time an application is created in the API Store as shown below:

Image Removed

An application is a logical collection of one or more APIs and is required to subscribe to an API. Applications allow you to use a single access token to invoke a collection of APIs and to subscribe to one API multiple times with different SLA levels.

An application is available to a consumer at different levels of service. For example, if you have infrastructure limitations in facilitating more than a certain number of requests to an application at a time, the throttling tiers can be set accordingly so that the application can have a maximum number of requests within a defined time. The default throttling levels are are as follows:

  • Bronze: 1 request per minute
  • Silver: 5 requests per minute
  • Gold: 20 requests per minute
  • Unlimited: Unlimited access. The Default Application, which is provided out of the box has Unlimited tier set. You have the option to set it to a restricted limit.
Resource-level throttling

An API is made up of one or more resources. Each resource handles a particular type of request and is analogous to a method (function) in a larger API. Resource-level throttling tiers are set to HTTP verbs of an API's resources when Managing APIs using the API Publisher portal as shown below:

Image Removed
The default throttling levels are Gold, bronze, silver and unlimited, as explained in the previous sections. 
When a subscriber views an API using the API Store, s/he can see the resource-level throttling tiers using the Throttle Info tab as follows:
Image Removed
Subscribers are not allowed to change these throttling tiers. They are simply notified of the limitations.
IP-level throttling

In IP-based throttling, you can limit the number of requests sent by a client IP (e.g., 10 calls from single client).

...

Navigate to the tiers.xml file in the registry location /_system/governance/apimgt/applicationdata.
Image Removed

Add your policy. For example, the throttling policy shown below allows only 1 API call per minute for a client from 10.1.1.1 and 2 calls per minute for a client from any other IP address.

...

languagexml

...

You can define throttling in the API, application and resource levels. The final request limit granted to a given user on a given API is ultimately defined by the consolidated output of all throttling tiers together.

Image Added

Example: Lets say two users subscribed to an API using the Gold subscription, which allows 20 requests per minute. They both use the application App1 for this subscription, which again has a throttling tier set to 20 requests per minute. All resource level throttling tiers are unlimited. In this scenario, although both users are eligible for 20 requests per minute access to the API, each ideally has a limit of only 10 requests per minute. This is due to the application-level limitation of 20 requests per minute.

Table of Contents
maxLevel5
minLevel5
typeflat

API-level throttling

API-level throttling tiers are defined when managing APIs using the API Publisher portal. The UI looks as follows:

Image Added

After API-level throttling tiers are set and the API is published, at subscription time, the consumers of the API can log in to the API Store and select which tier they are interested in as follows:

Image Added 

According to the tiers the subscriber selects, s/he is granted a maximum number of requests to the API. The default tiers are as follows:

  • Bronze: 1 request per minute
  • Silver: 5 requests per minute
  • Gold: 20 requests per minute
  • Unlimited: Allows unlimited access (you can disable the Unlimited tier by editing the <TierManagement> node of the <APIM_HOME>/repository/conf/api-manager.xml file)

Setting tier permissions: Users with Manage Tiers permission can set role-based permissions to API-level access throttling tiers. This is done using the Tier Permissions menu in the API Publisher as shown below. For each tier, you can specify a comma-separated list of roles and either Allow or Deny access to the list.

Image Added

A subscriber logged into the API Store can consume APIs using a specific tier only if s/he is assigned to a role that is allowed access. In the API Store, the subscriber sees a list of tiers that is filtered based on the subscriber's role. Only the ALLOWED roles appear here. By default, all tiers are allowed to everyone.

Application-level throttling

Application-level throttling tiers are defined at the time an application is created in the API Store as shown below:

Image Added

An application is a logical collection of one or more APIs and is required to subscribe to an API. Applications allow you to use a single access token to invoke a collection of APIs and to subscribe to one API multiple times with different SLA levels.

An application is available to a consumer at different levels of service. For example, if you have infrastructure limitations in facilitating more than a certain number of requests to an application at a time, the throttling tiers can be set accordingly so that the application can have a maximum number of requests within a defined time. The default throttling levels are are as follows:

  • Bronze: 1 request per minute
  • Silver: 5 requests per minute
  • Gold: 20 requests per minute
  • Unlimited: Unlimited access. The Default Application, which is provided out of the box has Unlimited tier set. You have the option to set it to a restricted limit.
Resource-level throttling

An API is made up of one or more resources. Each resource handles a particular type of request and is analogous to a method (function) in a larger API. Resource-level throttling tiers are set to HTTP verbs of an API's resources when Managing APIs using the API Publisher portal as shown below:

Image Added
The default throttling levels are Gold, bronze, silver and unlimited, as explained in the previous sections. 
When a subscriber views an API using the API Store, s/he can see the resource-level throttling tiers using the Throttle Info tab as follows:
Image Added
Subscribers are not allowed to change these throttling tiers. They are simply notified of the limitations.
IP-level throttling

In IP-based throttling, you can limit the number of requests sent by a client IP (e.g., 10 calls from single client).

  1. Log in to the management console and click the Resources -> Browse menu.
  2. Navigate to the tiers.xml file in the registry location /_system/governance/apimgt/applicationdata.
    Image Added

  3. Add your policy. For example, the throttling policy shown below allows only 1 API call per minute for a client from 10.1.1.1 and 2 calls per minute for a client from any other IP address.

    Code Block
    languagexml
    <wsp:Policy xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"  
    
    xmlns:throttle="http://www.wso2.org/products/wso2commons/throttle">   
    <throttle:MediatorThrottleAssertion>    
    <wsp:Policy>            
    <throttle:ID throttle:type="IP">10.1.1.1</throttle:ID>            
    <wsp:Policy>                
    <throttle:Control>                    
    <wsp:Policy>                        
    <throttle:MaximumCount>1</throttle:MaximumCount>                        
    <throttle:UnitTime>60000</throttle:UnitTime>                    
    </wsp:Policy>                
    </throttle:Control>           
    </wsp:Policy>        
    </wsp:Policy>
         
    <wsp:Policy>            
    <throttle:ID throttle:type="IP">other</throttle:ID>            
    <wsp:Policy>                
    <throttle:Control>                    
    <wsp:Policy>                        
    <throttle:MaximumCount>2</throttle:MaximumCount>                        
    <throttle:UnitTime>60000</throttle:UnitTime>                   
     </wsp:Policy>                
    </throttle:Control>            
    </wsp:Policy>        
    </wsp:Policy>    
    </throttle:MediatorThrottleAssertion></wsp:Policy> 

How throttling tiers work

With capability to define throttling at three levels, the final request limit granted to a given user on a given API is ultimately defined by the consolidated output of all throttling tiers together.

Image Removed

...

...

API visibility and subscription

...