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.
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.
   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.

   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. Configure a developer portal based on the catalog.
    1. Create the portal:
       1. In the catalog, click the Catalog Settings tab.
       2. On the Catalog Settings page, click Portal in the navigation list.
       3. On the Portal page, click Create.
       4. On the Create Portal page, select a portal service.
       5. Click Create to save your changes.
       If you want to edit the portal service or URL, or delete the portal site, return to the portal settings page, click the Options icon, and click Edit or Delete.
    2. Optional: You can create a custom vanity hostname for the portal by completing the following steps.

       When you create a developer portal, API Connect generates a URL that consumers can use to access the portal. If you want consumers to use a custom URL for the developer portal, you can configure a vanity hostname for the portal to be used in the URL. Configuring a vanity hostname requires that you configure a DNS with the CNAME.

       Step 1: Set up the vanity hostname:

       1. Set up your desired DNS as a CNAME pointing to the following address:

          custom.<region>.apiconnect.ibmappdomain.cloud

          where <region> is the region where your API Connect account is hosted. For example, for an eu-central customer:

          custom.eu-central-a.apiconnect.ibmappdomain.cloud

          Note: DNS changes can sometimes take up to 24 hours to populate.

       Step 2: Configure the vanity hostname for the Developer Portal:

       1. In the catalog, click the Catalog Settings tab.
       2. On the Catalog Settings page, click Portal in the navigation list.
       3. On the Portal page, click Edit.
       4. On the portal page, configure the vanity hostname :
          1. In the "Portal site" section, select Use vanity hostname.

             When you select this option, a reminder to configure the CNAME for your vanity hostname displays. If you did not already configure the CNAME, click in the message to copy the URL so that you can use it to configure the CNAME.

          2. Type the new custom hostname DNS; for example: api.CustomHost.uk.
          3. Click Check DNS to verify that the host can be accessed.

             The hostname must already be configured with a CNAME as shown in the reminder to configure DNS. If the DNS check fails, you cannot proceed with this procedure and must work with IBM Support to correct the problem.

          4. When the DNS check succeeds, click Save.

             The Catalog Settings page displays the settings for the updated portal.

15. 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.
    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.
16. 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.
17. 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.