Defining a Plan

Define Plans to specify the limitations and subscription details of how developers can use your API Products. A Plan includes rate limit settings that can be applied to the Plan as a whole, or specified for each operation in an API. It can also include billing information that applies to the Product. Through Products and Plans, you have greater control over what APIs your developers have access to, and the subscription terms.

To create a Plan, complete the following steps:

1. To open the API Designer UI, enter the following command at the command line:

   apic edit

   The API Designer UI opens in your default browser.

   Note: If you are connected to a network, you are asked to sign in with IBM Cloud. Enter your IBMid credentials and click LOG IN. If this is your first time using API Designer, the Draft APIs information page opens, click Got it!, and continue with the following steps.
2. Select the Products tab in API Designer.
   The Products tab opens.
3. If the Product that you want to work with is already there, select it, and continue with step 5.
   Your Product design is displayed.
4. Optional: See Creating a Product, if you have not yet created the Product.
5. Select Plans in the navigation.
   A Default Plan is automatically created for you if you do not want to create your own, and any APIs that you selected for this Product are automatically included in this Plan. This Plan has no rate limitations, and no billing information. You can clear the check box for any API to exclude it from the Plan, but at least one API must be included. A Product cannot be staged if it includes any Plans that do not include APIs. If you decide not to use the Default Plan, you must delete it.
6. Select the Delete icon beside the Default Plan to remove it from your Product.
7. Select the Add Plan icon in the Plans section to add a new Plan.
   A Plan called New Plan 1 is created and displayed.
8. Select the name of the Plan to display its details.
9. Replace the title, name, and version with your information for the new Plan.
   The title is the name of the Plan that the customer sees and subscribes to.

   Note: The Name field can contain only lowercase alphanumeric characters (a-z and 0-9), and hyphen characters (-). A hyphen cannot be used as the first or last character in the name.
10. Optional: If you want to bill for the Plan, configure it for billing.
    1. Select your billing plan.
    2. Enter the monthly cost of the Plan.
    3. Select the unit of currency for the billing.
    4. Set the number of free trial days that subscribers can use when they subscribe to the Plan.
