Creating a plan

An API Plan is the contract proposal presented to consumers who are about to subscribe to APIs. Plans are offered as tiered offerings with varying availability guarantees, SLAs or cost structures associated with them. An API package can be associated with multiple plans at a time. This helps the API providers in providing tiered access to their APIs to allow different service levels and pricing plans. Though you can edit or delete a plan that has subscribers, it is recommended to avoid doing so.

1. Open the menu options and select Manage > Packages.
2. Click Create in the Manage packages and plans section.
3. Select Plan.
4. Click Create.
5. Provide the following information in the Basic information section:
   • Name. Name of the API plan.
   • Version. Version assigned for the API plan.
   • Team. Team to which the application must be assigned to. You can select more than one team. To remove a team, click the delete icon next to the team.
   • Description. A brief description for the plan.
   • Icon. An icon that is displayed for the plan. Click Browse and select the required image to be displayed as the icon for the plan. The icon size should not be more than 100 KB.

   You can save the API package at this point and add the plans at a later time. The above fields are basic fields, provided by webMethods API Gateway. You can add additional information in the Additional information section.

6. Click Additional information to create custom fields for your plan.
   You can use these fields to extend meta data for Packages to store additional (billing/consumer related) data. For example, you can have a field called plan type. This field can have values called prepaid and postpaid. You can categorize all the plans as either prepaid or postpaid plans.
7. Click Add field to create a new custom field.
8. (Optional) Click Add to add multiple custom fields.
9. Provide the following information
   • Name. Name of the custom field.
   • Field value. Value for the custom field.
   • Description. A brief description for the custom field.
10. Click Save.
11. Click Pricing in the left navigation pane.
12. Provide the following information in the Pricing section
    • Cost. Specifies the cost for the plan.
    • Terms. Specifies the terms of conditions for the pricing.
    • License. Specifies the license information.

    You can save the plan at this point and provide traffic optimization configurations at a later time.

13. Click Continue to Quality of Service.
14. Click + Add Rule.
15. Provide the following information in the Create rule section
    • Maximum request count. Specifies the maximum number of requests handled. Value provided should be an integer.
    • Interval. Specifies the value for the interval for which the maximum request count is handled. Value provided should be an integer.
    • Interval unit. Specifies the unit of measurement of the time interval. For example:
      • Minutes
      • Hours
      • Days
      • Calendar Week. The plan starts on the first day of the week and ends on the last d ay of the week. By default, the start day of the week is set to Monday.

        For example

        • If you subscribe to a package on a Wednesday and Interval is set to 1, the validity of the plan ends on Sunday, that is, 5 days.
        • If you subscribe to a package on a Wednesday and Interval is set to 2, the validity of the plan still ends on Sunday, but the validity of the plan is two calendar weeks, that is 12 days.

        You can change the start day of the week using the extended setting startDayOfTheWeek in the Administration > General > Extended settings section. This extended setting requires a restart of the webMethods API Gateway server for the changes to take effect. Please contact IBM® support team to the restart the API Gateway server.

      • Calendar Month. Starts on the first day of the month and ends on the last day of the month.

        For example,

        • If you subscribe to a package in the month of August and Interval is set to 1, the validity of the plan ends on the last day of August.
        • If you subscribe to a package in the month of August and Interval is set to 2, the validity of the plan still ends on Sunday, but the validity of the plan ends in two calendar months, that is on the last day of September.
      • Alert Frequency. Specifies how frequently to send alerts to webMethods API Gateway destination when the Rate limits condition is violated. Select one of the following options:.
        • Only Once. Triggers an alert only the first time one of the specified conditions is violated.
        • Every Time. Triggers an alert every time one of the specified conditions is violated.
      • Violation message. Specifies the text that displays when the rule is violated.
16. Click Ok.

    This creates the rule and displays it in the Configured rules table. Click + Add rule to add more rules. You can edit or delete the rules by clicking the edit and the delete icons respectively.

    At a later time, when this plan is applied to an API through a package, the rules that you configured for this plan are enforced on the applied API.
