Skip to main content

Introduction to Creating REST Services

This page introduces REST services in InterSystems IRIS® data platform. You can use these REST interfaces with UI tools, such as Angular, to provide access to databases and interoperability productions. You can also use them to enable external systems to access InterSystems IRIS applications. For an interactive introduction to REST services, try Developing REST InterfacesOpens in a new tab.

Components of an InterSystems REST Service

From the point of view of an application developer, an InterSystems IRIS REST application consists of the following elements on an InterSystems IRIS server:

  • An InterSystems web application, which provides access to the REST service. The web application is configured to enable REST access and to use a specific REST dispatch class.

  • One or more REST classes, which inherit from %CSP.RESTOpens in a new tab. You can create these classes in multiple ways.

Architecturally, there are additional components:

  • A web server, as supported for use with InterSystems IRIS.

  • The Web Gateway, which acts as the intermediary between the web server and the InterSystems IRIS server or servers. The Web Gateway maintains a pool of connections to these servers.

    The Web Gateway configuration includes definitions of web applications running on the InterSystems IRIS servers. These definitions enable the Web Gateway to route requests to the correct web applications on the InterSystems IRIS servers.

Coding Options

There are two general approaches for defining REST classes:

  • Specification-first definition — you first create an OpenAPI 2.0 specification and then use the API Management tools to generate the code.

    This is the recommended approach.

  • Manually coding.

Specification-First

When you define the REST classes via the specification-first approach, the result is the following set of classes:

  • A specification class (a subclass of %REST.SpecOpens in a new tab). This class contains the OpenAPI 2.0 specificationOpens in a new tab for the REST service. InterSystems supports several extension attributes that you can use within the specification.

  • A dispatch class (a subclass of %CSP.RESTOpens in a new tab). This class is responsible for receiving HTTP requests and calling suitable methods in the implementation class.

  • An implementation class (a subclass of %REST.ImplOpens in a new tab). This class defines the methods that implement the REST calls.

    The API management tools generate a stub version of the implementation class, which you then expand to include the necessary application logic. Your logic can of course invoke code outside of this class.

    The %REST.ImplOpens in a new tab class provides utility methods that you can call in order to set HTTP headers, report errors, and so on.

InterSystems follows a strict naming convention for these classes. When generating the classes via the API Management tools, you provide as input the name of the InterSystems web application that governs their use. Given the application name (appname), the names of the specification, dispatch, and implementation class are appname.spec, appname.disp, and appname.impl, respectively. The web application is named /csp/appname by default but you can use a different name for that.

With the specification-first paradigm, you can generate initial code from the specification, and when the specification changes (for example, by acquiring new end points), you can regenerate that code. Later sections provide more details, but for now, note that you should never edit the dispatch class, but can modify the other classes. Also, when you recompile the specification class, the dispatch class is regenerated automatically and the implementation class is updated (preserving your edits).

Manually Coding

It is also possible to manually code a REST service, where you directly create a dispatch class and any supporting code. See Creating a REST Service Manually. Some of the API management utilities enable you to work with manually-coded REST services.

API Management Tools

To help you create REST services more easily, InterSystems provides the following API management tools:

  • A REST service named /api/mgmnt, which you can use to discover REST services on the server, generate OpenAPI 2.0 specificationsOpens in a new tab for these REST services, and create, update, or delete REST services on the server.

  • The ^%REST routine, which provides a simple command-line interface that you can use to list, create, and delete REST services.

  • The %REST.APIOpens in a new tab class, which you can use to discover REST services on the server, generate OpenAPI 2.0 specificationsOpens in a new tab for these REST services, and create, update, or delete REST services on the server.

You can set up logging for these tools, as described later.

Helpful third-party tools include REST testing tools such as PostMan (https://www.getpostman.com/Opens in a new tab) and the Swagger editor (https://swagger.io/tools/swagger-editor/download/Opens in a new tab).

Overview of Creating REST Services

The recommended way to create REST services in InterSystems products is roughly as follows:

  1. Obtain (or write) the OpenAPI 2.0 specificationOpens in a new tab for the service.

  2. Use the API management tools to generate the REST service classes and the associated web application. See Creating and Editing REST Services.

  3. Modify the implementation class so that the methods contain the suitable business logic. See Modifying the Implementation Class.

  4. Optionally modify the specification class. See Modifying the Specification Class. For example, do this if you need to support CORS or use web sessions.

  5. If security is required, see Securing REST Services.

  6. Using the OpenAPI 2.0 specificationOpens in a new tab for the service, generate documentation as described in Discovering and Documenting REST APIs.

For step 2, another option is to manually create the specification class (pasting the specification into it) and then compile that class; this process generates the dispatch and stub implementation class. That is, it is not strictly necessary to use either the /api/mgmnt service or the ^%REST routine. This documentation does not discuss this technique further.

Enabling Logging for API Management Features

To enable logging for the API management features, enter the following in the Terminal:

 set $namespace="%SYS"
 kill ^ISCLOG
 set ^%ISCLOG=5
 set ^%ISCLOG("Category","apimgmnt")=5

Then the system adds entries to the ^ISCLOG global for any calls to the API management endpoints.

To stop logging, enter the following (still within the %SYS namespace):

 set ^%ISCLOG=0
 set ^%ISCLOG("Category","apimgmnt")=0

By default, the maximum number of entries in the log is 10000. To change this, call the MaxLogEntriesSet() method of %Library.SysLogOpens in a new tab.

Viewing the Log

Once logging for HTTP requests is enabled, the log entries are stored in the ^ISCLOG global, which is located in the %SYS namespace.

To use the Management Portal to view the log, navigate to System Explorer > Globals and view the ^ISCLOG global (not ^%ISCLOG). Make sure you are in the %SYS namespace.

To write the ISCLOG global as a log file (for easier readability), enter the following (still within the %SYS namespace):

 do ##class(%OAuth2.Utils).DisplayLog("filename")

Where filename is the full pathname of the file to create. The directory must already exist. If the file already exists, it is overwritten. This method uses the existing data in ^ISCLOG and generates the given file.

Creating and Editing REST ServicesNext section
FeedbackOpens in a new tab