Creating and configuring catalogs

How to create and configure catalogs in IBM® API Connect.

To create and configure your catalog, complete the following steps:

1. Log in to API Manager and click Manage.
2. Create the catalog.
   You can create the catalog in either of the following ways:

   Specify the owner, then configure the catalog:

   1. Click Add > Create catalog.
   2. In the Catalog Owner field, select the owner of the catalog; by default, you are the owner. You can specify any user who is a member of the provider organization.
   3. Continue from step 3 to configure the catalog.

   Send an invitation email, with an activation link, to the intended catalog owner:

   1. Click Add > Invite catalog owner.
   2. Enter the email address of the catalog owner, then click Invite.
   3. On receipt of the email, the catalog owner must activate the catalog and configure it:
      1. Open the activation link, complete the sign up form, and sign in to the API Manager UI.
      2. Click Manage Catalogs, click the catalog name that was provided on the sign up form, then click the Catalog settings tab.
      3. Continue from step 6 to configure the catalog.
3. Enter the catalog Title. A Name is entered automatically and cannot be changed.
   Note: The value in the Name field is a single string that is used to identify the catalog in developer toolkit CLI commands. The Title is used for display; you can change the title but the name does not change.

   To view the CLI commands to manage catalogs, see the toolkit CLI reference documentation.

4. Click Create.
   Your new catalog is displayed on the Manage page.
5. To continue to configure your catalog, select the catalog on the Manage page, then click the Catalog settings tab.
6. To configure the general settings for the catalog, click Overview, then proceed with the following steps:
   1. By default, the new catalog is a development catalog. To use the catalog in production, set the Production Mode slider control to the On position, then click Confirm.

      In a development catalog, all publish operations are forced, and any conflicts are resolved automatically. If you republish a previously published product version it is overwritten without warning, allowing you, for example, to repeatedly republish the same product version during testing. If spaces are enabled in a development catalog and you republish a previously published product version to a different space, it is removed from the previous space.

      However, if the catalog has been configured to require approvals, a development catalog behaves the same as any other catalog with regard to requiring approval for staging and publishing actions.

      Note: In a production catalog, the following conditions apply:

      • You cannot publish a product to the catalog if there is already a product in the catalog with the same name and version. Instead, you must create a new version of the product for publication; see Creating a new version of your product . If spaces are enabled in a production catalog, you cannot publish a product with the same name and version to more than one space in the catalog.
      • If this new product contains one or more modified APIs, you must create new versions of the APIs for inclusion in the product; see Creating a new version of an API definition. If the product contains a modified API and there is already a published API of the same name and version, the changes will not be published.
   2. To enable the partition of this catalog into spaces, set the Spaces slider control to the On position, then click Confirm.
      For more information, see Using syndication in IBM API Connect.
   3. If the catalog is the default staging catalog, move the Default slider control to the On position, then click Confirm. Then, calls to APIs that are published to the catalog can use a shorter URL that does not include the catalog name.
      Note: You can enable Default for only one catalog. If another catalog is already set as the default catalog, you will be unable to enable the setting on this catalog without first disabling the setting on the other catalog.
   4. To enable application lifecycle for applications that are created in the Developer Portal that is associated with this catalog, set Application Lifecycle to On, then click Confirm.
      When application lifecycle is enabled, any application that an application developer creates in the Developer Portal has Development status by default. When application testing is complete, the application developer can request to upgrade the application to production status. For more information, see Managing the application lifecycle.
7. To configure the gateway service settings for the catalog, click Gateway Services, then proceed with the following steps:
   Note: If spaces are enabled in the catalog then you configure the gateway settings for the spaces, not for the catalog as a whole.
   1. Click Edit.
   2. Select the gateway services that you want to use with this catalog.
      Gateway services are configured by the using the Cloud Manager UI. For details, see Registering a gateway service. If any catalog default gateway services have been configured, they will already be selected when you create a new catalog; see Configuring default gateway services for catalogs.

      The TYPE column indicates the gateway type for each gateway service listed, DataPower® Gateway (v5 compatible), DataPower API Gateway, or Event Gateway Service. For more information, see API Connect gateway types.

   3. Click Save to save your changes.
      The UI for creating or importing AsynchAPIs from Event Endpoint Management is disabled for catalogs that do not have the Event Gateway service available. If you want to work with AsynchAPIs in the catalog, you must add an Event Gateway service to the catalog.

   You publish APIs by adding them to a product and then publishing the product to a catalog. To be able to publish products to a catalog, the catalog must be assigned at least one gateway service so that the APIs in the product are available to be called at a gateway service endpoint. You can assign more than one gateway service to a catalog, and they can be of mixed types, DataPower API Gateway and DataPower Gateway (v5 compatible).

   A product is gateway type specific, either DataPower API Gateway or DataPower Gateway (v5 compatible). By default, when you publish a product to a catalog, it is published to all the assigned gateway services of the same gateway type as the product, but you can choose to publish the product only to selected gateway services, of that type, at publish time; see Publishing a draft product for more information. The APIs in the product will be available to be called at all the specified gateway service endpoints.

   If you select two or more Gateway services then, for analytics data to be available in the Developer Portal for this catalog, the Gateway services must all be associated with the same analytics service. If the set of associated analytics services for the selected gateway services includes two or more different analytics services then the Developer Portal does not display analytics data. An analytics service is associated with a gateway service in the Cloud Manager user interface; see Associating an analytics service with a gateway service.

   Note: You can also configure the gateway service settings for the catalog by using the developer toolkit CLI; for details, see the toolkit CLI reference documentation.