17. Click Quota and provide the following information in the Quota settings section.
    • Maximum request quota. Specifies the maximum number of requests handled. Value provided should be an integer.
    • Block on breach. When selected it specifies that the access to the API is blocked when there is a rule violation. By default, this option is not selected.
    • Interval. Specifies the value for the interval for which the maximum request quota is handled. Value provided should be an integer.
    • Interval unit. Specifies the unit of measurement of the time interval. For example:
      • Minutes
      • Hours
      • Days
      • Calendar Week. The plan starts on the first day of the week and ends on the last ay of the week. By default, the start day of the week is set to Monday.

        For example

        • If you subscribe to a package on a Wednesday and Interval is set to 1, the validity of the plan ends on Sunday, that is, 5 days.
        • If you subscribe to a package on a Wednesday and Interval is set to 2, the validity of the plan still ends on Sunday, but the validity of the plan is two calendar weeks, that is 12 days.

        You can change the start day of the week using the extended setting startDayOfTheWeek in the Administration> General > Extended settings section. This extended setting needs a restart of the webMethods API Gateway server for the changes to take effect. Please contact IBM support team to the restart the API Gateway server.

      • Calendar Month. Starts on the first day of the month and ends on the last day of the month.

        For example,

        • If you subscribe to a package in the month of August and Interval is set to 1, the validity of the plan ends on the last day of August.
        • If you subscribe to a package in the month of August and Interval is set to 2, the validity of the plan still ends on Sunday, but the validity of the plan ends in two calendar months, that is on the last day of September.
      • Alert Frequency. Specifies how frequently to send alerts to webMethods API Gateway destination when the Quota condition is violated. Select one of the options:
        • Only Once. Triggers an alert only the first time one of the specified conditions is violated.
        • Every Time. Triggers an alert every time one of the specified conditions is violated.
      • Violation message. Specifies the text that displays when the policy is violated.
      • Notification settings. Specifies whether notifications are to be sent on rule violations.Enable the toggle button to enable the notifications and provide the following information:
        • Notify after (in %). Provide a value which is a number. A notification is sent to the configured email IDs once the total request count reaches the % value as provided in the maximum quota value.
        • Violation message. Provide the content of the mail that is sent to the configured email Ids once the quota request count reaches the limit specified.
        • Email Ids. Provide email Id of the recipient to which notifications have to be sent of notification once the quota request count reaches the limit specified. Click +Add. You can add multiple recipients.
          Note: The SMTP settings under Administrator settings, Destinations has to be provided for email to be sent.
        • Send Digital Events
        • Custom destination. Select custom destinations to which the notification must be sent. You can select multiple custom destinations. The custom destinations displayed in this field are populated from the custom destinations, configured in the Administration > Destinations > Custom destinations page.
      Important: In case of a server crash or restart, the quota status is determined by the value set in the pgmen.quotaSurvival.addLostIntervals property and works as follows.

      • If the property is set to false, remaining time in quota is retained even after a restart or crash. For example, If quota is of 60 minutes and 7 minutes was used before the server crash or restart, then quota remaining time of 53 minutes is retained after server crash or restart, if the property is set to false.
      • If the property is set to true, and if the sum of time between server shutdown and restart and quota elapsed time does not exceed the interval of the subscription, the quota usage value is retained. In this case the remaining quota time is calculated as {current interval cycle - (elapsed time + (start time - shutdown time))}. For example, if the current subscription duration is 1 month and if the server starts on the 10th day of the cycle and restarts on the 12th day of the cycle, the remaining quota time is calculated as {30 - (10 + (12-10))} = 18 days.
      • If the property is set to true, and if the sum of time between server shutdown and restart and quota elapsed time exceeds the interval of the subscription, a new interval is created. Quota usage value is not retained in this case.
18. Click Save.
    The plan is created and listed in the list of plans.