Describing Plans in your Product

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:
Note: For information about rate limits and burst limits in API Connect, see Understanding rate limits for APIs and Plans.
```
    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: {}