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.

To describe your Plans, include APIs in them, and set rate limits for Plans or specific operations, complete the following instructions:

1. Begin the Plans section with plans:
2. 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.
3. 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
4. Under your Plan, specify which APIs are to be included.
   To reference by file path, use the following syntax:

         apis:
            - $ref: 'file:API_File_Path'

   where API_File_Path is the file path of the YAML file for an API that you have already included in your Product. The API must have been added to the Product before it can be included in a Plan, as is described in Referencing the APIs for your Product.

   To reference by name and version, use the following syntax:

   apis:
      - $ref API_1_Name:API_1_Version
      - $ref API_2_Name:API_2_Version

   where

   • the API_Name variables are the case-sensitive names of your APIs.
   • the API_Version variables are the versions of your APIs.
5. 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:
            - $ref: 'file:File_Path'
               operations:
                  - path: 'Operation_1_Path'
                    verb: 'Operation_1_Verb'
                  - path: 'Operation_2_Path'
                    verb: 'Operation_2_Verb'

   where

   • the Operation_Path variables are the paths of operations that is to be included. The dash is required for each new operation.
   • the Operation_Verb variables are the appropriate REST verbs for the operations.
6. Optional: If you want to specify multiple rate limits for a single operation; use the following syntax:

         apis:
            - $ref: 'file:API_File_Path'
               - path: 'Operation_Path'
                 verb: 'Operation_Verb
                 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.

plans:
   Plan_Name:
      description: Plan_Description
      approval: Approval_Toggle
      rate-limits:
         Name:
            value: Limit
            hard-limit: Limit_Toggle
      apis:
         - $ref: 'API_Name:API_Version'
         - $ref: API_Name:API_Version

plans:
   Plan_Name:
      description: Plan_Description
      approval: Approval_Toggle
      rate-limits:
         Name:
            value: API_Limit
            hard-limit: API_Limit_Toggle
      burst-limits:
         Name:
            value: Burst_limit
      apis:
         - $ref: 'file:API_File_Path'
           operations:
               - path: Operation_1_Path
                 rate-limits:
                    Name:
                       value: Operation_Limit
                       hard-limit: Operation_Limit_Toggle
              - path: Operation_2_Path