Experience & feedback from online course "Hands-On with InterSystems API Manager for Developers" 

With my basic knowledge of Docker container and REST API, I would like to have my first try on using InterSystems API manager to take control of APIs and microservices. I have completed this online course using my local IRIS instance as host (Windows OS) and IAM running on a Linux VM (guest). 

Firstly, I will introduce InterSystems API Manager (IAM), then explain the steps for setting up my local environment and lastly walk through the course chapters.

Introduction

Nowadays API management is very important by taking the advantages of easy deployment, provided a entralized UI portal for managing, monitoring, and securing API traffic.

InterSystems API Manager (IAM)  takes control of APIs and microservices consumed and exposed by IRIS application. It is an API gateway between downstream and upstream systems and also have a visual trace way to find out what APIs are called, how often they have been called and who called them. 

Benefits of using IAM:

• Monitor HTTP-Based APIs
• Control  traffic. 
• Protect API safety via using security mechanism. 
• Easy to use for new onboarding developer.

Setup IAM

What I have installed before start setting up the IAM

• Windows (IRIS Instance installed)
• Linux VM (Docker installed)

Enable InterSystems IRIS Instance to use IAM

1. Open management portal of IRIS instance, enable IAM.

1. 1. In the Management Portal, select System Administration > Security > Users and select the IAM user
   2. Click the Password radio button
   3. Enter and confirm a password for the IAM user
   4. Select the User enabled check box
   5. Select Save
