API Connect

Obtain and configure the APIC Toolkit Designer and CLI on your local system

This section will showcase obtaining the toolkit required for the API developer to create and develop APIs and/or Products through the APIC Toolkit Designer, and publish them with the CLI. 

The overall details can be found in Installing the toolkit from the IBM Knowledge Center.

1. Log into IBM Fix Central and fill out the information to get to the API Connect downloads.
   
   
2. For the purpose of this demo, we will be taking the toolkit-loopback-designer-windows_lts_v2018.4.1.11. Please see the IBM API Connect Support Lifecycle Policy for more details on LTS releases.
   
   
3. Once downloaded, unzip the contents to a local directory (e.g. C:\APIC_Toolkit) to assign the folder to the system environment path. There will be 2 executables in the zip (api_designer-win.exe and apic.exe).
   
   
4. Set your Windows environment to the APIC_Toolkit folder so you will be able to reference the APIC command later from your local API working directory.
   1. Open the File Explorer (Windows button + E), right-click the “This PC“, and click Properties.
   2. Click on Advanced system settings in the System popup.
   3. Click on the Environment Variables…
   4. Locate the Path variable in the System variables list, and double-click to open.
   5. Add New with the path where the extracted files were located at from the previous step.

      Once completed, Ok/Apply everything.

      
5. Open a command prompt (Windows button > cmd > Enter). Type in apic version to verify that the environment has been set properly. 
   
   

Develop APIs and Products with the APIC Toolkit Designer

This section will showcase the APIC Toolkit Designer. The API developer will use this to create APIs and/or Products on their local system.

1. Create a working project directory of your choosing to store your APIs and Products, download the hellofromtoolkitdesigner_1.0.0.yaml and test-product_1.0.0.yaml, and store the following template APIs and Product yaml samples in the directory so the API Connect Designer tool will be able to use the “Work Offline” mode to interact with the API/Products and new API/Products you create. The sample being showcased will be located in the …/WORK/APIC_Toolkit/inProgress directory.
   
   
2. Open a command prompt (Windows key > cmd > press Enter). Type in api_designer-win and press Enter or navigate to where the api_designer-win.exe file is located and double-click, to open the API Connect Designer.
3. Once opened, you will see the “Open a Directory” to the directory which your APIs and Products are located. Select it and choose the directory you had stored the sample api/product from the previous step.
   
   
4. After selecting the directory that the APIC Toolkit Designer will use, click on the elipse on the next screen and select Work Offline.
   
   
5. In the next screen you will see the “Develop APIs and Products” tile. Select it and you will see the sample API and Product you have in your working directory.
   
   

   Here the API developer will be able to create APIs and Products on their local directory, and publish with the APIC Toolkit CLI showcased in the next section.

Publish with APIC Toolkit CLI

This section will use the APIC Toolkit CLI to publish a Product which contains the API/Product into the APIC cloud instance. This section will take the downloaded sample product and publish into the Catalog Space designated for the API developer. 

1. Go back to the command prompt (windows button > cmd > press Enter) and navigate to the working directory, which contained the sample Product “test-product_1.0.0.yaml“.
   
   
2. Log into the target APIC cloud instance which API developer has permission to within the Space with the following syntax:apic login -u <User> -p <Password> -s <APIM_Server_URL> --realm provider/default-idp-2

   The realm tells the toolkit command whether you are logging into the CMC or APIM and to which identity provider / user registry (local user registry, ldap, etc).

   You may find which identity providers on your APIC cloud instance are available by issuing the following commands:

   To get the user registry list of the APIM:

   apic identity-providers -s 

   To get the user registry list of the CMC:

   apic identity-providers -s 

   NOTE: The ibm-bluepages in the diagram below is a sample user registry configuration, which is not an APIC default.

   
3. The login should yield the following when successful:apic login -u <username> -p <password> -s <apim_server_url> --realm provider/default-idp-2
   Logged into <APIM_Server_URL> successfully
   
4. Once logged in, issue the Publish command:

   WARNING: Be wary of publishing a Product with the same name that may already be in the same catalog. This will OVERRIDE the previous one. For example, if there is a Test-Product that was published with API xyz, then another developer publishes another Test-Product (same name) that contains api abc, the newly published Test-Product with abc will override the xyz.

   apic products:publish -s <APIM_server_url> -o <provider_organization> --catalog <catalog> --scope space --space integration-developers test-product_1.0.0.yaml
   

Afterwards, log into the APIC cloud instance and you will see the API and Product has been published and ready to be tested.

NOTICE: The API is published to the Test-Product but will not be available on the APIC cloud instance to be modified because the developer does not have permission to upload the API/Product yaml artifact up to the “Develop” section of the APIC instance. It was only published to the catalog to go live. The API develop holds the source of that API/Product yaml. This next step for the developer is to check it into a CI/CD pipeline for QA testing.

References

• Installing the toolkit
• Toolkit command-line tool reference – apic login
• Toolkit command-line tool reference – apic products:publish