Overview

Skill Level: Any Skill Level

Since the "Develop APIs and Products" tile is not accessible to API developers within a Space, they will have to use the toolkit to develop and publish APIs/Products. This tech note show cases those steps (on Windows).

Ingredients

There is not a lot of samples as to how an API developer whom have been assigned to a Space within APIC will be able to develop new APIs and publish them into their perspectively assigned Space, therefore this article was created to provide a little insight into how API developers will be able to create APIs/Products on their local systems.


You'll notice that if you assign an API developer to a Space, they will not be able to see the "Develop APIs and Products" tile to create a new APIs or Products.

This is because the ability to create draft APIs and Products on the APIC cloud instance is on the provider organization level, and if the developer role is assigned on that level, they will be able to see all the catalogs and spaces, and be able to modify all the APIs/Products on all Spaces, which defeats the purpose of the Spaces. Therefore, by only assigning the API developer into a Space and enabling the developer role, they will have to create new APIs and Products through the APIC Toolkit Designer and publish via the Toolkit CLI, which this article will showcase (on Windows).

More about user roles may be found in the IBM Knowledge Center: API Connect user roles.

Assumptions: 

  • Spaces have been activated and created in one of the Catalogs.
    01.SpacesEnabled

  • The Space used in this example will be Intergation-Developers 
    and the apiconnect.dev@gmail.com user will be the sample API Developer.
    02.1.spaceMember

Step-by-step

  1. 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.
      03.FixCentral
    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.
      04.fixcentralDownload
    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).
      05.toolkitunzipped
    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.
        06.envSet

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

     

     

  2. 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.
      08.sampleapiandproduct
    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.
      09.OpenaDirectory
    4. After selecting the directory that the APIC Toolkit Designer will use, click on the elipse on the next screen and select Work Offline.
      10.workoffline-2
    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.
      11.Developapiproducts

      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.

     

     

  3. 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“.
        12.cli_
      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 <APIM_Server_URL> --scope provider

        To get the user registry list of the CMC:
        apic identity-providers -s <APIM_Server_URL> --scope admin

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

      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

         14.apicLogin-2

      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

         15.publish-1

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

    16.publishedproduct17.publishedapi

    NOTICE: The API is pubished to the Test-Product but will not be available on the APIC cloud instace 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.

  4. References

     

     

     

Join The Discussion