With the API Connect service, you can easily serve your APIs over a secure developer platform. Traditionally, developers prepare their APIs for a web service, then implement or develop another service for serving APIs in a secure way. API Connect allows developers to focus on APIs while it does the rest of the work.
API connect can:
- Categorize APIs
- Limit APIs with certain restrictions
- Allow identifying different roles on APIs
- Allow managing different web services together
- Allow developers to version APIs
- Give a graphical programming interface for manipulation
- Create sample code examples for different languages and tools like cURL, Node.js, and Python
This tutorial explains how to:
- Create a Node.js web app with boilerplate code
- Use REST APIs over Node.js
- Serve your Node.js REST APIs with API Connect
In order to use this how-to, you need the following prerequisites:
- IBM Cloud account – sign up if you don’t have an account yet
- A provisioned API Connect instance
- A provisioned Node.js Web Starter instance
- The setup of the Node.js Web Starter shouldn’t take longer than 10 minutes.
- The setup of the API Connect shouldn’t take longer than 10 minutes.
- Understanding how to use the Node.js Web Starter with API Connect shouldn’t take longer than 15 minutes.
Creating Node.js Web Starter boilerplate
Let’s start our how-to with preparing an example web application. We will use Node.js Web Starter boilerplate for that purpose. Open the IBM Cloud catalog and type node.js in the search bar. You can see filtered services like in the figure below.
Under the Boilerplates section you will see Node.js Cloudant DB Web Starter which is placed right in the upper figure. Click on that boilerplate. After that we will redirect to the service creation page. Which can be seen in the figure below.
Fill the empty sections with the unique values then click the big blue Create button which is placed right bottom corner. It will redirect you to service instance Getting started page. Now click to the Logs section from the menu which is placed left side of the page. And wait until the seeing Container became healthy message. After that, you can click the instance URL to see your application home page.
We need to upload a sample file for seeing meaningful REST API call result from our web app. Go to your web app homepage, click the Choose File button and select a sample image file for upload. Then click the Upload button. When the upload was finished, you would be able to see your example file on the list.
Details of REST API
We are ready to test our REST API. But before that, I want to dig a little bit more on that topic. As far as here we even didn’t write a single piece of code. On the boilerplate everything is ready for us. We will just use that. For example, when we click the upload, it triggered a api call in the background. After the upload finished, we would be able to see our uploaded file on the list which is a another api call.
Long in short this boilerplate contains lots of api calls which are binded to the route for performing upload and showing them to the users. In this how to we will focus on the /api/favorites/attach route.
If you want to see all api call of that boilerplate, feel free to download codes from link. You can find everything you need under the app.js file.
Testing Node.js REST API
Now we let’s test our REST API. Copy your Node.js instance’s url from browser. Then add this “/api/favorites/attach” string to at the end of it. Now you should have something like this: “cagataytanyildiz.mybluemix.net/api/favorites/attach”. Now go to that url and you should see some json from your database.
If everything is correct we can go through API Connect part.
Configuring Catalog on API Connect
Before using API Connect we need to understand it’s background. API Connect has some hierarchy for collecting, creating and serving APIs to real world. You can see API Connect Hierarchy on the figure below.
As you can see from the figure, you need to use Catalogs for serving APIs. In this how-to we will use example API Connect catalog for serving our API but you can also create your own Catalog. Let’s begin! Go through your API Connect instance and click on it.
Adding API on API Connect
Open your API Connect , use >> button which placed next to the Dashboard button, then go to Drafts and go to API tab. Click ADD button before creating API, expand Additional Properties and select Identify Using with Client ID under the Security section.
After that, go to Paths section and add “/files” path for your web service.
Now we need to bind our web service to API. For this reason go to Assemble section and click on the invoke diagram. When you click the invoke diagram, you need to enter your web service url (ex: cagataytanyildiz-node-red.mybluemix.net/sensor-data) and you need to select request type which is GET for this scenario and lastly you need to select Cache Type which is No Cache.
After adding service to your API. You need to “Save” and Validate your API design. You can find Save button right side of the page. Click Save button first then after getting success message pop up click Validate button which is placed near Save button. We do not expect any error message on this section if you get any feel free to reach me.
Adding Product on API Connect
After preparing API we need to prepare Product as well. Let’s turn back to Drafts page. But this time we will add Product from Product tab.
After all these settings click to Save button for saving all these steps. You can find Save button right side of the page. Then go to Design section and click to Save first then Validate button next to save button.
We don’t expect any error message on these stages. If you get any error feel free to reach me.
Now we need to add our API to our Product. Go to your catalog, then click onto your product and go to API section and bind your product with your API. Click on the Add API button which is placed right upper sight of the APIs section and select the saved API.
After that click to Save button an then Stage button which is placed near to Save. After staging our product we should wait a few minutes then we should publish it over Dashboard. Click on >> , select Dashboard, then the Sandbox catalog. Then select the staged product and publish it using the three dots menu item.
Testing API on API Connect
Now we can test our API. Turn back to your API Page through Drafts section open Assemble section and click play button which placed next to search bar.
You should be able to see your path under Operation dropdown.
Select your get operation from dropdown menu. Click to invoke button. Status code should be 200 OK.
Creating Developer Portal for Serving Your APIs
If you noticed that when you invoking a call we send a clientId variable within the header. Which means only the subscribed users can send receive meaningful data from your api otherwise they will get unauthorized access response.
Let’s go to the Catalog first. Then click on the Sandbox. It will redirect you to homepage of the catalog select Settings from upper bar. You will see Portal section which is placed left side of the Settings page.
Select IBM Developer Portal from dropdown menu. After a while it will create a portal for your catalog then you can give these portal’s url to your subscribers. Before consuming your APIs, they need to sign up to your portal and get client id over the developer portal.
Now you can give your developer portal address to anyone which you want to share your API. You can also limit, organize, manipulate your web application service’s API over API Connect.
You can now connect a lot of web services, like Node.js, to your API Connect platform. Additionally, you can merge your web services over the API Connect. In this how-to, we just simply created one web service and bind it to API Connect. In the end we expect from you to learn these outcomes:
- Creating Node.js webservice
- Creating and publishing API with API Connect
- Creating developer portal for API Connect