FHIR is an emerging standard that many healthcare companies are moving to as they digitally modernize. FHIR is based on serving up REST APIs with JSON and is a good case study to begin our introduction into CLI.
To set the context of how the CLIs work, it’s important to understand how an executed command integrates with API Connect. API Manager maintains the database of all the artifacts and resources that comprise the API Connect cloud. When you issue a command that will interface directly with API Connect, the call will pass through the Platform-API interface. For that to happen, you need to log in to API Manager. Additionally, your credentials need to have the appropriate role and permission to execute the CLI commands.
To make this introduction more interesting, we’ll take a typical workflow scenario and issue the appropriate commands to achieve the goal. We’ll assume you have downloaded the toolkit highlighted in the Technical requirements section and ensured that it’s within the path.
You, as a developer, have been tasked to take an existing OpenAPI FHIR swagger file and create an API definition within the APIC healthcare organization. You must upload the FHIR API into API Connect and stage and publish it to the Sandbox Catalog. Your goal is to take what you have learned and teach the DevOps team, so they understand how to get started on building a future deployment pipeline. Here is what you will learn:
- How to get your IDP; you need to know what registry to log in to.
- How to supply the required parameters to log in to API Manager
- Set the command configuration to specify a Catalog for deployment.
- Create an FHIR API draft by using an existing OpenAPI document.
- Run a stage deployment of your FHIR API to that Catalog.
- Publish the FHIR API to the Catalog that also pushes it to the portal.
To identify the arguments that you will need to provide for each CLI command, you can use this guide to identify the required parameters. For these examples, we present arguments that can be used in a fictitious environment. As you run CLI commands that specify a server name, you will need to replace those with your server name. The use of the Sandbox Catalog will be throughout these examples because the Sandbox Catalog is always created for you, by default, when you create a new Provider organization. To provide some context regarding the target environment, Figure 2.20 depicts the API Connect Manager’s relationship with the Provider organization and Catalogs:
Figure 2.20 – An example target API Connect environment
The < > symbols signify a field, and you must supply a value for these fields. Inside the symbols will be example values to give you some context. Some examples include the following:
<api manager host> = api-manager-ui.apicisoa.com
<userid> = isoadeveloper
<catalog> = sandbox
<organization> = middleware
Now that you understand how to provide the variable arguments, you can begin with the CLI development flow. Open up a Terminal window/Command Prompt, and we will go ahead and learn how to interact with the IDP.
Determining realms and IDPs
There is a concept called realms. If you recall, the management server comprises two user interfaces: Cloud Manager and API Manager. When you use the CLI commands, you need to specify which target environment (either Cloud Manager or API Manager) you want the commands to apply to. Here are the realms:
- For Cloud Manager, the scope is called admin.
- For API Manager, the scope is called provider.
You need to find out which user registry points to the realm you desire. API Connect can have many user registries for different realms, so finding the correct one is important.
You will use the apic identity-providers:list command to obtain a list of registries used for Cloud Manager. To do that, you will have to pass the scope argument, specifying admin. Additionally, you need to provide the hostname, following the –server argument. As mentioned earlier, <api-manager-ui.apicisoa.com> represents the hostname that you will substitute with the hostname of your API Connect environment:
apic identity-providers:list –scope admin –server <api-manager-ui.apicisoa.com>
default-idp-1
Notice that default-idp-1 is returned. This means that when you log in to Cloud Manager, you must specify this user registry.
So, what about getting Providers? You can use the same command, but this type provides a scope of provider:
apic identity-providers:list –scope provider –server <api-manager-ui.apicisoa.com>
default-idp-2
Once again, it returns the user registry. This time, it is telling you that default-idp-2 is what you will be using when you log in to API Connect to work with API Manager. Now that you have that important data, it’s time to log in.