Introduction

I am back with another post in the IBM API Connect tutorial series. In my previous related articles, I have covered easy way of installing IBM API Connect and how to setup the IBM API Connect in your local system. Now, in this blog post, we will learn  how to develop APIs in IBM API Connect. It will also cover an overview of IBM developer portal; how to subscribe the API from developer portal.. Lot’s of learning here; stay tuned.

What will we develop

Before we start, let’s first understand what we will do. As part of this development exercise, we will have a backend service that will have only one HTTP GET operation. When we’ll hit the service, it will return a number of Orders. We will expose this service through an API in IBM API Connect. Imagine the backend service as a legacy service in your organisation and you want to expose it through the IBM API Connect.

For the sake of simplicity, we will not spend much time behind the backend service. We will use one popular freely available online tool to mock the service itself. We will then develop the API that will invoke this service. We will also demonstrate how a developer can subscribe to this API from developer portal. So, let’s get started.

Tech Stack

Following are the stack used here –

Create the Service Mock

As discussed above, let’s first create a mock GET Orders service. We will use https://www.mockable.io/ for our simple mocking.

• Open the above site and click on Try Now button. In the next window click on  DEFINE A NEW REST MOCK.
  

  select-mock-rest-service

• In the next window, let’s define the mock service. I have used following configuration on to mock the service –

define-mock-rest-service

• In the Response body segment, I have pasted a sample Orders data and then pressed the button to start the mock. The sample data that I used is available in here. The mock service URL can be seen in above screenshot. When you use this site to mock a service, you will have a different URL. So, don’t copy the mock service URL from this tutorial; use your own.

start-mock-rest-service

• Once the mock service starts, copy the URL and hit it from browser. Observe that it’s returning the same data that you have placed in the response body.
• Well, now we are ready with the mock service.

Create a REST API Definition in IBM API Connect

• If not already open, hit the URL https://apim/apim in your favourite web browser and login with your credential. If you are following my users, I will use order.org.owner@iteritory.com user credential.
• Once the portal opens, click on the APIs tab –> Add button (on the top left corner) –> New API menu item. As our backend service is a legacy one and as such doesn’t have any definition; we will define the API from scratch. This will also give us some insights into how the API is defined in IBM API Connect.
  

  apic-create-new-api

• As we click on the New API menu item, a new popup will open to define the API. We can populate the form as we wish. Here, as our API is related to Orders; we are defining as follows.
  

  apic-define-api

• If you notice, we have selected Security scheme as Client ID and secret and also we have selected Datapower Gateeway.
• Click on Create API button.
• It will take a few seconds to create the API we just defined and a new web-page will open up. This is the complete definition of the API. On the left pane, you can see different options, you can click those to review/change anything as you want.
  

  apic-api-design-page

• Also, if you notice, by default at this point, we are Design tab. There is a tab just adjacent to it called Source. Click on it and you will notice it’s nothing but a swagger definition of the API that we just created. Amazing!! isn’t it? If you are comfortable, you can very well modify this source itself to define the API as per your choice.
  

  apic-api-source-swagger-definition

• However, in this tutorial, we will stick to GUI. So, let’s switch back to Design tab. We will make following changes.
  • In the Info segment –
    
    Description field: Order API

    1	Description field: Order API

  • In the Contact segment –
    
    Name field: Orders API Owner Email field: order.org.owner@iteritory.com URL field: https://iteritory.com

    1 2 3

    Name field: Orders API Owner Email field: order.org.owner@iteritory.com URL field: https://iteritory.com

  • In the Terms and License segment –
    
    Terms of Service field: https://iteritory.com/sample-terms-of-service License Name field: Lience1 License URL field: https://iteritory.com/sample-licnese-url

    1 2 3

    Terms of Service field: https://iteritory.com/sample-terms-of-service License Name field: Lience1 License URL field: https://iteritory.com/sample-licnese-url
• Next, we will move to Base Path. Verify that we have the value as /orders. Leave it as-is.
• Let’s select Paths menu item on the left pane. You will notice the Path segment will be on focus on the right pane. Click on the plus symbol on the extreme right and then rename the path as order. HTTP GET operation will be auto selected. You can add new operations are required. However, for this tutorial, we will just use the GET.
  

  apic-define-api-path

• Click on Save icon on top-right corner.

Edit API Assembly Section

• Now, click on the Assembly tab which is adjacent to Design and Source tabs.
• You will notice a new page will open up with a lot of operations on the left side and on the right side editor, there will be an icon which is called Invoke. You can drag and drop multiple actions from the left pane and do your orchestration. However, in this tutorial, we will keep it simple. Just click on this Invoke icon on the right side editor and you will notice, a sliding bar will open up on the right-most side. It will have multiple options to configure. All the options come with some explanation. Please go through those for understanding.
  

  apic-design-assembly

