Creating and configuring Catalogs
These instructions describe how to create and configure Catalogs in IBM® API Connect.
Before you begin
- As the user who creates the Catalog, you are automatically the Catalog owner and have all Catalog permissions.
- If you configure a new user registry for authenticating users to the Developer Portal, you must also complete the onboarding section in the Catalog, to make the registry available to Developer Portal users. See Step 15 for details.
- Every account in the Developer Portal,
including across different user registries for the same site, must have a unique email address,
including the site Admin account. For example, if you configure three different user registries for
a particular Developer Portal
site, the email address alice@acme.com can be used to log in to the site from
only one of the user registries. The default email address for the Admin account is the email
address of the Catalog owner. It is not possible to create a user account (and associated Consumer
organization) with the same email address as the Admin account (or that of the Catalog owner if
their email address is different). Any attempts to create an account with the same email address
results in the new account not functioning correctly, and returning the following error message when
trying to log in:
A user already exists with this email address
.
Procedure
To create and configure your Catalog, complete the following steps:
- Log in to API Manager and click
Manage.
-
Create the Catalog.
You can create the Catalog in either of the following ways:Specify the owner, then configure the Catalog:
- Click Add > Create catalog.
- 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.
- Continue from step 3 to configure the Catalog.
Send an invitation email, with an activation link, to the intended Catalog owner:
- Click Add > Invite catalog owner.
- Enter the email address of the Catalog owner, then click Invite.
- On receipt of the email, the Catalog owner must activate the Catalog and configure it:
- Open the activation link, complete the sign up form, and sign in to the API Manager UI.
- Click Manage Catalogs, click the Catalog name that was provided on the sign up form, then click the Catalog settings tab.
- Continue from step 6 to configure the Catalog.
- 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.
- Click Create. Your new Catalog is displayed on the Manage page.
- To continue to configure your Catalog, select the Catalog on the Manage page, then click the Catalog settings tab.
-
To configure the general settings for the Catalog, click Overview, then
proceed with the following steps:
-
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 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.
-
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.
-
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 only for 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.
-
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.
- To transfer ownership of the Catalog to a different user, click
Overview, then proceed with the following steps:
- Click Edit.
- From the Select owner user drop-down menu, select the user who will become the new owner.
- 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.
- 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.
- 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.
- Click Edit.
-
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), DataPower API Gateway, or Event Gateway Service if you have Event Endpoint Management enabled in Cloud Pak for Integration. For more information, see API Connect gateway types.
- 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, DataPower Gateway (v5 compatible), and Event Gateway Service.
A Product is gateway type specific: DataPower API Gateway, DataPower Gateway (v5 compatible), or Event Gateway Service. 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 the toolkit CLI reference documentation. - To specify the Product lifecycle state changes for which you
want to enforce approval, complete the following steps:
- Click Lifecycle Approvals in the Catalog settings navigation pane, then click Edit.
- 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.
- 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.
- Click Save.
- To configure the publish validations that are performed when a Product is
published, complete the following steps:
- Click Publish validations in the Catalog settings navigation pane.
- Click Edit, and select or clear the validation check boxes as
required. The following validation options can be selected:
- Publishing APIs with empty paths is not allowed.
- Validate custom policy schema in assembly.
- Validate the references inside the API and perform additional OpenAPI validations.
- Publishing APIs with duplicate base paths is not allowed.
- Click Save.
-
To configure the permissions that each role in API
Manager has, complete the following
steps:
-
Click Roles in the Catalog settings navigation pane.
To see the current permissions for a role, expand the role.
-
Click the options icon
alongside the role that you want to work with, then click Edit.
-
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. - Click Save when done.
-
Click Roles in the Catalog settings navigation pane.
-
To configure the default role permissions for consumer organizations that are created in this
Catalog, complete the following steps:
- Click Role Defaults in the Catalog settings navigation
pane. To see the current default permissions for a role, expand the role.
- Click the options icon
alongside the role that you want to work with, then click Edit.
- Select or clear the permissions check boxes as required.
- Click Save when done.
- To create a new role and assign default permissions to it, click Add, name the role and assign permissions, then click Save.
- Click Role Defaults in the Catalog settings navigation
pane.
- To manage the onboarding of API consumers into this Catalog, complete the
following steps:
- Click Onboarding in the Catalog settings navigation pane.
- 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.
- To set a default registry, click the options icon
alongside the required registry, then select 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.
- 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.
- 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.
- 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.
- 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.
- 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.
-
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:
- Click the Catalog settings tab, and then select API User Registries.
-
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.
- 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
.
-
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.
- Click OAuth Providers in the Catalog settings navigation pane.
-
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.
- Click Save when done.
- 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.
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 thehost
field is not included in the API endpoint.
- 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 theservers
array in the OpenAPI definition of the API is used to determine thebasepath
element of the API endpoint, as follows:- 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
- If a full URL is specified for the server URL, the scheme (
http://
orhttps://
) is ignored by the DataPower API Gateway, and the remaining host name andbasepath
are used to form the API endpoint as follows:https://gateway_service_host/provider_organization/catalog/host_name/basepath
- 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.
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.To configure vanity API endpoints, so that you can publish endpoints that are different to these gateway endpoints, complete the following steps:
- Click API Endpoints in the Catalog settings navigation pane. The Vanity API Endpoint page opens.
- Click Edit.
- To display the current API base endpoint settings, select Display vanity endpoint.
- 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 behttps://prod.acme.com/basepath
.The way in which thebasepath
is determined depends on the OpenAPI version of the API, as follows:- (OpenAPI 2.0): The
basepath
is taken from thebasepath
field in the OpenAPI definition. (OpenAPI 3.0): The
basepath
is taken from the firsturl
entry in theservers
array in the OpenAPI definition, ignoring any scheme (http://
orhttps://
) and host name.
- (OpenAPI 2.0): The
- 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 theservers
array in the OpenAPI definition.
- If the OpenAPI definition has a host defined,
- 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
- 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.
apigw.dc.zone.mycompany.com
and an IP address of29.12.141.150
, then the generic DNS configuration might look like:
orapi.acme.com. CNAME apigw.dc.zone.mycompany.com.
api.acme.com. A 29.12.141.150
Consult your network administrator and the DNS provider's documentation to do this configuration.
- 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.
- Click TLS Client Profiles in the Catalog settings navigation pane.
-
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.
- Click Save when done.
-
To configure the Developer Portal,
complete the following steps:
- Click Portal in the Catalog settings navigation pane, then click Create.
-
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.
- Optionally, override the default generated portal URL. The URL must have the following format:
where host_name.portal.com must resolve to the IP address of the Developer Portal machine.https://host_name.portal.com
For example:https://myhost.mydomain.com
Important:To implement sub paths into your site URL, see Sub paths for Developer Portal sites.- 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.
-
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.
- 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:- Click the User icon
, and then select My Account.
- Check the contents of the Email field, and specify a value if necessary, then click Save.
Note: If you want to edit the portal service or URL, or delete the portal site, return to this portal settings page, click the options icon, and click Edit or Delete.
- To define Catalog properties, complete the following steps:
- Click Properties in the Catalog settings navigation pane, then click Create.
- 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.
- 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.
What to do next
For more information about how to create and manage user-defined policies, see User defined policies.