2.1.5 Configure API Quotas - Axway-API-Management-Plus/apim-cli GitHub Wiki
Quotas can be configured via the API as well as via the application. In the case of API quotas, you store system and application default quotas. Quotas that you store for applications are configured as application quota override. On this page you will learn how quotas work and are configured in detail.
API-Quotas
A quota always consists of a list of restrictions. This allows you to combine different restrictions. For APIs you can define System- and Application-Default quotas in its API config file.
{
"name": "My API-Name",
"path": "/api/with/quotas",
"state": "published",
"version": "1.0.0",
"organization": "API Development",
"applicationQuota": {
"restrictions": [
{
"method":"*",
"type":"throttlemb",
"config":{
"period":"day",
"mb":10000,
"per":1
}
},
{ ... }
]
},
"systemQuota": {
"restrictions": [
{ ... },
{ ... }
]
}
}
Application-Quotas
If you want to give special quotas to an application, you have to configure this in the context of the application, i.e. in the application config file. These are configured as application quota overrides in API management. It is not possible to store application quotas in the API config.
{
"name": "My App Name",
"organization": "API Development",
"appQuota": {
"restrictions": [
{ ... },
{ ... },
{ ... }
]
}
}
⚠️ Please be aware:
- Application-Quota overrides are not taken over as long as the API is unpublished
Quota-Restrictions
The actual quota is stored in a quota restriction object. Each quota restriction object corresponds to a quota line in the API Manager UI. You can define any number of quota restrictions for an application or defaults, but you must ensure that they do not overlap. More information on how to make a restriction unique can be found here.
{
"name": "My App Name",
"organization": "API Development",
"appQuota": {
"restrictions": [
{
"api": "Petstore",
"method": "addPet",
"type": "throttle",
"config": {
"messages": "3000",
"period": "hour",
"per": "1"
}
},
{ ... },
{ ... }
]
}
}
API-Level Quotas
When you declare quotas for an application, it makes sense to define them per API depending on your use case. This means that an application A, for example, should be allowed more or less calls for all methods of the Petstore API. For quotas that are defined for APIs, the following is of course not necessary, since the quota is already API-specific.
For this you have to tell the APIM CLI on which API you want to set up the quota. Here you have two possibilities in your application-config file:
1. API path
This method uses the API-Path and if specified also the V-Host & Query-Version to identify the matching API. This method takes precedence over the API name if both pieces of information are provided.
{
"name": "Application with quota",
"description": "Application that configured quota per API-Path",
"appQuota": {
"restrictions": [
{
"apiPath": "/api/v1/petstore",
"vhost": "test-api.customer.com", (Optional)
"apiRoutingKey": "v2", (Optional)
"method": "*",
"type": "throttle",
"config": {
"messages": "9999",
"period": "week",
"per": "1"
}
}
]
}
}
2. API Name
This method uses the API name to identify the API. Since the API name is meta information that can change at any time, the recommendation is to use the API path instead. If an API path is specified, the API name is ignored.
{
"name": "App with API-Quota",
"organization": "API Development",
"appQuota": {
"restrictions": [
{
"api": "Petstore",
"method": "*",
"type": "throttle",
"config": {
"messages": "2000",
"period": "month",
"per": "1"
}
},
{
"api": "Banking API",
"method": "*",
"type": "throttle",
"config": {
"messages": "3000",
"period": "hour",
"per": "1"
}
}
]
}
}
If no unique API can be identified based on the API name or API path, the APIM CLI will abort the process and the application will not be replicated/changed.
Method-Level Quotas
It is also possible to configure API method level quotas. You can set these for APIs as well as applications with API specific quotas. In this case, instead of an asterisk "*", you must configure the operation ID for the method as specified in the OpenAPI/Swagger definition. The following example defines such a method-level quota for an application:
{
"name": "App with API-Quota",
"organization": "API Development",
"appQuota": {
"restrictions": [
{
"api": "Petstore",
"method": "addPet",
"type": "throttle",
"config": {
"messages": "2000",
"period": "month",
"per": "1"
}
},
{
"api": "Banking API",
"method": "*",
"type": "throttle",
"config": {
"messages": "3000",
"period": "hour",
"per": "1"
}
}
]
}
}
Of course, you can also mix API- and Method-level-Specific quotas, for example, to allow more or fewer requests on only one or two methods.
Desired- vs. Actual-Quota state
You can store any number of quota restrictions for system default, application default or application. Quotas are also configured according to the desired vs. actual state principle. This means that the APIM CLI determines whether a quota restriction already exists or not. It uses the following keys of a quota restriction for this:
| Field | Comment | Example |
|---|---|---|
| method | The methodId this restriction should be applied | addPet |
| range | The time frame unit | hour |
| per | The number of time frames | 2 |
| type | The Quota-Restriction type. Either throttle or throttlemb | throttlemb |
Based on these keys the APIM-CLI is identifying existing quota restrictions which, which are updated or new restrictions added. You can use the parameter: quotaMode to control the behavior.
Let's take the following example. When someone manually configures the following quota in API-Manager for an API:
And the following is configured for the same API in the API-Config-File:
"applicationQuota":{
"restrictions":[
{
"method":"*",
"type":"throttlemb",
"config":{
"period":"hour",
"mb":50,
"per":1
}
}
]
}
The APIM-CLI will overwrite the manually configured Quota to 50MB instead 1.000MB as all Quota-Keys are the same. It is basically the same Quota-Restriction and therefore updated to the desired value.
But with the following example and the same configured Quotas as from above:
"applicationQuota":{
"restrictions":[
{
"method":"*",
"type":"throttlemb",
"config":{
"period":"day",
"mb":10000,
"per":1
}
}
]
}
An additional quota entry in combination with the existing one will be added. This would be the result:
Quota-Mode
You can use the quotaMode parameter to control how quotas are processed:
quotaMode=ignore
The same as setting ignoreQuota=true. The quota handling is completely turned off. This also means that existing quotas, which may have been created manually, are not transferred if, for example, a new API is created. Only recommended if no quotas are used at all.quotaMode=replace
With this mode, potentially existing Quotas for an API or Application, that might have been manually configured, will be replaced by the configured quotas.quotaMode=add
This is the default option, if nothing else is provided. With that the APIM-CLI is adding configured quotas to potentially already existing quotas.
It is also possible to configure multiple quotas for an API at the same time. For instance this example:
"applicationQuota":{
"restrictions":[
{
"method":"*",
"type":"throttlemb",
"config":{
"period":"day",
"mb":10000,
"per":1
}
},
{
"method":"*",
"type":"throttlemb",
"config":{
"period":"hour",
"mb":1000,
"per":1
}
},
{
"method":"*",
"type":"throttle",
"config":{
"period":"minute",
"messages":2000,
"per":30
}
}
]
}
This configuration results into the following API-Manager setting for this API:
This is enforced by the API-Manager at runtime in combination.
When using quotaMode=add (which is the default) and changing Quota-Keys (e.g. Type, Time-range, Per) in the API-Configuration file the CLI cannot identify anymore if existing quotas has been added manually or by the CLI before. Therefore new Quota-Entries will be added.
The recommendation is to avoid too many Key changes in the API-Config-File, but if it's required two options:
- replicate the API (maybe only once) with quotaMode=replace to bring it to the configured desired state
- clean-up unused quotas in API-Manager manually