First Look: InterSystems API Manager
This First Look introduces you to InterSystems API Manager (IAM), explains how it works, and gets you started for exploring its capabilities on your own instance.
How Does InterSystems API Manager Work?
InterSystems API Manager is a component of InterSystems IRIS® data platform that allows you to take advantage of microservices and APIs that are either exposed or consumed by your InterSystems IRIS applications. Acting as an API gateway between your InterSystems IRIS servers and applications, it gives you the ability to more effectively monitor and control the traffic of calls between your server-side APIs and your client-side applications.
To learn more about InterSystems API Manager, you can view this overview video.
InterSystems API Manager is installed separately from an instance of InterSystems IRIS. To get your own installation kit of IAM, you can download it from the InterSystems WRC Software Distribution site, or reach out to your InterSystems sales engineer. The installation package includes a script (iam-setup) for setting up IAM and connecting it with your instance of InterSystems IRIS.
This exercise assumes that you have instances of InterSystems IRIS and IAM and have run the setup scripts to connect them.
Set up the REST API in InterSystems IRIS
From the GitHub repository at https://github.com/intersystems/FirstLook-IAM, import the following into InterSystems IRIS:
/cls/cmAPI includes three class files generated using the API management service as well as a coffeemaker object definition:
To import, open the InterSystems IRIS Management Portal and navigate to the Classes page (System Explorer > Classes); if you are not in the USER namespace, use the selectors on the left to change to it, as shown in the following illustration:
Select the four classes listed above and click Import. This imports the REST API into InterSystems IRIS, along with the corresponding classes that will be used by applications to access the set of coffeemakers stored in the database.
Import by going to the Management Portal and clicking Globals > Import > My Local Machine. Find coffeemakers.gof. Import to the schema User.cmAPI.coffeemaker.
Next, set up a Web Application pointing to the REST classes you just imported. Web application layers provide an additional opportunity for customization and security. In the Management Portal, select System Administration > Security > Applications > Web Applications. Click Create New Web Application and fill out the following settings:
Enable Application: selected
Dispatch Class: cmAPI.disp
Allowed Authentication Methods: Unauthenticated, Password
Create a Service in IAM for your REST API
As you saw in the IAM overview video, there are three major components at play within the IAM workflow —Consumers, Routes, and Services. Services in IAM are created for your APIs that exist within InterSystems IRIS. In this case, we will create a service for your Coffeemaker API.
Your IAM package that you downloaded from the WRC also includes a script (iam-test) for setting up a sample service and route. We will be achieving a similar result, using the IAM portal, to add your Coffeemakers service.
Within IAM, navigate to the default workspace, then API Gateway > Services. Click New Service. The ensuing form will ask for a number of properties about your service. Fill in the values as follows:
retries: 5 [this is the default]
connect_timeout: 60000 [this is the default]
write_timeout: 60000 [this is the default]
read_timeout: 60000 [this is the default]
host: [insert the IP address of your InterSystems IRIS instance, which may be localhost]
port: [insert the webserver port of your instance, by default 52773, or if the instance is in a container, the host port you have mapped to the webserver port]
url: not required
Once your service is created, you will need to create a route that maps API calls to the appropriate service.
Create a Route in IAM
When creating a route, you will need to obtain the hexadecimal ID from the CoffemakerService that you created in the last step. Take note of this ID. Then, navigate to API Gateway > Routes and click New Route. The ensuing form will ask for a number of properties about your route. Fill in the values as follows:
methods: GET, POST, PUT, DELETE
hosts: Can be left empty
strip_path: Checked [this is the default]
preserve_host: Unchecked [this is the default]
service.id: [copy the hexademical id from the CoffeemakerService you created in the last step]
Once your route is created, you will test your route and service by making a simple API call from a REST client.
Call Your API from a REST Client
Using a REST client — Postman or Advanced REST Client from Google Chrome will work here — make a simple API call to your Coffeemakers API within InterSystems IRIS. To do this, create a request URL that includes the IP address and port number of your IAM instance, as well as the path of your service and the requested endpoint. Be sure to authorize your request with a username and password. An example is shown below; note that by default, IAM handles proxy requests on port 8000. For example:
Once you have successfully made this call, you can navigate back to your IAM Dashboard to see the statistics and other information from the call that was made. From this dashboard, you can see a number of different sets of information that will help you with monitoring and controlling traffic between client applications and your services within InterSystems IRIS.
Add a Rate Limiting Plugin
Effectively monitoring your API traffic is beneficial, but only to the extent that you use that information to appropriately control and optimize your flow of traffic. IAM enables you to use a number of different plugins to boost your ability to control traffic flow between clients and APIs.
Within IAM, navigate to API Gateway > Plugins and click New Plugin. In the Traffic Control category, find the Rate Limiting plugin and click Enable.
On the configuration screen for this plugin, we will simply enter values into two fields: route_id and config.minute. For route_id, you will need to copy the ID of the route you created. To find this, you will need to look at your routes again (API Gateway > Routes).
In the config.minute field, enter 5. This will limit the rate of calls accordingly, meaning that clients can only access the API along this specified route a maximum of 5 times per minute. Click Create when you have finished entering fields, and your plugin has been enabled.
You can test this rate limiting plugin by returning to your REST client and making sample calls.
Add Your REST Specification to IAM
The best practice approach for REST development is specification-first, so it is likely that you already have your REST specification on hand. For this exercise, you can download the JSON specification from the spec folder in the GitHub repository:
For more information on documenting and managing your REST API specifications, read Discovering and Documenting REST APIs in Creating REST Services.
Once downloaded, you are able to add your specification to IAM. Within IAM, navigate to Dev Portal > Specs. Here, you can click the +Add Spec button, as shown in the screenshot below.
By creating a name for your spec, and pasting its contents into the editor, you will be able to add the specification to IAM so that developers can easily access it in your developer portal. In your developer portal, you can see all API specs within the Documentation tab. Below is an example of what developers will see when viewing an API specification. This example is using the Swagger Petstore API, but once added, your Coffeemaker specification should be accessible in the same way.
Learn More About InterSystems API Manager
InterSystems provides several resources to learn more about IAM: