Creating and configuring Catalogs (V5.0.6 and earlier)

These instructions describe how to create and configure Catalogs with IBM API Connect V5.0.6 and earlier.

To create your Catalog:

1. If you have not previously pinned the UI navigation pane then click the Navigate to icon .
   The API Manager UI navigation pane opens. To pin the UI navigation pane, click the Pin menu icon .
2. Add a Catalog.
   1. Click Dashboard.
   2. Click Add > Catalog.
      The Add Catalog window is displayed.
   3. Enter the name of your new Catalog in the Display Name field.
      The name that you provide is displayed on your dashboard.
   4. Enter the text that you want to form the Catalog segment of the URL, in the Name field.
      Note:

      • The Name field can contain only lowercase alphanumeric characters (a-z and 0-9), or hyphen characters (-). A hyphen cannot be used as the first or last character in the name. For more information, see Sub paths for Developer Portal sites.
      • The following names are reserved and cannot be used:
        • apis
        • plans
        • products
   5. Click Add. Your Catalog is created, and is displayed on your dashboard.
3. To configure the Catalog, click the name of the Catalog, then click Settings > Configuration, and proceed with the following steps:
   1. Click Configure Gateway and choose one of the following options depending on the gateway that is to be used when APIs are published to this Catalog, then click Done when finished.
      1. If you are using the DataPower® gateway, select the required gateway service under Datapower Services. Gateway services are configured in the Cloud Manager user interface; for more information, see Configuring the initial Gateway service and Adding more Gateway services.
      2. If you are using the Micro Gateway with the IBM API Connect Professional or Enterprise offering then, under Collectives, select the collective to which the Micro Gateway has been published, and click Next; for more information on configuring the Micro Gateway, see Adding a Micro Gateway to a Catalog.
         Important: IBM API Connect Micro Gateway is deprecated in IBM API Connect Version 5.0.8 in favor of DataPower Gateway. From 1 April 2020, Micro Gateway, and associated toolkit CLI commands, will no longer be supported. Existing users can migrate their API definitions to IBM DataPower Gateways. For information on supported API policies, see Built-in policies.
      3. If you are using the standalone Micro Gateway with the IBM API Connect Essentials offering, select API Connect Standalone Micro Gateway and click Next; for more information on configuring the standalone Micro Gateway, see Adding a Micro Gateway to a Catalog.
         Important: IBM API Connect Micro Gateway is deprecated in IBM API Connect Version 5.0.8 in favor of DataPower Gateway. From 1 April 2020, Micro Gateway, and associated toolkit CLI commands, will no longer be supported. Existing users can migrate their API definitions to IBM DataPower Gateways. For information on supported API policies, see Built-in policies.
   2. If the new Catalog is a development Catalog, select Sandbox.
      Development and Production catalogs behave differently:

      • Development catalog

        In a development Catalog, staging and publishing actions are forced, meaning that if you republish a previously published Product it is overwritten without warning. If conflicts are found, they are automatically resolved by the system. Unpublish actions happen automatically.

        Note: Approval boxes are not displayed for development Catalogs. You cannot enable the approval process for lifecycles.
      • Production catalog

        You will be prevented from publishing a Product to a Production 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. 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 you create a new Product that contains one or more modified APIs, you must create new versions of those APIs for inclusion in the Product. If the Product contains a modified API and there is already a published API with the same name and version, your changes will not be published.

   3. If the Catalog is the default staging Catalog, select Default. Then, calls to APIs that are published to that Catalog can use a shorter URL that does not include the Catalog name.
      Note: You can only select Default for one Catalog.
   4. Optional: Populate the following fields:

      Custom Gateway URL

      In the Custom Gateway URL text field, enter a URL. You use the Custom Gateway URL if you want to achieve custom branding of URLs for APIs that are deployed to IBM API Connect, rather than using the default URL that API Manager generates.

      By default, the IBM API Connect gateway URL has the following format:

      https://gateway_cluster_hostname/organization_name/catalog_name

      However, you can override the default by specifying a URL that is more appropriate for your enterprise; for example, https://api.mycompany.com. Any API endpoints that are displayed in the Developer Portal will then reflect the specified URL.

      Note:

      • You must configure your DNS entry to send requests for your custom domain https://api.mycompany.com to your gateway cluster load balancer endpoint so that API calls can be received by the gateway.
      • You must also configure transformation of the path of the HTTP request so that it reaches the gateway as the internal format /organization_name/catalog_name/api_root, and not just api_root. This step is not required in V5.0.4 or later.
      • For the endpoints of an API to reflect your custom gateway URL, you must configure the API to be enforced by the IBM API Connect gateway; for details, see specifying an alternative host for an API.
      • Ensure that the same custom gateway URL is not applied to multiple Catalogs as the behavior in that scenario is undefined.

      Tip: When you call the API, you can also set the HTTP host header on the API request to the value that you specified in the Custom Gateway URL field.

      Custom API URL

      In the Custom API URL text field, enter the URL. You use the Custom API URL to specify the URL for APIs that are deployed to a third party gateway.

      The Custom API URL represents the endpoint by which the API is known externally; that is, the endpoint that is published to the developer portal and used by an application developer to invoke or advertise the API.

      If you are using a third party gateway or external load balancer in this Catalog, supply the URL in this field. Any API endpoints that are displayed in the developer portal will then reflect the specified URL. These endpoints exist on the third party gateway or load balancer and project a virtual address, exposed to API consumers, that is mapped to the API proxy or API assembly endpoints on the gateway. The endpoints that are derived from the custom API URL are typically published in production developer portals to advertise the address of the API.

      Note: If you specify a custom API URL for a Catalog, it takes precedence over any host name that you specify when configuring the API; for more information, see specifying an alternative host for an API.

      Hostname for Developer Portal API Calls

      In the Portal API Endpoint window area, enter a host name for Developer Portal API calls. The host name that you enter can be the host name of your Management service.

      To access the Developer Portal API within the context of a Developer Portal, you must configure the base host name for the Developer Portal API calls.

      This action allows API Manager to map your host name to the provider organization and Catalog of the Developer Portal API calls instead of requiring you to look it up and include them in your calls.

