Creating and configuring Catalogs

These instructions describe how to create and configure Catalogs in IBM® API Connect.

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

1. In the navigation pane of the API Manager UI, click Manage.
2. Create the Catalog. You can create the Catalog in either of the following ways:
   • Specify the owner, then configure the Catalog yourself.
   • Send an invitation email, with an activation link, to the intended Catalog owner. The Catalog owner configures the Catalog after activating it.

   To specify the owner and configure the Catalog yourself, complete the following steps:

   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.

   To invite the Catalog owner, complete the following steps:

   1. Click Add > Invite catalog owner.
   2. Enter the email address of the Catalog owner, then click Invite.

   On receipt of the invitation email, the Catalog owner should complete the following steps.

   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 subsequently but the name does not change.

   To view the CLI commands to manage Catalogs, see apic catalogs.

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.

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

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

      • You will be prevented from publishing a Product to the Catalog if there is already a Product in the Catalog with the same name and version, 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 these 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.
7. To transfer ownership of the Catalog to a different user, click Overview, then proceed with the following steps:
   1. Click Edit.
   2. From the Select owner user drop-down menu, select the user who will become the new owner.
   3. If Spaces are enabled in the Catalog then to also have the ownership of all Spaces in the Catalog transferred to the new Catalog owner, select Also transfer ownership of owned Spaces.
   4. Click Save when done.
   Note:

   • To have permission to change the Catalog owner, you must be either the Catalog owner, or the owner of the provider organization that contains the Catalog.
   • When the ownership changes, the new owner is assigned administration privileges for the Catalog, and the previous owner has their administration privileges removed. If required, you can restore the privileges to the previous owner as described in Managing Catalog membership.
   • The ownership can be transferred only to a user who is already a member of the Catalog. To transfer to a new user or another existing user, that user must previously have been added or invited to the Catalog, as described in Managing Catalog membership.
8. 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 each Space separately, not for the Catalog as a whole. For more information about enabling and managing Spaces, see Using syndication in API Connect.
   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) or DataPower API Gateway. For more information, see API Connect gateway types.

   3. Click Save to save your changes.

   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 apic configured-gateway-services.
9. 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.
10. Click Save when done.
11. 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.
12. To configure the default role permissions for consumer organizations that are created in this Catalog, complete the following steps:
    1. Click Role Defaults in the Catalog settings navigation pane.
       To see the current default 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.
    4. Click Save when done.
    5. To create a new role and assign default permissions to it, click Add, name the role and assign permissions, then click Save.
13. 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, click the options icon alongside the required registry, then select Set default.

       When an application developer 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, move the Self service onboarding slider control to the On position.
       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, move the Self service onboarding approval slider control to the On position.
       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 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.
    7. 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.
    8. To override the timeouts set by consumer organization invitations, enable the Override consumer organization's invitation timeout with catalog invitation timeout setting by moving the slider to the On position.

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

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

      .
15. 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.
16. Optional: Configure vanity API endpoints for your Catalog.
    For any API, there are two possible endpoints to consider:

    • The gateway endpoint at which the API is invoked.
    • The endpoint that is visible to the consumer in the Developer Portal.

    If you do not configure vanity endpoints, these two endpoints are the same, and point to the gateway endpoint at which an API is invoked.

    To have an endpoint visible to the consumer that is different to the gateway endpoint, you configure a vanity endpoint. A vanity endpoint represents the endpoint by which an API is known externally; that is, the endpoint that is published to the Developer Portal and is used by an application developer to invoke the API. The way in which the gateway endpoints for an API are determined depends on the OpenAPI version of the API, as follows:

    (OpenAPI 2.0): For any enforced API in API Connect, the gateway endpoint formats for the API are as follows:

    • If the OpenAPI definition has no host field, the API endpoint has the following format:

      https://gateway_service_host/provider_organization/catalog/basepath

    • If the OpenAPI definition has a host field (for example, petstore.com), the host is appended to the path after the provider_organization/catalog segments, and the API endpoint has the following format:

      https://gateway_service_host/provider_organization/catalog/host_field_value/basepath

      Note: This is a change in behavior from IBM API Connect Version 5.0, where the host field is not included in the API endpoint.

    In these endpoint URLs, the variables are as follows:

    • gateway_service_host is the host name of the gateway service on which the API is running.
    • provider_organization is the value of the name field of the provider organization that contains the Catalog in which the API is published.
    • catalog is the value of the name field of the Catalog in which the API is published.
    • basepath is the value of the basepath field in the OpenAPI definition for the API.
    • host_field_value is the value of the host field in the OpenAPI definition for the API.

    (OpenAPI 3.0): If the API is enforced by the DataPower API Gateway, the value specified for the first url entry in the servers array in the OpenAPI definition of the API is used to determine the basepath element of the API endpoint, as follows:

    1. If a relative URL is specified for the server URL, that value is used as-is for the basepath, and the API endpoint has the following format:

       https://gateway_service_host/provider_organization/catalog/basepath

    2. If a full URL is specified for the server URL, the scheme (http:// or https://) is ignored by the DataPower API Gateway, and the remaining host name and basepath are used to form the API endpoint as follows:

       https://gateway_service_host/provider_organization/catalog/host_name/basepath

    In these endpoint URLs, the variables are as follows:

    • gateway_service_host is the host name of the gateway service on which the API is running.
    • provider_organization is the value of the name field of the provider organization that contains the Catalog in which the API is published.
    • catalog is the value of the name field of the Catalog in which the API is published.
    • host_name is the value of the host name in the server URL.
    • basepath is the value of the basepath derived from the server URL.

    For details on configuring the server URL in an OpenAPI 3.0 API definition, see Defining servers for an API, Defining servers for a Path, and Defining servers for an operation.

    Note:

    • You can change your Catalog settings to use the IBM API Connect Version 5.0 endpoint behavior, including support for a feature known as host to catalog mapping, whereby an API can be invoked without having to include the provider organization or Catalog in the URL path; see Retaining Version 5 vanity endpoint behavior in a Catalog.
    • IBM API Connect Version 5.0 provides a Default setting; calls to APIs that are published to the default Catalog do not need to include the Catalog name. This feature is not currently supported in IBM API Connect Version 10.

    To configure vanity API endpoints, so that you can publish endpoints that are different to these gateway endpoints, complete the following steps:

    1. Click API Endpoints in the Catalog settings navigation pane. The Vanity API Endpoint page opens.
    2. Click Edit.
    3. To display the current API base endpoint settings, select Display vanity endpoint.
    4. Select the required Preference setting. Choose one the following settings:
       • Catalog priority: Any host defined in the OpenAPI definition of the API is ignored and all API endpoints always point to the endpoints that you define here. For example, suppose you define a vanity API endpoint, with Catalog priority preference, to be https://prod.acme.com/. Then the API endpoint will be https://prod.acme.com/basepath.
         The way in which the basepath is determined depends on the OpenAPI version of the API, as follows:

         • (OpenAPI 2.0): The basepath is taken from the basepath field in the OpenAPI definition.
         • (OpenAPI 3.0): The basepath is taken from the first url entry in the servers array in the OpenAPI definition, ignoring any scheme (http:// or https://) and host name.
       • API priority: The host defined in the OpenAPI definition for the API takes precedence. For example, suppose you define a vanity API endpoint, with API priority preference, to be https://api.acme.com/. Then the following rules determine the endpoint that is used when an API is called:
         • If the OpenAPI definition has a host defined, test.acme.com for example, then that value is used to determine the API endpoint. For example: https://test.acme.com/basepath.
         • If the OpenAPI definition has no host defined, the API endpoint will be https://api.acme.com/basepath, as determined by the vanity API endpoint setting.
         The way in which any defined host is determined depends on the OpenAPI version of the API, as follows:

         • (OpenAPI 2.0): The host is taken from the host field in the OpenAPI definition.
         • (OpenAPI 3.0): The host is taken from the host name in the first url entry in the servers array in the OpenAPI definition.
    5. Supply one or more endpoints, as follows:
       • If you selected Catalog priority, click Add to enter one or more endpoints URLs, and an optional summary for each. Any of the endpoint URLs can be used to invoke an API.
       • If you selected API priority, enter the endpoint URL, and an optional summary.
    Note: After configuring your Catalog to support your vanity URL, you must configure your external network to map the vanity endpoints to the corresponding gateway endpoints. This typically includes the following:

    • A DNS mapping to ensure that the vanity host resolves to the gateway.
    • Additional URL routing for the API as required.

    For example, if your gateway has a default domain name of apigw.dc.zone.mycompany.com and an IP address of 29.12.141.150, then the generic DNS configuration might look like:

    api.acme.com. CNAME apigw.dc.zone.mycompany.com.

    or

    api.acme.com. A 29.12.141.150

    Consult your network administrator and the DNS provider's documentation to do this configuration.

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

       Note:

       • The URL must be unique across all Catalogs.

       To implement sub paths into your site URL, see Sub paths for Developer Portal sites.
    4. Select the portal service that you want to use with this Catalog.

       For more information on using the Developer Portal, see Developer Portal: Socialize your APIs.

    5. Click Create to save your changes.
    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.
19. 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.