Creating and configuring Catalogs (V5.0.7 and later)

These instructions describe how to create and configure Catalogs with IBM API Connect V5.0.7 and later.

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.
   6. To configure your Catalog, click the name of the Catalog, then click Settings.
3. To configure the general settings for the Catalog, click Overview, then proceed with the following steps:
   1. If the new Catalog is a development Catalog, enable development mode by selecting Development mode.
      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.

        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.

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

   2. 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.
   3. 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.
   4. To enable the partition of this Catalog into Spaces, select the Spaces toggle.
      For more information, see Using syndication in IBM API Connect.
   5. Optional: In the API endpoint for unenforced APIs section, enter a custom API URL.
      For any API, there are two possible endpoints to consider:

      • The gateway endpoint at which the API is invoked. The URL has the following format:

        https://gateway_cluster_hostname/organization_name/catalog_name

      • The endpoint that is visible to the consumer in the Developer Portal.

      If you do not configure a custom API URL, 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 custom API URL. 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. The URL represents only the server endpoint and does not include the path to the API itself; for example:

      https://custom_host.domain

      The ability to call an API without supplying the provider organization or Catalog name in the URL is called host to catalog mapping.

      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.

      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.

4. To configure the Gateway settings for the Catalog, click Gateways > Configure, then proceed with the following steps:
   1. Choose one of the following options depending on the gateway that is to be used with APIs that are published to this Catalog.
      1. If you are using the DataPower® gateway, select the DataPower Gateway services that you want to use with this Catalog.

         If you select two or more Datapower Gateway services, you can modify the Gateway service endpoint URLs, and configure your DNS appropriately, so that API calls are routed to the required Gateway service; for more information, see Using multiple DataPower Gateway services with a Catalog.

         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. Click Done to save your changes.

      When you modify gateway settings, the change takes effect almost immediately for all APIs in the catalog

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. To enable development application workflow for applications that are created in the Developer Portal that is associated with this Catalog, select Development Application Workflow.

      When development application workflow is enabled, any application that an application developer creates in the Developer Portal has Development status by default, and can call APIs in the Catalog only through dedicated DataPower Gateway service development endpoints. When ready, the application developer can request to upgrade the application to Production status. After the upgrade request is approved, the application can call APIs through the DataPower Gateway service production endpoints. For more information, see Managing the application lifecycle.

   3. 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.
      Note: After the User Registry is specified for a Catalog, you can change it only if no portal users have been created, and it’s not set to be a Portal Delegated User Registry.
   4. Specify your user registry options; for more information, see Working with user registries.
   5. Optional: In the Portal API Endpoint section, 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.

6. 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.
7. 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.
8. 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).
9. Click the Save icon .