4. To configure the Catalog, click the name of the Catalog, click Settings, then proceed with the following steps:
   1. Click Gateway > Configure Gateway and choose one of the following options depending on the gateway that is to be used when APIs published to this Catalog, and click Done when finished.
      1. If you are using the DataPower gateway, select the required gateway service under Datapower Services. Gateway services are configured in the Cloud Manager user interface; for more information, see Configuring the initial Gateway service and Adding more Gateway services.
      2. If you are using the Micro Gateway with the IBM API Connect Professional or Enterprise offering then, under Collectives, select the collective to which the Micro Gateway has been published, and click Next; for more information on configuring the Micro Gateway, see Adding a Micro Gateway to a Catalog.
         Important: IBM API Connect Micro Gateway is deprecated in IBM API Connect Version 5.0.8 in favor of DataPower Gateway. From 1 April 2020, Micro Gateway, and associated toolkit CLI commands, will no longer be supported. Existing users can migrate their API definitions to IBM DataPower Gateways. For information on supported API policies, see Built-in policies.
      3. If you are using the standalone Micro Gateway with the IBM API Connect Essentials offering, select API Connect Standalone Micro Gateway and click Next; for more information on configuring the standalone Micro Gateway, see Adding a Micro Gateway to a Catalog.
         Important: IBM API Connect Micro Gateway is deprecated in IBM API Connect Version 5.0.8 in favor of DataPower Gateway. From 1 April 2020, Micro Gateway, and associated toolkit CLI commands, will no longer be supported. Existing users can migrate their API definitions to IBM DataPower Gateways. For information on supported API policies, see Built-in policies.
   2. If the new Catalog is a development Catalog, enable development mode:
      • Click Info and select the Development mode toggle.
      • Click Overview and select the Development mode toggle.

      In a development Catalog, staging and publishing actions are forced, meaning that if you republish a previously published Product it is overwritten without warning. If conflicts are found, they are automatically resolved by the system. Unpublish actions happen automatically.

      Note:

      • In a development Catalog, approvals are bypassed for publishing and lifecycle actions; you cannot configure the Catalog to require approval. Pending approvals are canceled when a non-development Catalog is converted to a development Catalog.
      • 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.
   3. If you want to enable automatic subscription for the Catalog, select Automatic subscription.
      Enabling automatic subscription makes testing of your APIs easier because a test application is used, with a pre-supplied client ID and client secret, which is automatically subscribed to all the Plans in the Catalog, so you don't have to specify a plan or application when testing.

      Note:

      • Automatic subscription is available only for a development Catalog.
      • Automatic subscription is supported only with the DataPower Gateway.
   4. If the Catalog is the default staging Catalog, select Default. 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 only select Default for one Catalog.
   5. To enable the partition of this Catalog into Spaces, select the Spaces toggle.
      For more information, see Using syndication in IBM API Connect.
   6. Optional: Click Endpoints, and populate the following fields:

      Custom Gateway URL

      In the Custom Gateway URL text field, enter a URL. You use the Custom Gateway URL if you want to achieve custom branding of URLs for APIs that are deployed to IBM API Connect, rather than using the default URL that API Manager generates.

      By default, the IBM API Connect gateway URL has the following format:

      https://gateway_cluster_hostname/organization_name/catalog_name

      However, you can override the default by specifying a URL that is more appropriate for your enterprise; for example, https://api.mycompany.com. Any API endpoints that are displayed in the Developer Portal will then reflect the specified URL.

      Note:

      • You must configure a DNS entry that maps your custom hostname and domain to the default gateway URL.
      • For the endpoints of an API to reflect your custom gateway URL, you must configure the API to be enforced by the IBM API Connect gateway; for details, see specifying an alternative host for an API.
      • Ensure that the same custom gateway URL is not applied to multiple Catalogs as the behavior in that scenario is undefined.

      Custom API URL

      In the Custom API URL text field, enter the URL. You use the Custom API URL to specify the URL for APIs that are deployed to a third party gateway.

      The Custom API URL represents the endpoint by which the API is known externally; that is, the endpoint that is published to the developer portal and used by an application developer to invoke or advertise the API.

      If you are using a third party gateway or external load balancer in this Catalog, supply the URL in this field. Any API endpoints that are displayed in the developer portal will then reflect the specified URL. These endpoints exist on the third party gateway or load balancer and project a virtual address, exposed to API consumers, that is mapped to the API proxy or API assembly endpoints on the gateway. The endpoints that are derived from the custom API URL are typically published in production developer portals to advertise the address of the API.

      Note: If you specify a custom API URL for a Catalog, it takes precedence over any host name that you specify when configuring the API; for more information, see specifying an alternative host for an API.

      Hostname for Developer Portal API Calls

      In the Portal API Endpoint window area, enter a host name for Developer Portal API calls. The host name that you enter can be the host name of your Management service.

      To access the Developer Portal API within the context of a Developer Portal, you must configure the base host name for the Developer Portal API calls.

      This action allows API Manager to map your host name to the provider organization and Catalog of the Developer Portal API calls instead of requiring you to look it up and include them in your calls.