2. Enable the IAM web application (Make sure your IRIS license specifies "API Management" 

1. 1. In the Management Portal select System Administration > Security > Applications > Web Applications and select the "/api/iam" 
   2. Select the Enable Application check box
   3. Select Save

Download and extract the IAM installation files

1. Download the IAM installation kit from WRC inside Linux environment
2. Extract the tar files (Do not extract iam-image.tar, because this is the IAM docker image)

Set up & Start IAM 

In this step, I have used ROOT user as I was getting errors such as "Cannot load the Manage Portal properly" or setup script was not passing the environment variable value to docker-compose.yaml file when I used sudo with my Linux user. One workaround to the latter was to use "sudo -E" to pass the environment variables.

1. Open terminal executing the command "docker load -i iam_image.tar" in the directory where you extracted the IAM archive.
2. Execute "source ./scripts/iam-setup.sh" in current directory or "source ./iam-setup.sh" under "scripts" folder.
   1. Enter exact IAM image name and the repository name from https://containers.intersystems.com/contents For example: intersystems/iam:3.0.2.0-2 (This step is required, otherwise you will receive an error about repository authentication fail once you do "docker compose")
   2. Enter exact IP address of host machine (You can find out the IPV4 spec under Windows setting, do not enter localhost or 127.0.0.1)  
   3. Enter port number of IRIS instance under Windows OS, for example 52773 
   4. Enter and re-enter the password of IAM user
3. Inside the "scripts" directory, make sure run the "iam-test.sh" to test connection
4. Inside the "scripts" directory execute "docker compose up -d" to start the IAM
5. Start IAM portal on Linux by going to: http://localhost:8002/overview

If you cannot ping the host address using VM, check Windows Firewall- Advanced Settings - Inbound Rules. Enable  File and Printer Sharing (Echo Request - ICMPv4-In) Profile: Private, Public

Test IAM

Inside of installation kit, you will find a script called "iam-test.sh" under scripts directory. 

Type and Run "./iam-test.sh" to start testing the connection between IAM and IRIS instance. 

Note: If the test result says "Error creating service. HTTP Status Code:000 or Error creating service. HTTP Status Code:409", check the docker status, if it is healthy but still not working shut down the container and run docker compose again, from my experience, this may happen after you have paused the VM.

For more information you can find here the IAM setup documentation: https://docs.intersystems.com/components/csp/docbook/DocBook.UI.Page.cls?KEY=CIAM3.0_install#CIAM3.0_install_setupIAM

Hands on exercise: https://learning.intersystems.com/course/view.php?name=IAMExercise

Course Chapters

After I have done this exercise, I have concluded 3 main chapters that I would like to share:

• Setting Up Services
• Setting Up Routes
• Setting Consumers and Plugins

Before I started using IAM, this exercise asked me to make a REST request using GET method, this HTTP request is from client server directly point to the endpoint which is a web application built on an IRIS instance. 

For the next steps this exercise showed me how to set up services that API request is forward to and route that analyses the inbound request and then allocates to the best suited API.

Setting up Services and Routers

What is a Service? 

A service is configured to connect API Manager to InterSystems IRIS; you usually have one service per REST service or web application within InterSystems IRIS. For example, if you have a web application with the base path /rest/coffeemakerapp, you will configure one service within API Manager for this URL. Services are usually defined before routes.

What is a Route?

A route defines what will be called by client applications to InterSystems API Manager. You usually define a service before a route because the interface allows you to easily create the corresponding routes directly from a defined service. Routes are typically simplified versions of the paths within InterSystems IRIS. In the following example, you will create routes for /test, /coffeemakers, /coffeemaker and /newcoffeemaker. The more specific your routes, the more control you have over your APIs within API Manager, both in viewing metrics and in adding plugins to specific routes.

Create a Service:

1. Go to IAM Admin Portal select Services tab
2. Click New Service and name it
3. Select Add using URL
4. Provide the base URL which is the exact URL path that you specified in Web Application, and double check the instance ip address is correct (do not use localhost or 127.0.0.1)

Create a Route:

1. Scroll down on the summary of the service and click Add a Route
2. Specify Name, Protocols, Path(s)
3. The Service field should be automatically generated with the service details
4. The exercise required us to unselect Strip Path under Advanced Fields, If selected, this removes the path when sending the request to InterSystems IRIS, which is an important element to connect to the InterSystems IRIS endpoint.

After the Service and Route have been created, you can use a REST client such as Postman, to send a request directly to IAM and receive a "200 ok" response for example: GET http://10.0.0.1:8000/test (/test is the Route created).

Note: in my case, the URL of HTTP request should match the Linux VM IP address, you can find the IP address via Settings-Network or execute " ifconfig" command in terminal. 

Open the IAM Admin Portal, you will see the request to display all coffeemakers was successfully logged, from REST client to IAM.

Even with the basic CRUD requests, instead of sending HTTP request directly to IRIS web application, using IAM brings you a visual representation to take control of APIs and maintain endpoint security.

Using Plugins

One benefits of using IAM is that it has many plugins available, such as Rate Limiting plugin to help with throttling, ACL plugin, OAuth2.0 plugin. In my case I will share my experience of enabling basic-auth and create a consumer.

Enable basic-auth Plugin

1. Go to IAM Admin Portal select Plugins tab
2. Click New Plugin > Basic Authentication > Create

Create a IRIS user that you need for Basic Auth 

1. Open IRIS management portal 
2. Go to System Administration > Security > Users > Create New User
3. Set user Name, Password
4. Others leave it blank then click Save, in my case I have created a user called "CoffeeManager"

Create a consumer and set up it credentials

1. Go to IAM Admin Portal select Consumers tab
2. Click New Consumer > Enter CoffeeManger (in my case) under Username > Create
3. Go to CoffeeManager information page > Credentials > New Basic Auth Credential
4. Use the user credentials that we created in IRIS instance > Save

Now we have done all the requirements in order to make basic-auth plugin functional

Send a HTTP request using Basic Auth with "CoffeeManager" credential we created on the last step 

Go to CoffeeManager information page > Activity, you will see there is a successful request have been lodged

Conclusion

In conclusion, I have started by introducing what is InterSystems API Manager (IAM), and its benefits. Followed by a simple walkthrough of how to set up IAM in a Linux VM and how to use IAM by implementing its basic functions, create services and routes, enable plugins and consumers.

If you have any questions and comments, please feel free to reach out.

Have fun and enjoy with IAM!