8. To specify the product lifecycle state changes for which you want to enforce approval, complete the following steps:
   1. Click Lifecycle Approvals in the catalog settings navigation pane, then click Edit.
   2. Select the required state changes, then click Save when done.
      For example, if you select Publish and leave the other check boxes cleared, approval is required when anyone attempts to publish a product, but no approval is required for any of the other lifecycle state changes.

      Note: Approval for product lifecycle state changes in a catalog is disabled by default. You must explicitly enable the product lifecycle state changes that you want to enforce.
   3. To allow the originator of a product lifecycle change to approve it themselves, move the Task self approval slider control to the On position.
      Note: In a development catalog, the originator of a product lifecycle change can always approve it themselves. In a production catalog, the originator of a product lifecycle change can approve it themselves only if the catalog setting Task self approval is enabled.
   4. Click Save when done.
9. To configure the permissions that each role in API Manager has, complete the following steps:
   1. Click Roles in the catalog settings navigation pane.
      To see the current permissions for a role, expand the role.
   2. Click the options icon alongside the role that you want to work with, then click Edit.
   3. Select or clear the permissions check boxes as required.

      To ensure a role can manage user-defined policies, select Manage for the Settings permission.

      To grant a role the permission to approve a specific lifecycle state change, select the state change in the Product-Approval section.

      Note: You cannot remove a permission that has been assigned to the role at the provider organization level. However, you can add permissions that haven't been assigned at the provider organization level.
   4. Click Save when done.
10. To manage the onboarding of API consumers into this catalog, complete the following steps:
    1. Click Onboarding in the catalog settings navigation pane.
    2. To select the registries that are used to authenticate users of the Developer Portal associated with this catalog, click Edit in the Catalog user registries section, select the required registries, then click Save.
       For details on how to configure a user registry, see Authenticating by using your enterprise user registry.

       Important: Do not share user registries between the API Manager and the Developer Portal, or between Developer Portal sites when self-service onboarding is enabled or account deletions in any of the sites are expected. You should create separate user registries for them, even if the separate registries point to the same backend authentication provider (for example, an LDAP server). This separation enables the Developer Portal to maintain unique email addresses across the catalog, without API Manager needing the same requirement. It also avoids problems with users deleting their accounts from the Developer Portal that then affects their API Manager access.
    3. To set a default registry, locate the required registry and click Set default.

       When an API consumer signs up to the Developer Portal, the specified registry is used by default, with the option to select another registry.

    4. To allow API consumers to complete their own sign-up process to the Developer Portal, set Self service onboarding to On.
       If this option is disabled, an API consumer cannot sign-up without an invitation from a consumer organization owner.
    5. To require approval for all new self service onboarding to the Developer Portal, set Self service onboarding approval to On.
       If this option is enabled, then any attempt by an API consumer to sign-up to the Developer Portal results in an approval request being sent. This request is displayed in the Task tab in the catalog for the associated Developer Portal, from where the request can be approved or declined.

       Note that Self service onboarding approval is honored whenever a consumer organization is created. So, even if an API consumer has already been approved to access a Developer Portal with a specific consumer organization, if they then try to create another consumer organization in the same Developer Portal, their request will still go through the approval process.

       Note: To enable self-service onboarding approval, you must also complete the following tasks:

       • Configure the user registry to require the user's email address.
       • Configure the OIDC apps to send the user's email address for approval.
    6. To edit the timeout period for the self service onboarding task, click Edit in the Self service onboarding task timeout section, specify the timeout period required, and click Save. The timeout period for this task covers both the email activation link and, if Self service onboarding approval is enabled, the approval process. The default timeout period for the self service onboarding task is 72 hours.
       Note that expired self service onboarding tasks are cleared only once per day in the Developer Portal. Therefore, any API consumers with expired onboarding tasks have to wait until these tasks are cleared before attempting to sign-up again.
    7. To configure the ability for API consumers to invite collaborators and assign them to roles, click Edit in the Consumer invitation and roles section, select the options required, and click Save.
    8. To configure the timeout for activation links that are sent in email invitations to application developers, click Edit in the Invitation Timeout section, specify the timeout length, then click Save. The default timeout period for the invitation link is 48 hours.
    9. To override the timeouts set by consumer organization invitations, set Override consumer organization's invitation timeout with catalog invitation timeout to On.

       The catalog's own timeout setting will be used instead.

    Note: The Onboarding catalog settings applies to both the Consumer Catalog and Developer Portal.
