Building a RESTful web API on the InterSystems platform - 2

Introduction

Four years ago I wrote my first article on Habré and it was devoted to creating a RESTful web API on the InterSystems platform . A lot of time has passed since then and several new releases have been released, which have significantly simplified the work on creating a RESTful web API. Here I also want to tell about these changes in this article, and also to give some councils for creation of RESTful web API on the InterSystems platform.

Content

• RESTful web API architecture
• Brokers
• Broker split
• Brokers parameters
• Code summary
• CORS
• Authentication
• Debugging and Testing Tools
• Examples
• Json
• findings
• Links

RESTful web API architecture

I hope that the reader is familiar with what RESTful web API is and the basics of its implementation on the InterSystems platform (available since version 2014.1). Many articles / webinars / training courses in particular and my previous article are devoted to this. In any case, the first thing I would like to start is the overall high-level architecture of your application, including the RESTful web API. It can look like this:

This diagram presents the main levels of your solution:

Data

Stored classes on the InterSystems platform.

Terminal API

The layer of interaction with the data. Data should not be changed otherwise than through this API.
The methods of this API are not written to the device. The terminal API may return:

• An object
• Status or exception (depending on your preference)

Web API

Converts an incoming request to a form understood by the terminal API and calls the methods of the terminal API. The result of the terminal API execution is returned to the client.
The web API does not interact with the data directly. I use the term Web API and not the RESTful web API, since The Web API can be implemented using a different architecture, for example, based on the WebSocket protocol which is also supported by the InterSystems platform, which has already been written on Habré more than once .

Customer

Typically, a JavaScript (but not necessarily) application is available to the end user. This level should not have direct connections to the database, be loaded with basic business logic, and store the state of the application. Only the simplest business logic is usually brought to this level: an authorization interface, validation of input values ​​for validity and compliance with the format, simple data operations (sorting, grouping, counting values) already loaded on the client.

This separation increases the configurability of the application, making it easier to debug, find and fix errors. In essence, this is a three-tier application building architecture .

Brokers

Brokers are classes that contain the logic of your RESTful web API. They:

• Inherited from %CSP.REST
• Contains paths — matching URIs and callable methods

Example path:

 <Route Url="/path/:param1/:param2" Method="GET" Call="Package.Class:ClassMethod" /> 

Where ClassMethod is any class method.

Broker split

"Physical" separation

Since there can be many ways in the RESTful web API - methods, one broker will soon be overloaded with methods. To avoid this, divide the brokers into several classes as follows:

Where:

• An abstract broker is responsible for query conversion, CORS, and other technical issues not related to the RESTful web API logic.
• Brokers 1..N actually contains methods that process requests (calling terminal API methods and returning responses from the terminal API to the client).

"Logical" separation and versioning

Brokers usually contain paths - URI mappings and called methods, but in addition to paths, brokers can “send” requests to each other. It looks like this:

 <Map Prefix="/form" Forward="Destination.Broker"/> 

This allows for the separation of brokers by subject areas with which they are associated, as well as to ensure API versioning:

Brokers parameters

