Versions Compared

Key

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

Throttling allows you to limit the number of hits to an API during a given period of time, typically in cases such as the following:

  • 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

...

In addition, there is also a special tier called Unlimited, which allows unlimited access. It can be disabled by editing the <TierManagement> node of the api-manager.xml file. You can also add your own tiers to the API Manager using the instructions in section Adding New Throttling Tiers in the Admin Guide.

This section covers the following topics:

Table of Contents
maxLevel3
minLevel3

API-level throttling

API-level throttling tiers are defined when Creating and Managing APIs using the API Publisher . At 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:

...

According to the tiers s/he selects, the subscriber is granted a maximum number of requests to the API.

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 of 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.

...

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 using the API Store. For information, see  Applications and application-level throttling.

Resource-level throttling

Resource-level throttling is defined tiers are set to HTTP verbs of an API's resources by the developer at the time an API is created using the Publisher. when Managing APIs using the API Publisher portal. The UI looks as follows:
Image Added

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 RemovedImage Added
Subscribers are not allowed to change these throttling tiers. They are simply notified of the limitations.

IP-level throttling

In IP address based -level 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.
  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

  1. .

    Code Block
    language
html/
  1. xml
    <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

  • When an API is invoked, it first checks whether the request is allowed by APIapplication-level throttling limit. If the consumer an application has exceeded his/her its maximum number of allowed API requests, the new request will be terminated.
  • If APIapplication-level limit is not exceeded, it then checks whether the request is allowed by applicationresource-level throttling limit. If it has exceeded, the request will be terminated.
  • If applicationresource-level limit is not exceeded, it finally checks whether the request is allowed by resourceAPI-level throttling limit. If the limit is not exceeded, then the request will be granted.

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. For 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.

How to write a throttling policy and engage it to APIs

The steps below show how to write a throttling policy and engage it to an API pointing to a backend service.

  1. The following throttling policy allows 1000 concurrent requests to a service.

    Code Block
    languagehtml/xml
    <wsp:Policy xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
    xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
    xmlns:throttle="http://www.wso2.org/products/wso2commons/throttle"
                wsu:Id="WSO2MediatorThrottlingPolicy">
        <throttle:MediatorThrottleAssertion>
            <throttle:MaximumConcurrentAccess>1000</throttle:MaximumConcurrentAccess>
            <wsp:Policy>
                <throttle:ID throttle:type="IP">other</throttle:ID>           
            </wsp:Policy>
        </throttle:MediatorThrottleAssertion>
    </wsp:Policy>
  2. Start the API Manager, log in to its management console (https://localhost:9443/carbon) and click the Resource > Browse menu to view the registry.
  3. Click the goverence/apimgt/applicationdata path to go to its detailed view.
    Image Modified
  4. In the detail view, click the Resource link and upload the created policy file to the server as a registry resource.
  5. In the management console, select the Service Bus > Source View menu.

  6. The configurations of all APIs created in the API Manager instance opens. To engage the policy to a selected API, add it to your API definition. In this example, we add it to the login API.

    Code Block
    languagehtml/xml
    <?xml version="1.0" encoding="UTF-8"?><api xmlns="http://ws.apache.org/ns/synapse" 
    name="_WSO2AMLoginAPI_" context="/login">
        <resource methods="POST" url-mapping="/*">
            <inSequence>
                <send>
                    <endpoint>
                        <address uri="https://localhost:9493/oauth2/token"/>
                    </endpoint>
                </send>
            </inSequence>
            <outSequence>
                <send/>
            </outSequence>
        </resource>
        <handlers>
     <handler class="org.wso2.carbon.apimgt.gateway.handlers.throttling.APIThrottleHandler">
           <property name="id" value="A"/>
           <property name="policyKey" value="gov:/apimgt/applicationdata/throttle.xml"/>
           </handler> 
    <handler class="org.wso2.carbon.apimgt.gateway.handlers.ext.APIManagerExtensionHandler"/>
        </handlers>
    </api>
    Note

    Be sure to specify the same path used in step 3 in the policy key of your API definition.

  7. You have successfully engaged a throttling policy to an API.