Skip to main content

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.

Try it!

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. This exercise is shown using IAM version 2.3.

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:

  1. /cls/cmAPI includes three class files generated using the API management service as well as a coffeemaker object definition:

    • impl.cls

    • disp.cls

    • spec.cls

    • coffeemaker.cls

    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:

    The Management Portal Classes page includes a filter option labeled lookin. In this image, lookin is set to Namespace: USER.

    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.

  2. /gbl/coffeemakers.gof.

    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:

  • Name: /rest/coffeemakerapp

  • Namespace: USER

  • Enable Application: selected

  • Enable: REST

  • 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. If you ran the script, you will be able to view the test-iris service.

The iam-test script creates a service called test-iris.

We will be achieving a similar result, using the IAM portal, to add your Coffeemakers service.

Start the IAM management portal by entering the URL for the portal specified in the iam-setup.sh script that started IAM. By default, the URL is:

http://localhost:8002

Select the default Workspace. If the default workspace is not visible and the management portal seems empty, it is possible that you did not enter the exact URL as defined by iam-setup.sh.

Select Services in API Gateway and select New Service. Fill in the form as follows:

  • Name: CoffeemakerService

  • Select Add using Protocol, Host and Path

  • Protocol: http

  • Host: [insert the IP address of your InterSystems IRIS instance. To avoid DNS issues, use the numeric form of the IP address. ]

  • Path: /rest/coffeemakerapp

  • 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]

  • Do not select “View 6 Advanced Fields”.

  • Select Create.

Once your service is created, you will be viewing the service and will need to create a route.

Create a Route in IAM

When you are viewing the service, select “Add a Route”. Fill in the form as follows:

  • Sevice: this field is correctly initialized with the hexadecimal ID of the service.

  • Name: can be left empty

  • Protocols: http

  • Hosts: can be left empty

  • Methods: GET, POST, PUT, DELETE

  • Paths: select “+ Add Path” and enter /rest/coffeemakerapp

  • Headers: can be left empty

  • HTTPS Redirect Status Code: 426 (this is the default)

  • Tags: can be left empty

  • Do not select “View 4 Advanced Fields”.

  • Select Create.

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:

POST http://localhost:8000/rest/coffeemakerapp/coffeemakers

The Postman client displays the successful POST request; the response body contains a JSON array of coffee maker information.

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.

In the IAM management portal, select Plugins in API Gateway and select New Plugin. In the Traffic Control category, find the Rate Limiting plugin and select Enable.

The Rate Limiting plugin allows you to rate-limit how many HTTP requests a developer can make.

On the configuration screen for this plugin:

  • Select Scoped.

  • In Service select the CoffeeMakerService.

  • Leave most of the other fields with their default value, but set Config.Limit By to Service and Config.Minute to 5. This will limit all consumers to 5 calls per minute to all routes in the service.

  • Select Create.

You can test this rate limiting plugin by returning to your REST client and making sample calls. After the client exceeds the limit, it will get a 429 return error with an “API rate limit exceeded” message

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 use the swagger_100419.json file in the spec directory when you downloaded the FirstLook-IAM repository from github. You can also download the JSON specification directly from the spec folder in the GitHub repository

https://github.com/intersystems/FirstLook-IAM/blob/master/spec/swagger_100419.json

Note:

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:

  1. From the IAM management portal, select the Workspaces tab and select the default workspace.

  2. Select View for the CoffeemakerService service.

  3. In the Documents area (towards the bottom of the panel) select Add a document to this service.

  4. Click in the file selector text box below Or upload a new spec instead... and then select the swagger_100419.json file that you downloaded.

You can now view the OpenAPI specification for the CoffeemakerService. External developers can also access this specification, which allows them to develop REST calls to it. The “Try it Out” option will not work because the curl command does not specify the correct server.

IAM displays the CoffeeMaker REST API and shows the parameters for a call

Note:

If the default dev portal is not set up, select Set up Dev Portal. If the default Dev Portal is disabled, select Enable Developer Portal. It may take a few minutes to set up.

Learn More About InterSystems API Manager

InterSystems provides several resources to learn more about IAM:

If you want more details on how to develop the CoffeemakerService REST service, see First Look: Developing REST Interfaces in InterSystems Products.

Feedback