Here are the parameters that are recommended to set in the brokers of your RESTful web API:

 Parameter CONTENTTYPE = {..#CONTENTTYPEJSON}; Parameter CHARSET = "UTF-8"; Parameter UseSession As BOOLEAN = 1; 

That is what they are responsible for:

• CONTENTTYPE - adds to all server responses information that the response will be in JSON format.
• CHARSET - converts the response to UTF8.
• UseSession - uses session for user requests. Read more about this in the authentication section.

Since all brokers are inherited from one abstract broker, it is enough to specify these parameters once in an abstract broker (only the parameters of the first superclass are inherited).

Code summary

One of the problems often encountered when writing a RESTful web API is copy-paste code from a broker to a broker, which creates a large number of paths and lines of code. To avoid this, I recommend using code generation in conjunction with the % Dictionary package containing all the meta information necessary for writing the generator method. An example of active use of code generation is the RESTForms library . In addition, using code generation allows you to achieve greater uniformity in your RESTful web API.

CORS

The technology of modern browsers, which allows you to provide a web page with access to resources of another domain. To enable access to your RESTful web API using CORS, add a parameter to the broker:

 Parameter HandleCorsRequest = 1; 

What will provide access from any other domain. This is unsafe and therefore you must also override the OnHandleCorsRequest method, its signature:

 ClassMethod OnHandleCorsRequest(pUrl As %String) As %Status {} 

This method should check the origin of the request, for example, it must match the host name of the web application. To obtain Origin, you can use this method:

 ClassMethod GetOrigins() As %String { set url = %request.GetCgiEnv("HTTP_REFERER") return $p(url,"/",1,3) // get http(s)://origin.com:port } 

Authentication

In order for one user to consume one license and work within one session, you need to configure your REST and CSP applications in the System Management Portal so that the following conditions are met:

1. In all brokers Parameter UseSession = 1; .
2. All web applications are only available with authentication.
3. All web applications have a session timeout (900, 3600).
4. All applications have the same GroupById value.
5. All applications have the same Cookie Path value.

Debugging and Testing Tools

For debugging, you can use external tools such as:

• REST client (for example, Postman) - the primary debugging tool RESTful web API allows you to save and document requests, format JSON responses, execute requests to several environments, and provides many other conveniences to the developer.
• Interception proxy server (for example, Fiddler) - allows you to intercept, display, edit and duplicate requests to the RESTful web API.
• Traffic analyzer (for example, WireShark) - helps in cases of broken packets, problems with encodings, the need to analyze a remote system and other situations when the above tools are not enough.

I strongly recommend not using command line tools such as curl and wget.

External and internal debugging tools are described in detail in a series of articles ( Part 1 - external tools , Part 2 - internal tools ) on the InterSystems Developer Community .

Examples

I will give a few examples of RESTful web API.

MDX2JSON and DeepSeeWeb client

MDX2JSON - RESTful web API provides information about cubes, pivots, dashboards and many other DeepSee elements, in particular, the results of MDX queries, which allows you to embed the user interface of the analytical solution on DeepSee into any modern Web or mobile application. Works since version 2014.1.
DeepSeeWeb - AngularJS application that provides an alternative implementation of the DeepSee user portal. Can be easily customized. Uses MDX2JSON as a backend. Here is an example of a dashboard rendered in DeepSeeWeb:

Detailed article about DeepSee .

EnsembleWorkflow and the EnsembleWorkflowUI client

The InterSystems integration platform has an Ensemble Workflow subsystem that allows people to participate in automated business processes. Ensemble Workflow RESTful web API and EnsembleWorkflowUI client. RESTful web API provides access to user tasks. Works since version 2014.1. Here is the visualization:

RESTForms

RESTForms is a universal RESTful web API backend of working with data on the InterSystems 2016 platform 2016+ for modern web applications.

Here are some of the paths available in RESTForms:

In this project, code compilation is actively used (using code generation and using the %Dictionary package).

Angular and React clients are available, it looks like this:

Json

JavaScript Object Notation is a text-based data exchange format used in conjunction with the RESTful web API. JSON support on the InterSystems platform has appeared since version 2009.2, but has been significantly improved to version 2016.2. Read more about using JSON in the documentation .

findings

• REST today - the main and generally accepted method of constructing an API for the Internet
• By providing a RESTful web API, you get the opportunity to choose from a huge set of technologies to build client applications, including:
  
  • JavaScript (AngularJS, React, extJS, ...)
  • Mobile applications (Cordova and the like, Native)
• InterSystems technologies allow you to easily create a RESTful web API.

Links

• Part I
• Webinar about RESTful web API architecture
• Webinar about developing RESTful web API
• Documentation
• RESTful web API development series