• For our scenario, we will just update two segments in the right-most side pane.
  • URL:- We will put the mock service URL that we created in one of the first step.
  • HTTP Method:- We will also select HTTP Method as GET
• Click on Save button on top right corner.
• That’s it!! we have just defined our first API.

Test API

• IBM API connect is a sophisticated tool and it provides you an in-built test utility. It helps developer to test the API right inside the API window without having to create an application etc. Let’s take a look on how to do it.
• Take a look at the below screen grab. Notice the triangular icon just below Source tab and on the left of Search. That’s the test button.
  

  apic-test-own-api

• Click on it and notice a new sliding bar opening up on your left replacing the older one. Select the product (we created this product as part of API development environment setup.) from drop down. Click on Add API button. It will probably take a few moments to add the API to the selected product. Then click on the Next button located in the bottom of this left most bar.
  

  apic-test-select-product

• A new page will open in this left bar itself. Select the GET operation that we created in the API design phase.
• Scroll little down to check the security setup. Remember we have selected the API to have both Client ID and Client Secret. Select the drop-down and observe that API Connect test utility already generated both the values without the developer having to do anything. This is a cool feature and I like it!! 🙂
  

  apic-verify-security-settings

• Click the Invoke button.
• If it gives any error on first time, you may republish by clicking Republish Product button. The result will be shown in the same pane as follows. Notice the black box containing the same data you configured while mocking the service-
  

  apic-successful-developer-test-result

•  Well, that’s amazing!! isn’t it. With this test, we can say that our API is working fine.
• However, this is just a API provider team’s test using a utility. But how does an external API developer who wants to consume this API? Well, we’ll explore that in next section.

Put on API Consumer hat and explore IBM Developer Portal

• Ensure that you are still running the email client at http://email:5080
• As part of our setup process, we already created the developer portal –> https://ibmportal/orders/sb
•  Open this portal in browser and click on Create an account link on top-right corner.
• A form will open up; fill it up and create the account for API consumer.
• Once done, it will send an account activation email to the email id that was used to register the API Consumer. Refresh the email client, copy the invitation link and open it in browser.
• This will activate the account and present login page. Provide the user-id and password that we created above and login to the IBM Developer portal as an API Consumer.
• Click on the Apps menu item and then click Create new app button.
• A new web page will open up for registering a new application. Let’s provide appropriate name and description and click on Submit button.
  

  apic-developer-portal-register-app

• Once submitted, a new web page will come up with the client id, client secret and other detail. Ensure to copy the client id and client secret by clicking on the show checkbox available. Keep it safe. Client secret will only be displayed once. If you forget or lose it, you can verify the secret to see if it’s correct or reset it to get a new one.

apic-developer-portal-app-created-screen

• Now, click on the API products link on top menu; a new webpage will open with the list of products available. In our case, we have only i.e. orderproduct (1.0.0)
• Click on the product and explore the new page that will open up. It will include the detail of the product and the associated plans etc.
• On the left pane of the page, you will see the API as well. Click on the API and the operation that we created. Explore this page, it has got so many information –
  • It has got the swagger definition of our API in yaml format. If any consumer wants to implement/auto-generate code based on this swagger, he/she can download and use it accordingly.
  • It also has the contact information that we configured in the API design phase
  • It has got decent documentation of the API as well; in bottom, you have got the option to give a piece of our mind about the API through the comments section as well.
  • On the right side, you will notice code fragments required to implement this API in various languages.
    

    apic-developer-portal-detail

  • You can also see the option to discuss this API in the forum as well.
  • As we finish exploring, we will click on the Subscribe button to ensure that this newly created consumer app subscribes to the plan.
• Thereafter, we can either test the API right from this portal; or we can also use any REST client like postman, SOAP UI etc to test this API.
• For the sake of simplicity, I have used a curl command to test this API and it gives perfect result that we mocked in the initial phase of this tutorial. I have used –insecure option as it is my local environment. In enterprise environment, we won’t use this option definitely.
  
  curl --request GET --url https://datapower/orders/sb/orders/order \ --header 'accept: application/json' \ --header 'x-ibm-client-secret: REPLACE_WITH_UR_CLIENT_SECRET' \ --header 'x-ibm-client-id: REPLACE_WITH_UR_CLIENT_ID' -v --insecure

  1 2 3 4

  curl --request GET --url https://datapower/orders/sb/orders/order \    --header 'accept: application/json' \    --header 'x-ibm-client-secret: REPLACE_WITH_UR_CLIENT_SECRET' \    --header 'x-ibm-client-id: REPLACE_WITH_UR_CLIENT_ID' -v --insecure

Conclusion

Well, that brings me to the end of this tutorial. I hope that this helps you in your journey of API Connect learning. Feel free to comment below with your issues, problems, questions should you have one!! Happy learning and I will see you soon with some more tutorials in API Connect.