Up to this point, you have learned the role that APIs play in our new digital transformation and modernization space. You have also seen how API Connect (APIC) can provide all of the tools you will need to realize these benefits in a seamless and secure manner. You are probably eager to dive right in and start creating and exposing your own APIs! You will get there but before doing that it is critical that you take some time to get organized and perform some housekeeping to ensure your digital transformation is following a framework for success.
If you think about it, an API is nothing new. It is simply a common piece of code or a module that can be called or consumed from some other program or application. The thing that sets APIs apart is how you organize, publish, and make them available to the outside world for consumption. The old "if you build it they will come" line of thinking really doesn't apply when we are talking about APIs. They need to be easily discovered by consumers and well organized. This is why taking the time to set up and get organized is critical. API Connect provides the framework for you to organize and publish your APIs so that consumers can discover them easily and know how to invoke them.
Of course, stating that you must take the time to plan out your organizational structure is easy to say, but if you are not aware of what each component is and how it could impact the final outcome, it might be a more difficult task than it should be and you will likely not get the desired outcome.
In this chapter, we will discuss and demonstrate how API Connect allows you to organize your API environments. This will include everything from who can create and manage products and APIs to how they are managed throughout their life cycle, and finally, how consumers can discover them. When you are finished, you should have a good understanding of how this all fits together, which will give you the knowledge to guide yourself through your own planning exercise. To accomplish this, we will cover the following main topics:
This chapter will start with the assumption that you already have an API Connect installation complete, along with the required components configured within the Cloud Manager. You should have all of your gateways services, SMTP server, and portal services already configured. Your hostnames being used for all of your services and components should be added to your DNS server and network communication between all components should be open.
As you are introduced to all of the terminology and structure of how things are organized within API Connect, it could start to get a little overwhelming. So before diving into each piece of the setup that you will need to perform, let's take a look at the big picture and how things are organized. Hopefully, this will give you a high-level perspective on where each piece of the puzzle fits and provide some clarity on how you can structure your environment.
In Figure 3.1, you can see a very high-level overview of the main components and their hierarchy. You can see here that most of these components are required and you can have more than one defined. The one exception here is spaces. Spaces are not required but we will get into more detail on this in the Utilizing spaces section later in this chapter. Also, note that for simplicity, plans are not shown here as they will be covered in subsequent chapters:
As we go through each of the components shown in Figure 3.1, you can refer to it to see where and how each of these fits into the overall scheme. Although your implementation and organization will likely be more complex, this will give you the most simplistic view for your understanding.
For a more realistic illustration, Figure 3.2 shows what a typical organization structure might look like. Your setup will likely expand upon this, but this will give you an idea of the basic structure:
The remainder of this chapter will take the time to explain the role of each of these components and how to configure them. Again, careful planning and understanding of these concepts will ensure that your digital transformation is following a framework for success!
Your first step when configuring your environment is to define your Provider Organization. As you can see in Figure 3.1, this is the highest level in the hierarchy. This is typically defined for your organization and it is common to only have one. It is, however, possible that you would like to define multiple Provider Organizations to represent different subsidiaries of your parent company.
A Provider Organization is just as it sounds. It is the organization that provides the APIs. This should not be confused with a consumer organization, which you might have guessed is the organization that consumes the APIs. Defining your Provider Organization is done within the Cloud Manager UI and must be defined before you or anyone else can access the API Management Console to develop and publish your APIs. It is here that you define a few important pieces of information, as follows:
Let's begin with the configuration:
All of your pre-defined public registries will be listed in the User registry field within a dropdown.
Info:
User registries have visibility. When the cloud administrator sets a user registry to private, that user registry will not be available when creating a new Provider Organization.
One of these must be selected before entering the owner's user ID. An important thing to note here is that once your Provider Organization is created, you cannot change this value to a different user registry.
Congratulations! You have now created your Provider Organization, which will be the foundation for all other components that you will define within it. The owner of this organization can now invite other users to the organization and move on to the next step of the process, which is to create the Catalog(s) within the organization.
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.
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:
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.
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.
Spaces are a part of the API Connect syndication feature, which will allow you to subdivide your Catalog into partitions. Of all of the configurations we have covered within this chapter thus far, this is the first optional configuration we will demonstrate. Spaces could be useful if you have different divisions within your organization that you need to segregate within a Catalog.
For example, our sample healthcare organization might be split into two divisions within the company. One for prescription benefit management (PBM), and one for insurance. We might want to segregate these divisions within our Catalogs so that each division will be independent of the others within the Catalog. This independence would include the separation of authorized users, product life cycle, and runtime environment altogether.
Spaces would be the ideal feature to accomplish this because it provides this logical partition from all other spaces within the Catalog as well as a segregated runtime environment. In addition, Spaces will provide its own analytics for each space configured. Keep in mind that this only provides this segregation for development, management, analytics, and runtime, which are all internal. Spaces will not be evident within the Developer Portal to an outside consumer. To the outside consumer who will discover and consume your APIs, they will all appear to be within the same Catalog.
New with v10.0.1.5
There is a new feature to apply Catalog actions to Spaces. You can read more on this capability in the What's New section: https://www.ibm.com/docs/en/api-connect/10.0.1.x?topic=overview-whats-new-in-latest-release-version-10015
If you decide that your organization will require the use of Spaces, you must configure them at the Catalog level within each individual Catalog configuration.
Here is how we configure the spaces:
Once you enable Spaces within a Catalog, you can no longer configure a gateway service for the Catalog. At least one space must be configured and assigned a gateway service. Products and APIs can only be published to a space and not the Catalog itself.
If you wish to invite a new user to be the owner of the space, you will go to the previous screen and click Add | Invite space owner. Once these fields are populated, you can click Create to create your new Space. Figure 3.15 shows the creation of a new space for our healthcare organization with a Title of PBM:
The structure of our new organization is now starting to take form. Up to this point, we have defined our Provider Organization, Catalogs, and spaces. We now have the ability to start publishing products and APIs, which we will cover in later chapters.
Once you have configured your carefully planned out Provider Organization, Catalogs, and spaces, you can technically begin developing and publishing your APIs and products. Although you might be tempted to jump right into this, there is one final piece we must configure so that the consumers can discover your APIs—the Developer Portal. You might develop the most useful APIs going, but as we said earlier in this chapter – if no one can find them, they aren't much good.
The Developer Portal is the place developers will go to discover and register for your APIs that are available. This is where you will socialize your APIs to the outside world. This is their window into your API organization. In addition to socializing your APIs, the Developer Portal also provides analytics, forums, blogs, and rating facilities.
Since this is where the consumers of your APIs will go to find them, the Developer Portal will be a representation of your company to the outside world. For this reason, the Developer Portal is fully customizable so that you can brand and customize it to best represent your organization. The level of customization is entirely up to you, though. You can put as little or as much time into customizing it as you see fit.
Before we think about customization and branding, we must first configure the Developer Portal for each Catalog.
This is done at the Catalog level for each Catalog you have configured within your Provider Organization.
This will bring you to a screen where you will simply need to select one of the Portal services that were created in the Cloud Manager during your initial setup. You will see that the URL field will be automatically populated for you, which will include the Provider Organization and the Catalog name in the URI.
This is a one-time-use-only link and will bring you to the page shown in Figure 3.22, which will make it clear that this link can only be used once. From here, you will click the Sign in button to change your admin password:
You have now successfully added a Developer Portal for your Catalog. You would need to repeat this process for each Catalog within your Provider Organization the same way. As you complete this process for each Catalog, you will notice that the URL to access the Developer Portal for each Catalog will change to reflect the Catalog that it belongs to. As you publish your products and APIs to each of these Catalogs, you will see them appear in the respective Developer Portal for consumers to discover.
At this point, you can move on to customize your Developer Portal to personalize and brand it to represent your organization, or you can simply leave the default look. The choice is entirely up to you. You can find more information on customizing the look of the Developer Portal in Chapter 15, API Analytics and the Developer Portal:
You have now completed the configuration of your entire Provider Organization and can now begin to create, publish, and socialize your APIs!
In this chapter, we have taken you on a long journey and introduced you to many terms and concepts. You were introduced to configuring your first Provider Organization, Catalogs, spaces, and finally, the Developer Portal. All of this may seem a bit overwhelming at first, but as you go through your planning sessions to determine the structure and layout of your own organization, this will become clearer. It cannot be stressed enough how critical careful upfront planning and organization are to the success of your digital framework transformation. This will become more evident as you go through the API life cycle from development, to publishing, to retirement.
Now that you have learned about the foundation for setting up your API environments, our next chapter will expand on this by explaining and demonstrating the process of creating your own APIs.