Editing a draft Product

After initially creating a draft Product, you can continue to further configure the Product, or you can make configuration changes later.

About this task

You can complete this task either by using the API Designer UI application, or by using the browser based API Manager UI.

During the initial creation of a Product, the Product creation wizard guides you to enter the minimum configuration settings, and then provides an Edit Product button. You have the option to specify additional configuration immediately, or to return to Product to edit it later. This topic describes how to specify additional configuration in either case.

Procedure

To edit a draft Product, complete the following steps:

  1. Access the Product Setup page in one of the following ways:
    • After completing the initial creation of the Product, click Edit Product.
    • In the navigation pane, click Develop, then select the Products tab.
    • Click the title of the Product that you want to edit.
  2. On the Product Setup page, you can make the following configuration changes:
    1. In the Info section, change the Title, Version, or Summary.
    2. Use the Contact, Terms of Service, and License sections to enter the corresponding details as required.
    3. Change the gateway type. For more information, see API Connect gateway types and Specifying the gateway type for a Product.
    4. Click Save to save your changes.
  3. Optional: Specify Product metadata to be displayed with the Product in the Developer Portal:
    1. Click the Source tab to see the OpenAPI source for the Product.
    2. Add the custom attribute x-name: value into the info section. For example:
      info:
        version: 1.0.0
        title: Multi Plans
        name: multi-plans
        x-customarg: This is the custom value
      ...
      Where customarg is the name of the custom metadata, and This is the custom value is the information content.
    3. Click Save.
      When the Product is published in the Developer Portal, the custom metadata is displayed with the Product. For example:
      Screen capture of an example Product displayed in the Developer Portal with custom metadata.
  4. Click Visibility, then make the following changes as required:
    1. In the Visibility section, specify the users that you want the Product to be visible to. You can choose Public to make the Product visible to all users, Authenticated to make the Product available to users who have successfully authenticated, or Custom to specify the consumer organizations and consumer organization groups that you want the Product to be visible to.
      If you select Custom, complete the following steps:
      • Select the Catalog for which you want to control visibility.
      • Use the Search organizations and groups field to search for the consumer organizations and consumer organization groups, in the selected Catalog, that you want the Product to be visible to. For information about how to create and manage consumer organizations and consumer organization groups, see Administering Consumer organizations.
    2. In the Subscribability section, specify the users that can subscribe to the Plans in the Product. You can choose Authenticated to make the Plans in the Product subscribable by users who have successfully authenticated, or Custom to specify the consumer organizations and consumer organization groups that can subscribe to the Plans in the Product.
      If you select Custom, complete the following steps:
      • Select the Catalog for which you want to control subscribability.
      • Use the Search organizations and groups field to search for the consumer organizations and consumer organization groups, in the selected Catalog, that you want the Product to be subscribable to. If you selected custom visibility, only the consumer organizations and consumer organization groups selected there are available for adding to the custom subscribability list. For information about how to create and manage consumer organizations and consumer organization groups, see Administering Consumer organizations.
      Note:
      • If you select custom visibility or subscribability, only 10 search results are displayed in the selection list for the consumer organizations and consumer organization groups. If necessary, enter a more specific search string to refine the search.
      • Although the title of each organization or group is displayed, followed by the name in parentheses, in the table of selected organizations and groups only the name is displayed
    1. Click Save to save your changes.
    Note: You can change the visibility and subscribability settings when you publish the Product; see Publishing a draft Product. You can also change the settings in the Catalog to which the Product is published; see Changing the availability of a Product.
  5. To specify the APIs that you want to include in the Product, click APIs, then complete the following steps:.
    1. Click Edit.
      All draft APIs are listed.
    2. Select the APIs that you want to include. You can include only APIs whose gateway type matches the gateway type of the Product, or APIs for which the Enforced option is disabled, meaning that the API is not managed on an API Connect gateway. If you select an incompatible API whose gateway type does not match the gateway type of the Product, a warning message is displayed and you cannot save your changes until you clear the incompatible selection. For more information on gateway types, see API Connect gateway types, Specifying the gateway type for a Product, and Specifying the gateway type for an API definition.
    3. Click Save when done.
      The selected APIs are listed.
    Note: To make an API available to application developers, you must include it in a Plan.
  6. Optional: Add billing integration to the Product. Click Plans, and in the Billing integration section, select the billing integration resource that you want to apply to the Product.
    In the Plans section, you can then either edit the Default Plan to add pricing information, or create a new Plan with pricing information. For more information about billing integration, see Monetizing your Products.
  7. Optional: Add one or more Plans to the Product, or modify an existing Plan. Note that a default plan is automatically created for you, with a rate limit of 100 API calls per hour.
    Note: If you enable event endpoints in Cloud Pak for Integration, rate limits do not apply to AsyncAPIs associated with a plan.
    1. Click Plans.
    2. To add a new Plan, click Add. To modify an existing Plan, click the options icon options icon alongside the required Plan, then click Edit.
    3. Specify the Title of the Plan and, optionally, a description. A Name is entered automatically.
      Note: The value in the Name field is a single string that is used to identify the Plan in developer toolkit CLI commands. The Title is used for display.
    4. Specify whether your Plan requires subscription approval. If you want subscriptions by developers to require approval, select the Approval check box; otherwise, ensure the check box is cleared.
    5. In the Plan pricing section, you can add pricing information by completing the following steps:
      1. Change the toggle to On for Plan pricing. The Plan pricing definition section is displayed.
      2. If you want to include any free trial days in your Plan, select Include free trial days, and then enter the number of trial days that a subscriber can use the Plan without charge, after which their billing cycle begins.
      3. Select the Currency for the billing process use.
      4. Enter the Price per month to bill the subscriber for. If the selected currency supports fractional units, enter the price including any fractional units, such as cents.
      For more information about Product billing integration, see Defining a Product with billing integration.
    6. In the Plan Rate Limits section, you can modify a rate limit, and click Add to add further rate limits. You can set multiple rate limits, at second, minute, hour, day, and week time intervals. To remove a rate limit, click the corresponding delete icon The delete rate limit icon.
      Note: For information about rate limits and burst limits in API Connect, see Understanding rate limits for APIs and Plans.
    7. In the Plan Burst Limits section, you can modify a burst limit, and click Add to add further burst limits. You use burst limits to prevent usage spikes that might damage infrastructure. You can set multiple burst limits, at second and minute intervals. To remove a burst limit, click the corresponding delete icon The 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 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 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."

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

      Scenario A
      Table 1. Hard limit enabled
      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. Hard limit disabled
      Hard limit Burst limit Rate limit
      OFF 100 calls/minute 1000 calls/day
      • 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 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.
    8. To include in the Plan all the APIs that were included in the Product in step 5, select Same as product in the Plan APIs section.
    9. In the GraphQL Rate Limits section you can configure rate limits that will be applied to any GraphQL proxy APIs that are added to the Product.
      The following rate limits are available:
      graphql-field-cost
      Applies a limit to the total calculated field cost of GraphQL query calls made to the GraphQL proxy APIs in this Plan.
      graphql-design-request
      Applies a limit to the total number of calls of any of the following types made to the GraphQL proxy APIs in this Plan:
      graphql-input-type-cost
      Applies a limit to the total calculated input type cost of GraphQL query calls made to the GraphQL proxy APIs in this Plan.
      graphql-type-cost
      Applies a limit to the total calculated type cost of GraphQL query calls made to the GraphQL proxy APIs in this Plan.

      The calculated costs depend on weighting factors applied to the types and fields in the GraphQL schema. For details on the GraphQL proxy API, and configuring type and field weights, see Creating a GraphQL proxy API and Using the GraphQL schema editor.

    10. To define one or more assembly burst limits or assembly count limits, click Add in the Assembly Burst Limits or Assembly Count Limits section as appropriate. For a burst limit you specify the maximum number of calls allowed in a specified time period, for a count limit you specify a maximum call limit. The name that you supply is for use in a Rate Limit policy in an API assembly, enabling the policy to define the burst or count limit that is to be applied; for more information, see Rate Limit.
    11. To select the APIs that you want to include in the Plan, select Customize the plan API list in the Plan APIs section, then click Edit. The Edit plan APIs window opens. The APIs that are available for selection are those that were included in the Product in step 5. Use the check boxes to specify the required APIs, then click Save when done.
    12. To select specific API operations to include in the Plan, click the options icon options icon alongside the required API , then click Edit operation list. The Select operations you want to include window opens. Use the check boxes to specify the required operations, then click Save when done.
    13. To remove an API from the Plan, click the options icon options icon alongside the required API in the Plan APIs section, then click Remove.
    14. For any GraphQL APIs in the Plan, if you want to prevent subscribers to this Plan from using certain types or fields, complete the following steps:
      1. Click the options icon options icon alongside the required GraphQL API in the Plan APIs section, then click Edit show/hide settings.
      2. To prevent use of a GraphQL type, clear the check box selection alongside that type.
      3. To prevent use a of a field in a type, expand the type then clear the check box selection alongside that field.
      4. When done, click Next. A summary window opens. If the operation is permitted, any related elements that will also be hidden are listed; for example, if you hide a type, and that type is referenced as the data type of a field on another type, that field is also hidden. If the operation is not permitted, an explanation is displayed.
      5. If the operation is permitted, click Done to apply your changes. If the operation is not permitted, either click Cancel to close the window or click Back and amend your settings.

      You can use the Edit show/hide settings option to change existing settings; you can hide additional types or fields, and you can show types or fields that were previously hidden.

    15. To define rate limits for specific API operations, select Override plan rate limits for individual operation in the Plan APIs section; for further details, see Defining rate limits for an API operation
    16. Click Save to save your changes.
  8. Optional: Specify Plan metadata to be displayed with the Plan in the Developer Portal:
    1. Click the Source tab to see the OpenAPI source for the Plan.
    2. Add the custom attribute x-name: value into the appropriate plan section. For example:
      ...
      plans:
        default-plan:
          title: Default Plan
          description: Default Plan
          x-customarg: This is the custom value
          rate-limits:
            default:
              value: 100/1hour
              hard-limit: false
            minute:
              value: 20/1minute
              hard-limit: false
          apis:
            petstore-header-clientid1.0.0: {}
      ...
      Where customarg is the name of the custom metadata, and This is the custom value is the information content.
    3. Click Save.
      When the Plan is published in the Developer Portal, the custom metadata is displayed with the Plan. For example:
      Screen capture of an example Plan displayed in the Developer Portal with custom metadata.
    Note: After adding custom metadata to a Plan, if you need to edit the Plan details further, you must do this in the Source view, or the custom metadata will be deleted.
  9. Optional: Click Categories, then define any categories that you want to organize your Product into. Click Save to save any updates.
    By organizing your Products into categories, you can provide a hierarchical display for your Products in the Developer Portal. For more information, see Organizing your Products into categories.

What to do next

Stage your Product to a Catalog. For more information, see Staging a draft Product.