11. Optional: Add a rate limit to your Plan.
    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.

    Note: If you want to configure notifications that are triggered when your Plan approaches its rate limit in the Developer Portal, you must assign one of the following names to the rate limit in the Plan:

    • rate-limit
    • rate-limit-1
    • rate-limit-2
    • per-minute

    • Clear the Unlimited check box and then specify the rate limit you want to apply.
    • Click the Add new rate limit icon , and then specify the rate limit that you want to apply. You can set multiple rate limits, at second, minute, hour, day, and week time intervals.

      To add burst limits to your Plan, so that you can prevent usage spikes that might damage infrastructure, click the Add new burst limit icon , and then specify the burst limit that you want to apply. You can set multiple burst limits, at second and minute intervals. To remove a rate or burst limit, click the Delete rate limit or Delete burst limit icon .

    Rate and burst limits work together to manage network traffic for the APIs covered under a Plan. A Plan can have multiple rate and burst limits, but it is recommended that each time interval be assigned only one set of limits. Adjust the rate and burst limits to allow for maximum traffic without overloading your network. The rate limit sets the maximum amount of sustainable, ongoing traffic for accessing the APIs on your network within a time interval (for example, one day). The burst limit sets the maximum short-term traffic volume for your network within a time interval (per second or minute).

    The burst limit allows for short bursts of increased traffic. When the burst limit is exceeded, all subsequent API calls are rejected until the start of the next burst limit interval. The burst limit counter is reset to zero at the start of the next interval, which allows API calls to be accepted again. These API calls count toward the rate limit counter, but the resetting of the burst limit counter does not affect the rate limit counter.

    The rate limit is the number of API calls allowed in a time interval, for example, 1000 calls per day. When the rate limit is exceeded, and Enforce Hard Limit is enabled, all subsequent API calls will be rejected. The rate limit counter is reset to zero at the start of the next rate limit interval, which allows API calls to be accepted again. If Enforce Hard Limit is disabled, all subsequent API calls are still accepted, and a message is logged stating that the rate limit has been exceeded. This is referred to as a "soft limit."

    Enforce hard limit affects only the rate limit, as illustrated by the following scenarios:

    Scenario A

    Table 1. Enforce Hard Limit Enabled

    Enforce Hard Limit	Burst Limit	Rate Limit
    ON	100 calls/minute	1000 calls/day

    • If a user calls an API 100 times in one minute, the burst limit is reached. The 101st call (and any subsequent calls) within the same minute will be rejected. Once the minute is up, the burst limit counter is reset. All API calls are tallied toward the rate limit of 1000 calls per day. The resetting of the burst limit counter does not affect the rate limit counter.
    • If a user calls the API 99 times per minute, they will not hit the burst limit. They will eventually hit the 1000 calls per day rate limit, and the 1001st call will be rejected until the end of the same one day rate limit interval. During the period of time when API calls are rejected due to the daily rate limit being exceeded, the burst limit will not be activated since the calls are already rejected.
    • Both burst limits and rate limits are applied per consumer.

    Scenario B

    Table 2. Enforce Hard Limit Disabled

    Enforce Hard Limit	Burst Limit	Rate Limit
    OFF	100 calls/minute	1000 calls/day

    • Same as in Scenario A, if a user calls the API 100 times in one minute, the 101st call within the same minute will be rejected, until that minute is up and the counter resets. These calls count toward the 1000 calls per day rate limit as well.
    • If a user calls the API 99 times per minute, they will not hit the burst limit. They will eventually hit the 1000 calls per day rate limit, and the 1001st call will be accepted (since there is no hard limit). A message will be logged for each subsequent call until the time interval (one day) is up and the counter resets. During the remainder of the day, the burst limit will still be enforced, and calls will be rejected once the number of calls exceeds the 100 calls per minute within any given minute.
    • Both burst limits and rate limits are applied per consumer.
      Note: When Enforce Hard Limit is unchecked, the rate limit is considered a "soft limit." With a soft limit, calls are not rejected after the rate limit is reached. Instead, a message is recorded in the log file. With a soft limit, the burst limit still rejects API calls after it is exceeded.
    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

    For information about setting specific rate limits for operations, see step 14.
12. Optional: Specify whether your Plan requires subscription approval. If you want subscriptions by developers to require approval through the API Manager user interface, select Require subscription approval; otherwise, ensure the check box is cleared.
13. Verify that the APIs you require are included in the Plan.
    1. Under APIs included, ensure that the check boxes of the APIs you require are selected. If there are APIs already selected, and you do not want them included in the Plan you are editing, clear their check boxes.
    Note: If you add the same API to more than one Plan, and the same Application (client ID) signs up for multiple Plans that contain the same API, the Gateway server cannot determine which Plan rate limit should be applied. If you anticipate that an API will be shared by an Application, a proxy API should be defined so that the correct Plan rate limit can be applied.
14. Optional: Add a rate limit to an operation.
    
    1. Hover the cursor over the API that contains the operation, and click the Show operations icon .
    2. Hover the cursor over the operation that you want to apply a rate limit to. Click the Edit rate limit icon .
    3. Ensure the Unlimited check box is cleared, and then specify the rate limit you want to apply.
       If the Enforce hard limit check box is selected the Plan will stop applications from calling the operation after reaching the rate limit.
    
    1. Hover the cursor over the API that contains the operation, and click the Show operations icon .
    2. Hover the cursor over the operation that you want to apply a rate limit to, and click Override rate limit.
    3. Specify the rate limit that you want to apply.
       If the Enforce hard limit check box is selected, the Plan will stop applications from calling the operation after reaching the rate limit.
    4. Optional: To set additional rate limits, click the Add new rate limit icon for the operation, and then specify the rate limit that you want to apply. You can set multiple rate limits, at second, minute, hour, day, and week time intervals.
15. Optional: Select which operations from an API to include in the Plan.
    
    1. Hover the cursor over the API that contains the operation, and click the Show operations icon .
    2. Select or clear the check boxes for the operations you want to include or exclude.
    
    1. Hover the cursor over the API that contains the operation, and click the Show operations icon .
    2. Select or clear the check boxes for the operations you want to include or exclude.
16. Click the Save icon to save your changes.
17. Define any additional Plans that you need for your Product.