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 Settings.
   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 Settings.
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 a published API of the same name and version already exists, 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 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.
      The Enable Gateway Services page opens.
   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.
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.
9. Click Save when done.
10. 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.
11. 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.
12. To manage the onboarding of application developers 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.
    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 application developers to complete their own sign-up process, move the Self service onboarding slider control to the On position.
       If this option is disabled, an application developer cannot sign-up without an invitation from a consumer organization owner.
    5. 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.
13. 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. Select Settings from the navigation panel, 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

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

    For any enforced API in API Connect, the gateway endpoints 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.

    where:

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

    Note:

    • IBM API Connect Version 5.0 provides a feature known as host to catalog mapping, whereby an API can be invoked without having to include the provider organization or Catalog name in the URL path; this feature is not supported in IBM API Connect Version 2018.
    • 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 supported in IBM API Connect Version 2018.

    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 field 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
       • API priority: The host field 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 field, 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 field, the API endpoint will be https://api.acme.com/basepath, as determined by the vanity API endpoint setting.
         • If no vanity API endpoints are defined, then the default gateway endpoints are used to determine the API endpoint.
    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.

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