5. To configure the Developer Portal, click Portal and proceed with the following steps:
   1. Select IBM Developer Portal or Other, then enter the appropriate URL in the related text field.
      If you select IBM Developer Portal, enter the URL in 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.

      For more information on using the Developer Portal, see Discovering and using APIs.

   2. In the User Registry drop-down menu, select an existing User Registry or create a new one to be used by the Developer Portal. The user registry that you select is used to authenticate login to the Developer Portal. For more information, see Working with user registries. If you select Portal Delegated User Registry, see Portal Delegated User Registry for more information.
6. To configure the Permissions for the roles in API Manager, click Permissions.
   The Product management permissions to which you can assign roles are displayed:

   Stage

   Allow staging of Products to the Catalog.

   View

   Allow viewing and listing of Products in the Catalog.

   Manage

   Allow management of Product lifecycle (publishing, deprecating, retiring and archiving).

   Approve

   Enable approvals for Product lifecycle state changes.

   1. To add a Role to the Stage, View or Manage permissions, click the corresponding + icon. The following list shows the default available roles:
      • Administrator
      • Product Manager
      • API Developer
      • Publisher

      The Owner role has all permissions.

   2. Enable approvals for Product lifecycle state changes by selecting the required check boxes, then clicking the corresponding + icon to assign the roles that have permission to approve a lifecycle state change.
      The lifecycle state changes that you select are those for which you want to enforce approval. For example, if you select Publish but leave the others 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 assign the roles that have permission to manage user-defined policies, click the + icon in the Policy Management section.
      The policy management permissions are displayed, enabling you to assign roles as required.
7. To configure the Permissions that each role in API Manager has, click Roles.
   To add permissions to a role, or to remove permissions from a role, complete the following steps:
   1. Select a role from the list of available roles. You can configure the actions that permissions have for the following default roles that are available:
      • Administrator
      • Product Manager
      • API Developer
      • API Administrator
      • Catalog Owner

      You can configure the actions that permissions have for any custom roles that you have created, and are in the list of available roles. For details of how to configure a custom role, see Creating custom roles.

      Note: The Administrator and Catalog Owner role have all permissions. You cannot alter the permissions for the Catalog Owner.
   2. After you have selected the role that you want to configure the permissions for, select or clear any check boxes for any possible actions that you want to have enabled or disabled for a permission.
   3. To ensure a role can manage user-defined policies, select Manage for the Catalogs Settings permission.
   4. To grant a role the permission to approve a specific lifecycle state change, select the state change in the Product Lifecycle Approvals section.
   5. To specify the Product lifecycle state changes for which you want to enforce approval, click Approvals in the Catalog settings navigation pane, then select the required state changes.
      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.
   Note: The permissions that are assigned to each role by default when you create a new Catalog are determined by the settings in the default Catalog permissions template. For details, see Configuring the default Catalog permissions template.
8. To define the policies in API Manager, follow the procedure that is outlined in Importing a user-defined policy into a Catalog.
   Note: When you import a policy, its implementation is imported into all Gateway devices associated with the Gateway Cluster that hosts the Catalog. Additionally, API Connect modifies some object names and file locations to mark them with the appropriate Catalog name and policy version.

   Note: Policy implementation is a manual import for the Micro Gateway. For more information, see Packaging and importing your policies into IBM API Connect.

   For more information about how to create and manage user-defined policies, see User defined policies.

   Important: If you are using IBM API Connect for IBM Cloud (the SaaS offering), support for implementing your own policies is not available.
9. To import an extension schema into your Catalog so that you can extend the OpenAPI (Swagger 2.0) specification, click Extensions; for full details, see Adding an OpenAPI (Swagger 2.0) extension to an API definition (API Manager UI).
10. Click Save.
11. Click the Save icon .