An API Catalog is a component within your Provider Organization that provides a logical partition within your Provider Organization as well as the Developer Portal and the gateway executing the APIs themselves. This logical separation will be apparent in the Developer Portal and the URL used to invoke the APIs themselves as they will be unique for each Catalog. Catalogs are typically used to segregate each environment within your software development life cycle (SDLC). For example, you might configure DEV, STAGE, QA, and PROD Catalogs to represent each environment. You will see these as logical partitions within API Manager, however, you can choose to have different physical gateway services for each Catalog.
Now that you have your Provider Organization configured, you can move on to configuring your Catalog(s). The owner of the Provider Organization, or anyone that the owner has invited to the Provider Organization, can now log in to API Manager to perform this task. Before you begin to configure your API Catalogs, you should have already determined what Catalogs will be needed and what they will be named. This is all part of the careful, upfront planning you did before jumping right into your configuration effort.
Configuring your API Catalog
To begin configuring your Catalog(s), you will first log into API Manager using a credential that has been granted access to your particular Provider Organization. This could be the owner of the organization you previously set up, or some other person that was invited to join the organization. Let’s move on to the next steps now:
- Once logged into API Manager, you will be at the home screen with your newly-created Provider Organization shown at the top-right of the screen and several options on the main screen, as shown in Figure 3.6. From here, you will click on the Manage catalogs link:
Figure 3.6 – API Manager home screen
2. This will bring you to the Manage screen where you will see all Catalogs currently configured for your Provider Organization. You will notice one Catalog named Sandbox is present, which is created by default when a Provider Organization is created. Since you just created your Provider Organization, you will only see the default Catalog named Sandbox as shown in Figure 3.7:
Figure 3.7 – Manage Catalogs
3. You can choose to use the default Sandbox Catalog to quickly test APIs and resources such as LDAP registries for API authentication. Using the Sandbox to initially test APIs has the benefit of not needing to create a Product nor acquire a ClientId or secret. Those are automatically generated for you in the Sandbox. The Sandbox should be limited to learning and testing APIs. You will most likely want to start creating your own, more meaningful Catalogs that you included while planning your overall architecture. As mentioned earlier, a practical use of Catalogs is to have one for each of your SDLC environments.
4. To start, we will create a Catalog named DEV to be used for our APIC Healthcare organization’s development efforts and unit testing. To create a Catalog, from the Manage catalogs screen in API Manager, click the Add button at the top right of the screen, then click Create catalog as shown in Figure 3.7.
5. This will bring you to the Create catalog screen, showing the fields required to create a new Catalog where you will enter the Title for your new Catalog. In our example, we entered DEV as the title. Once the title is entered, you will see that the Name field is automatically populated with the slugified representation of the Title field. This will be used as part of the URL used to access the Developer Portal as well as to invoke your APIs published to this Catalog. This will be evident as we configure the Developer Portal.
6. You will notice that the Select user field is prepopulated with the user logged into API Manager. This user will be the owner of the new Catalog. You can select from the drop-down list any user that has been added to the Provider Organization as the owner of this Catalog. If you wish to add a user to the registry that you would want to be designated as the owner of this Catalog, you will need to return to the previous Manage screen and select Add | Invite catalog owner as you can see in Figure 3.7. Once all fields are completed for your new Catalog, you will click the Create button to create the new Catalog. Figure 3.8 shows this screen with the new Catalog being created named DEV:
Figure 3.8 – Create a new Catalog
7. After you click the Create button, the Catalog is created and you will be returned to the Manage screen where you will see the Catalog you just created listed on the main screen with a message at the top right, as seen in Figure 3.9:
Figure 3.9 – New Catalog created
We now have a Catalog created for our DEV environment but it is not yet ready to publish and execute APIs. For this, a gateway service must be assigned to this Catalog. This will be one of the gateway services that you would have configured in your initial setup in the Cloud Manager. This step is only necessary if you are not planning on configuring Spaces for this Catalog, which we will discuss later in this chapter.
8. If you are not planning on enabling Spaces in your Catalog, you can assign a gateway service to it by selecting your Catalog from the Manage screen and then clicking the Catalog settings tab at the top of the screen and then the Gateway services link on the left navigation. On this screen, you should see an empty list for your gateway services as you have not yet added one for this Catalog. Figure 3.10 shows this screen for our example DEV Catalog:
Figure 3.10 – Catalog settings | Gateway services
9. From this screen, you can add a Gateway service by clicking the Edit button in the upper-right corner of the screen. This will then bring you to a screen with a list of all gateway services configured that you can select from. Select the checkbox next to the gateway service you want to add to this Catalog and click the Save button. Figure 3.11 shows a gateway service selected for the DEV Catalog in our example:
Figure 3.11 – Select gateway service
10. After clicking the Save button, you will be returned to the previous screen where you will see the gateway service added to the list of Gateway services along with a message at the top right indicating that it has been added to the Catalog as shown in Figure 3.12:
Figure 3.12 – Gateway service added
At this point, you should have a good understanding of what a Catalog is and how it could fit into your API Connect Provider Organization structure. In our example, we walked you through the creation of one Catalog named DEV. You can repeat this process for every Catalog you need to create for your organization. Once that has been completed, you can move on to the next steps, which we will describe in similar detail.