Creating a Product

Create a Product to collect a set of APIs and Plans into one offering that you make available to your developers. A Plan includes rate limit settings that can be applied to the Plan as a whole, or specified for each operation in an API. Through Products and Plans, you have greater control over what APIs your developers have access to, and the subscription terms.

To create a Product, 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. Click Add and then click New product.
   Click Add and then click New Product.
4. From the Add a new product window, complete the following steps:
   1. Specify a title, name, and version.
      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.
   2. Click Add.
      The Design tab for the new Product opens.
5. From the New product window, complete the following steps:
   1. In the Product template field, select Default if you want to use the template defined as the default, to create the Product definition. This can either be the default .hbs template file provided with the developer toolkit, or another template file that you have configured as the default by using configuration variables. You can also select a custom template that you created. For information about template files and configuration variables, see Creating and using API and Product definitions templates and Toolkit command summary.
   2. Specify a title, name, and version for the Product.
      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.
   3. Click Create product.
      The Design tab for the new Product opens.
6. Optional: Enter description, contact, license, and terms of service information for the Product in the Info section.
7. In the Visibility section, specify the users that you want the Product to be visible to.
   You can choose Public, Authenticated users, or Custom.
   1. If you select Custom, type the name of the organization or community that you want the Plans in the Product to be visible to in the Type to add field. For information about how to create and manage organizations or communities, see Administering Developer organizations.
   2. If you select Custom, use the Type to add field to search for the developer organizations or communities that you want the Plans in the Product to be visible to.
      Note: To search for developer organizations or communities, the Product must be in the staged, published, or deprecated state. If the Catalog in which it is staged, published, or deprecated is not a development Catalog, you cannot make other changes to the Product while it is in one of these states. For more information, see The Product lifecycle.
8. Specify the users that can subscribe to the Product.
   You can choose Authenticated users or Custom.
   1. If you select Custom, type the name of the organization or community that you want to be able to subscribe to the Plans in the Product in the Type to add field. For information about how to create and manage organizations or communities, see Administering Developer organizations
   2. If you select Custom, use the Type to add field to search for the organizations or communities that you want to be able to subscribe to the Plans in the Product.
      Note: To search for developer organizations or communities, the Product must be in the staged, published, or deprecated state. If the Catalog in which it is staged, published, or deprecated is not a development Catalog, you cannot make other changes to the Product while it is in one of these states. For more information, see The Product lifecycle.
9. In the APIs section, specify the APIs that you want to include in the Product.
   1. Click the Add API icon .
   2. Select the APIs that you want to include, then click Apply.
      The selected APIs are listed.
   Note: To make an API available to application developers, you must include it in a Plan.
10. Add one or more Plans to the Product.
    1. Click the Add Plan icon .
    2. Expand the new Plan that has been created. If you have already added APIs to your Product, these are automatically included.
    3. Rename your Plan in the Title and Name fields, and optionally add a description.
    Note: A Default Plan is automatically created for you if you do not want to create your own, and any APIs that you selected in the previous step are automatically included in this Plan. You can clear the check box for any API to exclude it from the Plan, but at least one API must be included because 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.
11. Optional: Define the billing terms of the Plan.
    1. Select the billing model for the Plan. The monthly subscription is billed on the same day of each month.
    2. Select the currency and cost for the Plan.
    3. Select the number of days that customers can try the Plan before they are start incurring charges.
12. Verify that the APIs you require are included in the Plan.
    1. Expand the Plan to which you want to add APIs.
    2. 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.
13. 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.
14. Optional: Add a rate limit to your Plan.
    • 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 16.
15. 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.
16. 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.
17. Click the Save icon to save your changes.