IBM API Connect Tutorial: Part-1 Develop your first API

Introduction

In my previous article, I demonstrated how to set up IBM APIC LTE or IBM API Connection Local test environment. In this article, you will learn to develop your first API using IBM API Connect and test using LTE setup. As it is usually the practice, let’s build a Hello World API

System Pre-requisite

• IBM API Connect LTE
• IBM API Connect designer toolkit
• Test tool like postman, curl or soap-ui

Start APIC LTE

• Open a command prompt
• Traverse to C:\apic-lte\win and issue following command

Develop your first API

• Let’s start to develop your first API using IBM API Connect
• If you followed my last tutorial, you must have created a helloworld folder in C:\apic-workspace. If you have not already, create a helloworld folder in C:\apic-workspace path. You can choose your own folder structure as well.
• Double click on the API Designer shortcut. A window will open up. Click on “Open a Directory” button. A pop-up will open. Select the helloworld folder that we created above.

• Once done, it will open up a new page with a button “Connect to API Connect”. If you have not already done, connect to your LTE API Manager [follow this link]. As we have already connected to the LTE API Manager in our last tutorial, we’ll see a window similar to the following. Click on the localhost cloud

• Now, a window will open up where we will enter the credential as displayed in the apic-lte start command output and log in to the designer toolkit:
  • User: shavon
  • Password: 7iron-hide
• Once logged in successfully, click Develop APIs and Products

• A new page will open up. Click on Add -> API.

• A page will open up. In this page select New OpenAPI and click on Next button.

• In this page, fill up the form as below and click on Next button.

• A new page will open up. No need to change anything in this page. Click on Next button.

• In the next page, click on Edit API button.

• A new page will open up. You can browse through all different fields. This is GUI where you can design/develop your APIs.

• Notice that the basepath is set to /helloworldapi. Keep a note of this as we will need this later while testing.
• Any change that you make in these forms, will actually get translated to a swagger following OpenAPI specifcification. You can click on the Source tab and see the swagger file

• Anyways, click on Design tab and then click on the Security Definition menu on the left. You will see clientId security definition is already added. However, we want to secure our API with both clientId & clientSecret. Hence, we’ll need to create a new security definition for clientSecret. Click on Add button

• A new page will open up, fill in the form to add a clientSecret security definition and then click on Save button.

• Next click on the Security menu and select both clientId and clientSecret. Thereafter, click on Save button.
• Click on the Paths menu and delete the default path

• Then, click on Add button. A new page will open up with form. Fill it up as below:
  • Path Name: /test
  • Scroll down and click on Add button in the Operation Segment, select GET operation and then click on Add button.

• Click on Save button.
• We’ll now select Assemble tab on top. This will open up assembly area where we’ll write all the required logics for the API. On the left pane, we’ll see all different in-built policies and in the large right pane, we can write API assembly. By default, there will be an invoke policy.

• Here in this API, we won’t invoke any backend URL. Instead, we will just print Hello World from APIC. Hence, first delete the invoke policy by hovering your mouse over it and then clicking on Delete button.
• Thereafter, drag GatewayScript policy from the left pane onto the assembly area like below.

• On the right pane, you will notice a black window. This is where we’ll write gateway Script. Paste the following code into the black window and click on Save button.

• Now, it is time to test. We will first test using the GUI itself. Let’s publish this API to sandbox catalog by clicking on the yellow highlighted triangular button as mentioned in below screen.

• Ensure to save and republish each time you are making any change to the API by clicking on the yellow highlighted button as seen below

• Our HelloWorld API is now published. It’s time to test.
• The URL of this API is:

Now, if we fill up the above parameters in the context of our IBM APIC LTE and our HelloWorld API, the URL becomes :

• If you recall, we have secured our API with clientId and clientSecret.
• For IBM APIC LTE, the test id/secret will already be available as command output when you start the apic lte. So, we’ll use the same id/secret for testing this API.

Test the API

• Launch postman (I have used post-man, you can use any other tool as you wish).
• Fill up as follows:
  • Method: GET
  • URL: https://localhost:9444/localtest/sandbox//helloworldapi/test
  • X-IBM-Client-ID (Header): copy and paste from the command window that we executed in the initial step of this tutorial [apic-lte start]
  • X-IBM-Client-Secret (Header): copy and paste from the command window that we executed in the initial step of this tutorial [apic-lte start]

• Click on the Send button. You’ll see the result as below.

Additional Information

When we launched the API Designer, we selected a folder C:\api-workspace\helloworld. This folder is basically our API workspace. The artefacts that we created using API designer will be stored in this folder. You can traverse to this folder at this point and you will notice 2 yaml files. One file is the actual API that we defined. Another is auto-product file that gets automatically created when we click on publish button from designer toolkit.

More on this in upcoming articles.

API Swagger

Please find below the swagger file of the API we just developed above. The same code is also available in github

Conclusion

You just learnt how to develop your first API using IBM API Connect. I’ll cover many more interesting topic in future. Stay tuned!

Reference

• https://www.ibm.com/support/knowledgecenter/SSMNED_2018/com.ibm.apic.toolkit.doc/rapic_apigw_apis_gws_xslt.html
• https://www.ibm.com/support/knowledgecenter/SSMNED_2018/com.ibm.apic.toolkit.doc/rapic_lte_api_test.html