Describe the Plans that you want to include in your IBM® API Connect Product and which APIs
they will contain, as well as any rate limits that apply.
About this task
A Plan contains APIs and their operations. It can be used to implement rate limits and tailor
visibility.
Note: If you are using more than one
DataPower® server in a Gateway
service, then to properly calculate API calls for rate limits the servers must be able to
communicate with each other by using SLM peer groups, using either SLM unicast peering or SLM
multicast peering depending on your network configuration. For more information, see
SLM peering.
In addition, you can apply burst limits to your Plans, to prevent usage
spikes that might damage infrastructure. Multiple burst limits can be set per Plan, at second and
minute time intervals. You can also set multiple rate limits per Plan and per operation, at second,
minute, hour, day, and week time intervals.
Note: All keys and enumeration values that are specified in this topic are case-sensitive.
Two
example Plan descriptions from a YAML representation of a Product can be found at the
end of this topic. An example of a complete YAML representation of a Product can be
found in An example YAML representation of a Product.
Procedure
To describe your Plans, include APIs in them, and set rate limits for Plans or
specific operations, complete the following instructions:
-
Begin the Plans section with plans:
-
Under Plans, begin the description of your first Plan by providing a name, description, and
specifying whether approval is required for subscription requests; use the following syntax:
plans:
Plan_Name:
title: Plan_Title
description: Plan_Description
approval: Approval_Toggle
where:
- Plan_Name is the name of the Plan. It must be a single word and contain only
alphanumeric characters, and the - (dash) and _ (underscore) characters. The name is case-sensitive,
and should be 20 characters or fewer so that it can be displayed in the API Manager user interface.
- Plan_Title is the title of the Plan.Any string can be used, but the title
should be kept short so that it can be displayed in the API Manager user interface.
- Plan_Description is a description of your Plan.
- Approval_Toggle must be either true, in which case
approval is needed for subscription requests, or false, in which case
subscriptions are automatically approved.
- Optional:
Under your Plan, add multiple burst and rate limits that will be shared across all the
operations in the Plan; use the following syntax:
rate-limits:
Name:
value: Rate_Limit
hard-limit: Limit_Toggle
Name:
value: Rate_Limit
hard-limit: Limit_Toggle
burst-limits:
Name:
value: Burst_Limit
where:
- Name is the name of the limit.
- Rate_Limit is your rate limit. It can be for multiples of seconds, minutes,
hours, days, or weeks, written as second, minute,
hour, day, and week
respectively; do not use the plural forms of the words. Use the syntax:
1/2minute
.
If the time unit is singular, then it is not necessary to precede it with a number, for example,
1/minute
. If you do not want to apply a rate limit, set
Rate_Limit as unlimited.
- Limit_Toggle must be true or
false. If true, API calls by a developer will fail if the
rate limit is exceeded. This step is not necessary if you have set Rate_Limit to
unlimited.
- Burst_Limit is your burst limit. It can be for multiples of seconds or
minutes, written as second or minute; do not use the
plural forms of the words.
Note:
- Applying a rate limit at the Plan level creates a default rate limit that is
shared across all the operations within the Plan. If you need to set
specific rate limits for specific operations, you must set these within the
operations themselves and these settings will override the setting at the
Plan level.
- The test application that is used by the API
Manager test tool is
not subject to rate limits if you have enabled automatic subscriptions for
the Catalog in which you are testing. For more information, see Working with Catalogs
-
Under your Plan, specify which APIs are to be included.
Reference APIs by name and version, as follows:
apis:
API_1_nameAPI_1_version: {}
API_2_nameAPI_2_version: {}
where
- the API_n_name variables are the case-sensitive names of your APIs.
- the API_n_version variables are the versions of your APIs.
- Optional:
If you want to include only a subset of an API's operations, list the operations that are to be
included; use the following syntax:
apis:
API_nameAPI_version:
operations:
- operation: Operation_1_Verb
path: Operation_1_Path
- operation: Operation_2_Verb
path: Operation_2_Path
where
- the Operation_n_Path variables are the paths of operations that is to be
included. The dash is required for each new operation.
- the Operation_n_Verb variables are the appropriate REST verbs for the
operations.
- Optional:
If you want to specify multiple rate limits for a single operation; use the following
syntax:
apis:
API_nameAPI_version:
operations:
- operation: Operation_Verb
path: Operation_Path
rate-limits:
Name:
value: Operation_Limit
hard-limit: Operation_Limit_Toggle
Name:
value: Operation_Limit
hard-limit: Operation_Limit_Toggle
where:
- Operation_Limit is the rate limit that you want to apply to your operation.
It can be for multiples of seconds, minutes, hours, days, or weeks, written as
second, minute, hour,
day, and week respectively; do not use the plural
forms of the words. Use the syntax:
1/2minute
. If the time unit is singular, then
it is not necessary to precede it with a number, for example, 1/minute
. If you do
not want to apply a rate limit, set Operation_Limit as
unlimited.
- Operation_Limit_Toggle must be true or
false. If true, API calls by a developer will fail if the
rate limit is exceeded. This step is not necessary if you have set
Operation_Limit to unlimited.
Results
You have described the Plans that are to be included in your Product. Your Plans section should
be similar to the following scenarios.
If you have enforced a rate limit for your Plan and not specified individual operations, your
Plans section should have the following form:
plans:
Plan_Name:
title: Plan_Title
description: Plan_Description
approval: Approval_Toggle
rate-limits:
Name:
value: Limit
hard-limit: Limit_Toggle
apis:
API_1_nameAPI_1_version: {}
API_2_nameAPI_2_version: {}
If you have enforced rate limits at the Plan level and want to include two operations, with a
separate rate limit one for one of the operations, your Plans section should have the following
form:
plans:
Plan_Name:
title: Plan_Title
description: Plan_Description
approval: Approval_Toggle
rate-limits:
Name:
value: API_Limit
hard-limit: API_Limit_Toggle
burst-limits:
Name:
value: Burst_limit
apis:
API_nameAPI_version:
operations:
- operation: Operation_1_Verb
path: Operation_1_Path
rate-limits:
Name:
value: Operation_Limit
hard-limit: Operation_Limit_Toggle
- operation: Operation_2_Verb
path: Operation_2_Path
In both examples, variables are as in the previous steps and the indentation must be as
presented.
The following example shows a complete sample Plans
section:
plans:
default:
title: Default Plan
description: Default Plan
approval: false
rate-limits:
default:
value: 100/hour
hard-limit: false
my-plan:
title: my_plan
rate-limits:
Default rate-limit:
value: 50/1hour
hard-limit: false
burst-limits:
Default burst-limit:
value: 10/1second
apis:
api21.0.0:
operations:
- operation: get
path: /path2
api31.0.0:
operations:
- operation: get
path: /path3
rate-limits:
limit3:
value: 10/1second
hard-limit: true
limit4:
value: 100/1hour
hard-limit: true
api11.0.0: {}