11. To specify the user registries that are used to secure access to APIs in this catalog, and to add the user registry to the Sandbox catalog, complete the following steps:
    1. Click the Catalog settings tab, and then select API User Registries.
    2. Click Edit and select the user registries you want to use.
       For details on how to configure a user registry, see Authenticating by using your enterprise user registry.
    3. Click Save when done.
    Note:

    • Only LDAP and Authentication URL registries can be used to secure access to APIs; therefore, only registries of these types are listed and available for selection.
    • If spaces are enabled in the catalog then you specify the user registries for the spaces, not for the catalog as a whole. If you specify a user registry in one space in a catalog, it is deployed to the gateway services across all spaces in that catalog.

      For more information about enabling and managing spaces, see Using syndication in API Connect

      .
12. To specify the OAuth Providers that can be used to secure access to APIs in this catalog, complete the following steps:
    Note:

    • If you want to specify an OAuth provider for a catalog, ensure that the Sandbox catalog is configured to use the same OAuth provider
    • Any resources that the OAuth provider references, such as API user registries or TLS client profiles, must also be enabled in the catalog
    • If spaces are enabled in the catalog then you specify the OAuth providers for the spaces, not for the catalog as a whole. If you specify an OAuth provider in one space in a catalog, it is deployed to the gateway services across all spaces in that catalog.

      For more information about enabling and managing spaces, see Using syndication in API Connect.

    1. Click OAuth Providers in the catalog settings navigation pane.
    2. Click Edit, then select the OAuth providers that you want to use.

       To configure an OAuth provider, see either Configuring a native OAuth provider using Cloud Manager or Configuring a native OAuth provider using API Manager.

    3. Click Save when done.
13. To configure the TLS client profiles that are used with this catalog, complete the following steps:
    Note: If spaces are enabled in the catalog then you configure the TLS client profiles for the spaces, not for the catalog as a whole. If you configure a TLS client profile in one space in a catalog, it is deployed to the gateway services across all spaces in that catalog.

    For more information about enabling and managing spaces, see Using syndication in API Connect.

    1. Click TLS Client Profiles in the catalog settings navigation pane.
    2. Click Edit, then select the TLS client profiles that you want to use with this catalog.
       For details on how to create a TLS client profile, see Creating a TLS client profile.
    3. Click Save when done.
14. You have two options for sharing your APIs with the application developers. Use the default Consumer Catalog for a lightweight consumer experience; no customization, basic functionality, and ideal for small API catalogs, and internal users. You do not need Portal service to configure the Consumer Catalog. For more details on choosing between Developer Portal and Consumer Catalog, see Consumer Catalog and Developer Portal considerations.
    To enable the Consumer Catalog, complete the following steps:
    1. Click Portal in the catalog settings navigation pane, then set Consumer Catalog to On. The Consumer Catalog URL is displayed.
       By default, the Consumer Catalog is set to On.
    2. Click the URL to access the Consumer Catalog.
    If you require a complete content management system for your catalog, create a Developer Portal; fully customizable, full functionality, and ideal for large API catalogs and business users. You need a Portal service to configure the Developer Portal. To configure the Developer Portal, complete the following steps:
    1. Click Portal in the catalog settings navigation pane, then click Create.
    2. Select the portal service that you want to use with this catalog.
       Portal services are configured by using the Cloud Manager UI. For details, see Registering a portal service.
    3. Optionally, override the default generated portal URL.
       The URL must have the following format:

       https://host_name.portal.com

       where host_name.portal.com must resolve to the IP address of the Developer Portal machine.

       For example:

       https://myhost.mydomain.com

       Important:

       • The URL must be unique across all catalogs.
       • Mixed-case names are supported for resource names; however, portal endpoint URLs can support only lower-case. If a provider organization is created with a mixed-case name, you must edit the default-generated portal URL to make the provider organization name lower-case in the URL.

       To use sub paths in your site URL, see Sub paths for Developer Portal sites.
    4. Click Create to save your changes.
       For more information on using the Developer Portal, see Developer Portal: Socialize your APIs.
    If you want to edit the portal service or URL, return to this portal settings page and click Edit. To delete the portal site, click the options icon , and click Delete.
    Note: The account profile for the owner of the catalog must have an email address specified to receive the creation notification, otherwise the Developer Portal creation operation will fail. To check whether your account profile has an email address, and specify a value, complete the following steps:

    1. Click the User icon , and then select My Account.
    2. Check the contents of the Email field, and specify a value if necessary, then click Save.
15. To define catalog properties, complete the following steps:
    1. Click Properties in the catalog settings navigation pane, then click Create.
    2. Enter the property Name and Value, then click Create.
    The properties that you define can be referenced in any of the API definitions in this catalog. It is also possible to define properties that are specific to an API definition; see Setting API properties. For information on how to reference a property in an API definition, see Variable references in API Connect.

    Note:

    • If you define a catalog property of the same name as an API property, the API property takes precedence over the catalog property.
    • If you change the value of a catalog property, any API that references that property must be republished for it use the new value.
16. Optional: To configure the visibility of products that are published to a catalog or a space, see Configuring Product visibility at a Catalog or Space level.