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.
Comment: WSODOCINTERNAL-701

...

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 Modified

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

...

Application-level throttling

APIApplication-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

...

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

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>              <throttle:MaximumCount>1</throttle:MaximumCount>      
               <wsp:Policy>                     <throttle:UnitTime>60000</throttle:UnitTime>   
                  <throttle:MaximumCount>1</throttle:MaximumCount>              </wsp:Policy>          
                  <<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>:Policy>                
    </throttle:Control>            
    </wsp:Policy>        
    </wsp:Policy>    
    </throttle:MediatorThrottleAssertion></wsp:Policy>
    Tip

    If you need to add a list of IPs / subnets for throttling you can derive the IP range from CIDR (Classless Inter-Domain Routing) notation and add it to the throttling policy configuration as follows.

    Example :

    If IP / subnet is "10.1.1.1/27" in CIDR notation, the IP address range is between "10.1.1.1 - 10.1.1.30" (if we keep 31 for broadcast). Therefore you can add throttling for the IP range as follows.

    Code Block
    <throttle:ID throttle:type="IP">10.1.1.1 - 10.1.1.30</throttle:ID>

...

API visibility and subscription

...

 When you add resources to an API, you define a URL pattern and HTTP methods. A resource can also have a list of OAuth scopes.

URL Pattern

A URL pattern can be one of the following types:

  • As a url-mapping. E.g., /state/town/*
  • As a uri-template. E.g., /{state}/{town}

The terms url-mapping and uri-template come from synapse configuration language. When an API is published in the API Publisher, a corresponding XML definition is created in the API Gateway. This XML file has a dedicated section for defining resources. See examples below:

Code Block
languagehtml/xml
<resource methods="POST GET" url-mapping="/state/town/*">
<resource methods="POST GET" uri-template="/{state}/{town}">

url-mapping performs a one-to-one mapping with the request URL, whereas the uri-template performs a pattern matching.

Parametrizing the URL allows the API Manager to map the incoming requests to the defined resource templates based on the message content and request URI. Once a uri-template is matched, the parameters in the template are populated appropriately. As per the above example, a request made to http://gatewa_host:gateway_port/api/v1/texas/houston sets the value of state to texas and the value of town to houston. You can use these parameters within the synapse configuration for various purposes and gain access to these property values through the uri.var.province and uri.var.district properties. For more information on how to use these properties, see Introduction to REST API and the HTTP Endpoint of the WSO2 ESB documentation.

Also see http://tools.ietf.org/html/rfc6570 on URI templates.

Once a request is accepted by a resource, it will be mediated through an in-sequence. Any response from the backend is handled through the out-sequence. Fault sequences are used to mediate errors that might occur in either sequence. The default in-sequence, out-sequence and fault sequences are generated when the API is published.

...


The main attributes of a method are described below:

OAuth scopes

You can define a list of OAuth scopes to an API's resource and assign one of them to each HTTP method.

Authentication type

The authentication type can be one of the following:

  • None: No authentication is applied and the API Gateway skips the authentication process
  • Application: Authentication is done by the application. The resource accepts application access tokens.
  • Application User: Authentication is done by the application user. The resource accepts user access tokens.
  • Application and Application User: Both application and application user  level authentication is applied. Note that if you select this option in the UI, it appears as Any in the API Manager's internal data storage and data representation, and Any will appear in the response messages as well.

Note that for the resources that have HTTP verbs (GET, POST etc.) requiring authentication (i.e., Auth Type is not NONE), set None as the Auth type of OPTIONS. This is to support CORS (Cross Origin Resource Sharing) between the API Store and Gateway. (The above screenshot shows this).  

The auth type is cached in the API Manager for better performance. If you change the auth type through the UI, it takes about 15 minutes to refresh the cache. During that time, the server returns the old auth type from the cache. If you want the changes to be reflected immediately, please restart the server after changing the auth type.

Response content typeYou can use this attribute to document in what type the backend sends the response back to the API Manager. Note that this attribute doesn't do any message type conversion, but used simply as a way of letting the user know what type the response will be.
ParametersParameters of an HTTP method are analogous to arguments of a function in an object-oriented programming language. A resource's parameters are cached in the resource cache at the API Gateway.

...

Cross-origin resource sharing

...

The elements are described below:

XML ElementsValuesDescription
<Enabled>True/FalseUsed to enable/disable sending CORS headers from the Gateway. By default, CORS is enabled (True). This is needed for Swagger to function properly.
<Access-Control-Allow-Origin>HTTP and HTTPS Store Address. Change the Host and Port for correct values of your store. For example, https://localhost:9443,http://localhost:9763 The value of the <Access-Control-Allow-Origin header>. Default values are API Store addresses that are required for swagger to function properly.
<Access-Control-Allow-Headers>

Header values you need to pass when invoking the API. For example, authorization, Access-Control-Allow-Origin, Content-Type

Default values are sufficient for Swagger to function.

Change your code according to the sample given here.

...

You apply scopes to an API resource at the time the API is created or modified. In the API Publisher, click the API -> Add menu (to add a new API) or the Edit link next to an existing API. Then, navigate to the Manage tab and scroll down to see the Add Scopes button under Resources. A screen such as the following appears:

Scope KeyA unique key for identifying the scope. Typically, it is prefixed by part of the API's name for uniqueness, but is not necessarily reader-friendly.
Scope NameA human-readable name for the scope. It typically says what the scope does.
Roles

The user role(s) that are allowed to obtain a token against this scope. E.g., manager, employee.

Tip

Tip: When you generate access tokens to APIs protected by scope/s, a Select Scopes button is displayed in the My Subscriptions page for you to select the scope/s first and then generate the token to it.


...

Code Block
curl -k -d "grant_type=password&username=admin&password=admin&scope=some_random_scope" -H "Authorization: Basic WmRFUFBvZmZwYVFnR25ScG5iZldtcUtSS3IwYTpSaG5ocEVJYUVCMEN3T1FReWpiZTJwaDBzc1Vh," -H "Content-Type: application/x-www-form-urlencoded" https://10.100.0.3:8243/token

...