First Look: InterSystems API Manager

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:

   

   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.

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

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.

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.jsonOpens in a new tab

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.