InterSystems Independent Components Home > InterSystems API Manager (IAM) Home > Version 0.34-1 Home > Getting Started with API Manager

5-Minute Quickstart

Introduction

In this section, you'll learn how to get InterSystems API Manager (IAM) running and how to manage your IAM instance. First, you'll start IAM to give you access to the RESTful administration API and the easy-to-use IAM Manager, through which you'll manage your APIs, consumers, and more. Configuration changes made through the administration API and IAM Manager are stored in IAM's datastore.

The API Manager is distributed as a compressed tarball archive. Once you uncompress it and extract the files, you should have:

  • IAM Docker image, iam-image.tar — do not extract the files from this archive.
  • scripts directory with:
    • docker-compose.yml script to start and stop IAM
    • unix and win directories with UNIX and Windows scripts to setup and test IAM — these optional scripts provide an easy way to start and test IAM. The startup scripts set up the environment variables in the current shell used by IAM. If you do not use the scripts, you need to define these variables some other way. The variables are described in the next section.
    • PaxHeader directory
  • readme.txt file with brief instructions for starting IAM. This topic is based on the readme but provides some additional information.
  • EULA files with terms and conditions

Set Up IAM

To setup IAM, follow these steps:

  1. Ensure that your system has the required prerequisites:
    1. Install Docker if your system does not already have it. See Running InterSystems Products in Containers for a brief introduction to containers and Docker.
    2. Install Docker-compose if your system does not already have it.
    3. On UNIX systems, install the curl utility. The UNIX script files to start and test IAM use curl. The Windows script file uses PowerShell to invoke web requests and does not require curl.
    4. Ensure that you have a running Version 2019.2 or later InterSystems IRIS or InterSystems IRIS for Health system. If you are using Version 2019.2, contact your InterSystems sales engineer or the InterSystems Worldwide Response Center (WRC) to obtain the correct InterSystems build and license file that supports IAM.
    5. Download the tarball file with the IAM software and setup script files from the InterSystems download site.
    6. Extract the files from the distribution archive.
  2. Enable the IAM user and web application on the InterSystems IRIS instance. The purpose of the IAM user is to allow the setup script to get a copy of of the IAM license from the instance of InterSystems IRIS; the IAM has very limited privileges and is only used to access the IAM license information. In the Management Portal for the instance of InterSystems IRIS, InterSystems IRIS for Health, or HealthShare Health Connect:
    1. Select System Administration > Security > Applications > Web Applications and select the /api/iam web application.
    2. Select the Enable Application check box.
    3. Select Save.
    4. Select System Administration > Security > Users and select the IAM user.
    5. Enter a new password and select the User enabled check box.
    6. Select Save.
  3. Execute the following command to create the container and load the IAM image:
    docker load -i iam_image.tar
  4. If you want to secure the IAM administrative API, you must add an authentication plug-in to IAM. You should set a password for the IAM Super Admin account by defining the environment variable KONG_PASSWORD in the container before running the setup script. If this password is defined in the container, IAM creates a user, kong_admin, and specifies the value as the password for an account that can be used to log in to IAM Manager or to make Admin API requests when RBAC is enabled.
  5. Run the setup script and start IAM:
    1. Run the IAM setup script. If you are running the script on UNIX, you must ensure that the script is run in the same process, not a subprocess by using the bash source command or the dot command.
      In a Windows PowerShell, enter:
      .\scripts\win\iam-setup.ps1
      In a UNIX bash shell, enter:
      source ./scripts/unix/iam-setup.sh
      Or in another UNIX shell, enter the equivalent dot command:
      . ./scripts/unix/iam-setup.sh
    2. Enter the full image repository, name and tag for your IAM docker image. For example, it could be intersystems/iam:0.34-1-1
    3. Enter the IP address for your InterSystems IRIS instance. If your instance is on your local machine, please use your local IP address, not "localhost". To avoid any DNS issues, use the numeric form of the IP address.
    4. Enter the web server port for your InterSystems IRIS instance.
    5. Enter the password for the IAM user for your InterSystems IRIS instance.
    6. Re-enter the password.
    7. Confirm your entries.

This script sets the two environment variables required by the docker-compose file.

Environment Variables

The following environment variables are used by the docker-compose file and by IAM. These are set by the startup script. If you do not use the startup script, you must define these variables.

  • ISC_IAM_IMAGE — Contains the respository, name, and tag of the IAM docker image. The docker-compose file uses this variable to access the docker image. The value has the format:
    repository/name:tag
  • ISC_IRIS_URL — The docker-compose file defines this environment variable in the container so that IAM can access the InterSystems IRIS instance to get the IAM license. The value has the format:
    http://IAM:password@ip-address:port-number/api/iam/license

These environment variables are defined in the shell and allow the docker-compose file to access the IAM container and the InterSystems IRIS image. If you are not in the shell where you executed the setup script, these environment variables are not defined. You can either re-run the script or define them in another way.

By default IAM listens on the following ports:

  • :8000 on which IAM listens for incoming HTTP traffic from your clients, and forwards it to your upstream services.
  • :8443 on which IAM listens for incoming HTTPS traffic. This port has a similar behavior as the :8000 port, except that it expects HTTPS traffic only. This port can be disabled via the configuration file.
  • :8003 on which IAM listens for IAM Dev Portal GUI traffic — if the Dev Portal is enabled.
  • :8004 on which IAM listens for IAM Dev Portal /files traffic — if the Dev Portal is enabled.
  • :8001 on which the Admin API listens.
  • :8444 on which the Admin API listens for HTTPS traffic.
  • :8002 on which IAM Manager listens.
  • :8445 on which IAM Manager listens for HTTPS traffic.

Start and Test IAM

To start IAM, navigate to the /scripts directory with the docker-compose.yml file and execute the following command to start IAM:

docker-compose up -d

You can access the user interface at http://localhost:8002

To test the IAM setup, navigate to the directory with the scripts for the operating system you are running (scripts/win or scripts/unix), and run the iam-test script. This script sets up a route and a service in IAM and allows you to check connectivity with your InterSystems IRIS instance.

Stop IAM

To stop the IAM container navigate to the directory with the docker-compose.yml file and execute the following command:

docker-compose down

Note that you need to be in the same shell as the one that you ran the setup scripts or you need to define the ISC_IAM_IMAGE and ISC_IRIS_URL environment variables.

Restart IAM

To restart the IAM container, navigate to the /scripts directory with the docker-compose.yml file and execute the following command to start IAM:

docker-compose up -d

Note that you need to be in the same shell as the one that you ran the setup scripts or you need to define the ISC_IAM_IMAGE and ISC_IRIS_URL environment variables.

Next Steps

Now that you have IAM running you can interact with the Admin API and IAM Manager.

To begin, go to Configuring your Service.