We recently released InterSystems API Manager (IAM), a new component of the InterSystems IRIS Data Platform that provides visibility, control and management of traffic to/from the web API within the IT infrastructure.
In this article, I'll show you how to set up IAM and demonstrate some of the many options available to you with IAM. InterSystems API Manager allows you to:
- Monitor the API, understand who is using the API, which APIs are the most popular, and which ones need improvement.
- Control who uses the API and restrict API usage from simple access restrictions to request-based restrictions - you have custom control and can quickly respond to changes in API consumption patterns.
- Secure APIs with centralized security mechanisms such as OAuth2.0, LDAP, or Key Token Authentication.
- Simplify the work of third-party developers and provide them with a superior API experience by opening a dedicated developer portal.
- Scale the API and ensure minimal latency in response.
API management is essential for the transition to SOA or microservice architecture, facilitating the integration between individual (micro)services, making them available to all external and internal consumers. As a result, new APIs become easier to create, maintain, and consume.
If you are already using InterSystems IRIS, you can add the IAM option to your license. The IAM option is free for InterSystems IRIS customers, but you must request a new license key from InterSystems to start using IAM.
If you are not yet using InterSystems IRIS and only plan to try InterSystems API Manager, please contact InterSystems.
Getting started and installation
InterSystems customers can download the IAM distribution from the website section "Software Distribution" and run as a Docker container. Minimum system requirements:
- 17.04.0 +.
- 1.12.0 +.
- InterSystems IRIS 2019.1.1+.
Initially, you need to download the Docker image (Important! The archive with WRC is not a Docker image, you need to unpack it, inside the Docker image):
docker load -i iam_image.tarThis command will make the IAM image available for later use on your server. IAM runs as a standalone container so you can scale it independently of InterSystems IRIS. Running IAM requires access to InterSystems IRIS to download a license.
Set up InterSystems IRIS:
- Turn on the web app
/api/IAM - Enable user
IAM - Change user password
IAM
Now let's start the IAM container. In the archive you will find scripts iam-setup for Windows and Unix (and Mac). These scripts will help you set up your environment variables correctly, allowing the IAM container to establish a connection with InterSystems IRIS. Here is an example of how the script works on a Mac:
source ./iam-setup.sh
Welcome to the InterSystems IRIS and InterSystems API Manager (IAM) setup script.
This script sets the ISC_IRIS_URL environment variable that is used by the IAM container to get the IAM license key from InterSystems IRIS.
Enter the full image repository, name and tag for your IAM docker image: intersystems/iam:0.34-1-1
Enter the IP address for your InterSystems IRIS instance. The IP address has to be accessible from within the IAM container, therefore, do not use "localhost" or "127.0.0.1" if IRIS is running on your local machine. Instead use the public IP address of your local machine. If IRIS is running in a container, use the public IP address of the host environment, not the IP address of the IRIS container. xxx.xxx.xxx.xxx
Enter the web server port for your InterSystems IRIS instance: 52773
Enter the password for the IAM user for your InterSystems IRIS instance:
Re-enter your password:
Your inputs are:
Full image repository, name and tag for your IAM docker image: intersystems/iam:0.34-1-1
IP address for your InterSystems IRIS instance: xxx.xxx.xxx.xxx
Web server port for your InterSystems IRIS instance: 52773
Would you like to continue with these inputs (y/n)? y
Getting IAM license using your inputs...
Successfully got IAM license!
The ISC_IRIS_URL environment variable was set to: http://IAM:****************@xxx.xxx.xxx.xxx:52773/api/iam/license
WARNING: The environment variable is set for this shell only!
To start the services, run the following command in the top level directory: docker-compose up -d
To stop the services, run the following command in the top level directory: docker-compose down
URL for the IAM Manager portal: http://localhost:8002As you can see, the full image name, IP address, InterSystems IRIS port, and password for the IAM user are all you need to get started.
Instead of running the script, you can set environment variables manually:
ISC_IAM_IMAGE=intersystems/iam:0.34-1-1
ISC_IRIS_URL=http://IAM:<PASS>@<IP>:<PORT>/api/iam/licenseRelease
Now let's start IAM by running the command:
docker-compose up -dThis command organizes the IAM containers and ensures that everything is running correctly. The status of containers is checked using the command:
docker psOpen the admin interface in your browser localhost:8002.
So far, it's empty because it's a brand new node. Let's change that. IAM supports the concept of workspaces to separate APIs into modules and/or commands. Go to the "default" workspace which we will use for our experiments.
The number of requests for this workspace is still zero, but you'll get an idea of the basic IAM concepts in the menu on the left. The first two elements, Services and Routes, are the most important:
- Service (Service) - API to which we want to provide access to consumers. Thus, the REST API in InterSystems IRIS is a Service, as is, for example, the Google API if you choose to use it.
- The Route decides which Service incoming requests should be redirected to. Each Route has a certain set of conditions, and if they are met, the request is sent to the corresponding Service. For example, a Route can match an IP, sender domain, HTTP methods, parts of a URI, or a combination of these examples.
Service
Let's create an InterSystems IRIS Service, with the following values:
Field
Value
Description
name
iris
Service name
host
IP
Host or ip of the InterSystems IRIS server
port
52773
InterSystems IRIS server web port
path
/api/atelier
root path
protocol
http
Protocol
Leave the rest of the values as default. Click the button Create and write down the ID of the created Service.
Route
Now let's create a route:
Field
Value
Description
path
/api/atelier
root path
protocol
http
Protocol
service.id
guide from 3
Service (ID from previous step)
Leave the rest of the values as default. Click the button Create and write down the ID of the created Route. By default, IAM listens for incoming requests on port 8000. Requests sent to http://localhost:8000 and starting with /api/atelier are redirected to InterSystems IRIS.
The test is
Let's try to create a request in a REST client (I use ).
Send a GET request to http://localhost:8000/api/atelier/ (do not forget / at the end) and get a response from InterSystems IRIS. Each request goes through IAM which collects metrics:
- HTTP status code.
- Delay.
- Monitoring (if configured).
I made a few more requests (including two requests to non-existent endpoints like /api/atelier/est/), the results are immediately visible on the dashboard:
Working with plugins
Now that we have our Route set up, we can manage our API. We can add features that complement our service.
The most common way to change the behavior of an API is to add a plugin. Plugins isolate individual functionality and can be connected to IAM both globally and only to individual entities such as a User (a group of users), a Service, or a Route. We'll start by adding the Rate Limiting plugin to the Route. To establish a connection between the plug-in and the route, we need a unique identifier (ID) of the route.
Request limit
Click Plugins in the left sidebar menu. You see all active plugins on this screen, but since this IAM server is new, there are no active plugins yet. Therefore, proceed to the next step by clicking "New Plugin".
The plugin we need is in the "Traffic Control" category and is called "Rate Limiting". Select it. There are quite a few settings you can set here, but we only care about two fields:
Field
Value
Description
route_id
ID
Route ID
config.minute
5
Number of requests per minute
That's all. The plugin is configured and active. Note that we can select different time intervals such as minute, hour or day. The settings can be combined (for example, 1000 requests per hour and 100 requests per minute). I chose minutes as it makes it easy to test the plugin.
If you send the same request to Postman again, you will see that the response is returned with 2 additional headers:
- XRateLimit-Limit-minute: 5
- XRateLimit-Remaining-minute: 4
This tells the client that it can make up to 5 requests per minute and can make 4 more requests in the current timeslot.
If you make the same request over and over again, you will eventually run out of available quota and instead receive an HTTP 429 status code with the following response body:
Please wait a minute and you will be able to send requests again.
This is a convenient mechanism that allows you to:
- Protect the backend from load spikes.
- Tell clients how many requests they can make.
- Monetize the API.
You can set values for different time intervals and thus smooth out API traffic for a certain period of time. Let's say you allow 600 requests per hour for a specific Route. The average is 10 requests per minute. But nothing prevents the client from completing all 600 requests in the first minute of the hour. Maybe this is what is needed. You may want to achieve a more even load over the course of an hour. By setting the field value config.minute set to 20, you ensure that your users make no more than 20 requests per minute and 600 requests per hour. This allows small spikes in the minute interval compared to a fully averaged 10 requests per minute, but users cannot use the hourly quota for one minute. Now they will need at least 30 minutes to use all their requests. Clients will receive additional headers for each given time interval, for example:
HTTP Header
Value
X-RateLimit-Limit-hour
600
X-RateLimit-Remaining-hour
595
X-RateLimit-Limit-minute
20
X-RateLimit-Remaining-minute
16
Of course, there are many different ways to set up query limits, depending on what you want to achieve.
Conclusions
On this I will end, I think the material is quite enough for the first article about InterSystems API Manager. We only used one of over 40 plugins. There are many more interesting things you can do with IAM:
- Add a central authentication mechanism for all your APIs.
- Scale the load with a load balancer across multiple Services.
- Add new functionality and bug fixes for test audiences before a full update.
- Provide internal and external developers with a dedicated web portal that documents all APIs.
- Cache requests to reduce response time and reduce load on the system backend.
references
Webinar
We invite you to the webinar "API Management with InterSystems API Management", which will be held on November 21 at 10:00 Moscow time (GMT + 3).
InterSystems API Manager (IAM) is a new component of InterSystems IRIS Data Platform that provides monitoring, control and management of traffic to/from web API within the IT infrastructure. At the webinar, we will demonstrate the key features of InterSystems API Management:
- API traffic monitoring tools.
- API traffic control tools, including bandwidth control, limiting the number of API calls, maintaining lists of allowed and blocked lists of IP addresses, etc.
- API Security Configuration Tools.
- Developer Portal for publishing interactive API documentation.
- Single point of access to the API.
The webinar is intended for architects, developers and system administrators.
!
Source: habr.com