You can access and constrain the usage of specific APIs using either account plans or API plans.
Publishers constrain the cumulative API usage of all the organizations under it using
account plans. Portal Admins manage the visibility of APIs at the organization level.
For more information about API visibility and permissions, see Create and Set Permissions for APIs.
API plansare more granular and control how Developers and applications within an organization can consume individual APIs. The API plan comprises rate limit and/or quota information, along with the public or private APIs to which these controls apply. You can also choose to which organizations an API plan applies, allowing you to set different access tiers for different organizations for the same APIs.
Used concurrently, you can manage manage visibility, consumption, and tiered quota on your APIs using account plans
In this topic:
How Plans Work
Account plans and API plans govern the following parameters:
- Visibility and consumption:Which private APIs are visible to which organizations, through configuring account plans (indirect assignment) or using API Details (direct assignment).
- Quota and rate limit:The limit that an organization can consume both private and public APIs (through account plans), and the limit that each application can consume public and private APIs (through API plans).
The following diagram illustrates the relationship between account plans, API plans, organizations (and their applications), and APIs.
Account Plans vs API Plans
The following table highlights the similarities and differences between account plans and API plans:
Can be applied to different organizations.
Must be linked to organizations to make the plan selectable by Developers and applications within those organizations.
Restrict an organization to follow only one account plan.
Enable an organization to use different API plans for different APIs and applications.
Account plans do not impact visibility.
Can be linked to both private and public APIs to constrain their usage, but do not impact their visibility.
Constrain the cumulative usage limit for the organization under the account plan.
Constrain the consumption limit of individual APIs by Developers and applications.
Drive the overall access and quota of your organizations.
Allow you to manage access tiers for optimum consumption by organizations within your account plan.
Roles and Permissions
Portal Admins can add and edit.
Portal Admins can add and edit. Org Admin and Developer can select API plans for individual applications, or propose selections to be approved by Admins or API Owners.
For more information about account plan and API plan permissions, see Getting Started with Plans.
How Quotas and Rate Limits Work
Account plans and API plans can use different quotas and rate limits.
Quota per day or month
Restricts the number of times that an application can query an API in a day or month.
- In account plans, a quota limit of 10000 per day ensures that all activities of an organization under that account plan do not exceed 10000 hits per day.
- In API plans, a quota limit of 10000 per day ensures that application hits for the API assigned to that API plan do not exceed 10000 hits per day.
Rate limit per second
Restricts the number of times that an application can query an API in a second.
- In account plans, a rate limit of 100 per second ensures that all activities of an organization under that account plan do not query more than 100 times per second.
- In API plans, a rate limit of 100 per second ensures that application queries for the API assigned to that API plan do not exceed 100 times per second.
Account plan limits are superior to API plan limits and are triggered first. The following diagram is an example:
- Three private APIs are added to the account plan, which has one organization under it. These APIs, as well as the public API, are visible to the organizations under the account plan. The total quota of 10000 hits/day and rate limit of 100 per second apply to all activities within this organization.
- API Lettuce is assigned the Silver API plan. API Chicken is assigned the Bronze API plan. APIs Carrot and Spoon are assigned to both Silver and Bronze plans.Assign APIs to API plans to limit consumption for that API. By default, API consumption is unlimited and can use up your account plan bandwidth or quota.
- Both Silver and Bronze API plans are linked to Organization Soup.Link API plans to organizations to allow the organization's application to select the API plan for public and private APIs.
- At the application level, Application Vegetable Soup is configured to consume API Lettuce, API Carrot, and API Spoon.
- Quota for API Lettuce is 1000 hits/day and 100/second (Silver API plan).
- You can choose the quota for API Carrot and API Spoon between Silver and Bronze API plans.
- At the application level, Application Chicken Soup is configured to consume API Chicken and API Spoon.
- Quota for API Chicken is 500 hits/day and 50/second (Bronze Plan).
- You can choose the quota for API Spoon between Silver and Bronze API plans.
Following this logic, administrators can give each API a different quota and rate limit for different applications.
Getting Started with Plans
The recommended workflow is as follows:
The following best practices are recommended if you have existing account plans:
- Check and adjust the current account plan limit. Use the highest common denominator when assigning quotas and rate limits for an account plan.
- If you have not already, enable request workflows. This enables the Admin or API Owner to accept or reject requests made by Org Admins and Developers to edit applications and select API plans. If you disable the request workflow, Org Admins and Developers can perform these tasks without approval.
- Revisit your existing APIs (both private and public) and ensure that they are configured and/or assigned to an API plan. Non-configured APIs do not have a consumption limit and can use up your account plan bandwidth or quota.
Limit API Use
Organizations can manage API usage using one of the following policy templates:
- Rate Limit PolicyRestricts the number of times that an application can query an API in a second. For example, a rate limit of 1 prevents all the applications that use that API from accessing it more than once per second.
- Quota By Month PolicyRestricts the number of times that an application can query an API in a month. For example, a quota limit of 1 ensures that all the applications that use that API can only access it once per month.
- Quota By Day PolicyRestricts the number of times that an application can query an API in a day. For example, a quota limit of 1 ensures that the applications that use that API can only access it once per day.
Follow these steps:
- Log in toAPI Portalas a Publisher, or as an Org Admin or Developer with API publishing capabilities.
- In thePolicy Templatessection of the API, select the policy template that you want to use from the drop-down list, and then clickSave.
- Test the API limits that you specified.
Restrict API Usage by Application
You can restrict API usage for a specific application using the Rate Limit, Quota by Month, and Quota by Day policies with account plan policies. For example, you can set the
API Rate Limitto 10 per second, and the
Account Plan Rate Limitto 1 per second. Applications using the API
andthe account plan can access the API
onlyonce per second.
Change Quota and Rate Limits
The following example shows the impact of changing a quota or rate limit, based on the day of the change.
A customer sets the Quota by Day to 100 for an API. When that API is consumed 100 times, the API is no longer accessible. The customer then requests that the quota be increased to 200
today. The API can be consumed an additional 100 times today because the adjusted daily limit has not been reached yet.
If the customer requests the quota to be changed to 200 on the
next day, the API can be consumed 200 times the next day.
The above scenario above applies for Quota by Day and Quota by Month.