docs.intersystems.com
InterSystems IRIS Data Platform 2019.2

First Look: Developing REST Interfaces in InterSystems Products
InterSystems: The power behind what matters   
Search:  


This First Look shows you how to develop REST interfaces. 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™ data platform applications.
To browse all of the First Looks, including those that can be performed on a free evaluation instance of InterSystems IRIS, see InterSystems First Looks.
Why Provide a REST Interface
If you need access to the data in an InterSystems IRIS™ database from an external system or want to provide a user interface for that data, you can do it by defining a REST interface. REST — or REpresentational State Transfer — is a way to retrieve, add, update, or delete data from another system using an exposed URL. REST is based on HTTP and uses the HTTP verbs POST, GET, PUT, and DELETE to map to the common Create, Read, Update, and Delete (CRUD) functions of database applications. You can also use other HTTP verbs, such as HEAD, PATCH, and OPTIONS, with REST.
REST is one of many ways to share data between applications, so you may not always need to set up a REST service if you choose to communicate directly using another protocol, such as TCP, SOAP, or FTP. But using REST has the following advantages:
How to Define REST Interfaces in InterSystems IRIS
There are two ways to define REST interfaces in InterSystems IRIS:
Advantages of using the specification-first definition include the ability to automatically generate documentation and client code from the specification, but you can use either way to define REST interfaces. This First Look shows how to manually code the REST interface. See Creating Rest Services for information on defining REST interfaces using a specification.
Before defining REST interfaces, you should understand how a REST call flows through InterSystems IRIS. First consider the parts of a REST call such as:
GET http://localhost:52773/rest/coffeemakerapp/coffeemakers
This consists of the following parts:
Note:
Although this First Look uses the web server installed with InterSystems IRIS (in this case on port 52773 on the local system), you should replace it with a commercial web server for any code that you deploy. The web server installed with InterSystems IRIS is intended only for temporary use in developing code and does not have the robust features of a commercial web server.
When a client application makes a REST call:
  1. InterSystems IRIS directs it to the web application that corresponds to the URL. For example, a URL starting with /coffeemakerapp would be sent to the application handling coffee makers and a URL starting with /api/docdb would be sent to the web application handling the Document Data Model.
  2. The web application directs the call to a method based on the HTTP verb and any part of the URL after the section that identifies the web application. It does this by comparing the verb and URL against a structure called the URLMap.
  3. The method uses the URL to identify the resource that the REST call is specifying and performs an action based on the verb. For example, if the verb is GET, the method returns some information about the resource; if the verb is POST, the method creates a new instance of the resource; and if the verb is DELETE, the method deletes the specified resource. For POST and PUT verbs, there is typically a data package, which provides more information.
  4. The method performs the requested action and returns a response message to the client application.
Defining a REST interface requires:
This First Look uses a sample application, coffeemakerapp, that accesses a database of coffee makers. Each record describes a coffee maker, including information such as its name, brand, and price. The coffeemakerapp provides REST interfaces to get information about the coffee makers, create a new record in the database, update an existing record, or delete a record. In a later section, this First Look tells you how to get the sample code from https://github.com/intersystems/FirstLook-REST.
Creating a Subclass of %CSP.REST and Defining the URLMap
Here is the first part of the demo.CoffeeMakerRESTServer class definition. It extends the %CSP.REST class.
Class Demo.CoffeeMakerRESTServer Extends %CSP.REST
{
Parameter HandleCorsRequest = 1;

XData UrlMap [ XMLNamespace = "http://www.intersystems.com/urlmap" ]
{
    <Routes>
      <Route Url="/test" Method="GET" Call="test"/>
      <Route Url="/coffeemakers" Method="GET" Call="GetAll" /> 
      <Route Url="/coffeemaker/:id" Method="GET" Call="GetCoffeeMakerInfo" /> 
      <Route Url="/newcoffeemaker" Method="POST" Call="NewMaker" /> 
      <Route Url="/coffeemaker/:id" Method="PUT" Call="EditMaker" /> 
      <Route Url="/coffeemaker/:id" Method="DELETE" Call="RemoveCoffeemaker"/>
   </Routes> 
}
Look at the Route elements. Each has three properties:
The part of the Url value that starts with a : represents a wildcard. That is /coffeemaker/:id will match /coffeemaker/5, /coffeemaker/200, and even /coffeemaker/XYZ. The called method will get passed the value of :id in a parameter. In this case, it identifies the ID of the coffee maker to update (with PUT) or delete.
The Url value has additional options that allow you to forward the REST URL to another instance of a %CSP.REST subclass, but you don’t need to deal with that in this First Look. The HandleCorsRequest parameter specifies whether browsers should allow Cross-origin Resource Sharing (CORS), which is when a script running in one domain attempts to access a REST service running in another domain, but that is also an advanced topic.
Coding the Methods
The GetAll method retrieves information about all coffee makers. Here is its code:
ClassMethod GetAll() As %Status
{
  Set tArr = []
  Set rs = ##class(%SQL.Statement).%ExecDirect(,"SELECT * FROM demo.coffeemaker")
  While rs.%Next() {
    Do tArr.%Push({
      "img":              (rs.%Get("Img")),
      "coffeemakerID":    (rs.%Get("CoffeemakerID")),
      "name":             (rs.%Get("Name")),
      "brand":            (rs.%Get("Brand")),
      "color":            (rs.%Get("Color")),
      "numcups":          (rs.%Get("NumCups")),
      "price":            (rs.%Get("Price"))
    })
  }
  
  Write tArr.%ToJSON()
  Quit $$$OK
}
Points to note about this method:
The NewMaker() method has no parameters, but has a JSON payload that specifies the coffee maker to create. Here is its code:
ClassMethod NewMaker() As %Status
{
  If '..GetJSONFromRequest(.obj) {
    Set %response.Status = ..#HTTP400BADREQUEST
    Set error = {"errormessage": "JSON not found"}
    Write error.%ToJSON()
    Quit $$$OK
  }
  
  If '..ValidateJSON(obj,.error) {
    Set %response.Status = ..#HTTP400BADREQUEST
    Write error.%ToJSON()
    Quit $$$OK
  }
  
  Set cm = ##class(demo.coffeemaker).%New()
  Do ..CopyToCoffeemakerFromJSON(.cm,obj)
  
  Set sc = cm.%Save()
  
  Set result={}
  do result.%Set("Status",$s($$$ISERR(sc):$system.Status.GetOneErrorText(sc),1:"OK"))
  write result.%ToJSON()
  Quit sc
}
Points to note about this method:
Finally, the RemoveCoffeemaker() method shows how the :id part of the Url is passed to the method as a parameter:
ClassMethod RemoveCoffeemaker(id As %String) As %Status
{
  Set result={}
  Set sc=0
  
  if id'="",##class(demo.coffeemaker).%ExistsId(id) {
    Set sc=##class(demo.coffeemaker).%DeleteId(id)
    do result.%Set("Status",$s($$$ISERR(sc):$system.Status.GetOneErrorText(sc),1:"OK"))
  }
  else  {
    do result.%Set("Status","")  
  }
  
  write result.%ToJSON()
  
    quit sc
}
In summary, the methods specified by the Route Call property handles the REST call by:
Defining a REST Interface for Yourself
This section shows you step-by-step how to use the coffee maker application to handle REST calls. It starts with getting your system ready, including downloading the sample code from github, and takes you through the steps required to build the code and create the environment in the Management Portal.
Before you Begin
To use the procedure, you will need a system to work on, with an installed REST API application such as Postman, Chrome Advanced REST Client, or cURL installed, and a running InterSystems IRIS instance to connect to. Your choices for InterSystems IRIS include several types of licensed and free evaluation instances; the instance need not be hosted by the system you are working on (although they must have network access to each other). For information on how to deploy each type of instance if you do not already have one to work with, see Deploying InterSystems IRIS in InterSystems IRIS Basics: Connecting an IDE. For the information needed to connect your REST API application to your InterSystems IRIS instance, see InterSystems IRIS Connection Information in the same document.
You should also clone or download the FirstLook-REST sample code from github: https://github.com/intersystems/FirstLook-REST. This sample demonstrates REST APIs for a coffee maker database. The FirstLook-REST sources must be accessible by the instance. The procedure for downloading the files depends on the type of instance you are using, as follows:
Building the Sample Code
To build the sample code, follow this procedure
  1. Open the InterSystems IRIS Terminal, using the procedure described for your instance in InterSystems IRIS Basics: Connecting an IDE.
  2. Enter the following commands, replacing <path> with the full path of the buildsample/Build.RESTSample.cls file that you downloaded:
    do $system.OBJ.Load("<path>/Build.RESTSample.cls","ck")
    
    do ##class(Build.RESTSample).Build()
  3. When prompted, enter the full path of the directory to which you downloaded this sample. The method then loads and compiles the code and performs other needed setup steps.
Note:
The FirstLook-REST / README.md file contains a version of these instructions.
Defining Web Applications
To define the needed web applications, follow this procedure.
First, create a web application to contain the application. This is not the web application that will process the REST requests.
  1. Open the Management Portal for your instance in your browser, using the URL described for your instance in InterSystems IRIS Basics: Connecting an IDE.
  2. Create an interoperability-enabled namespace by navigating to the Namespaces page (System Administration > Configuration > System Configuration > Namespaces) and clicking the Create New Namespace button following the instructions for using the New Namespace page in Create/Modify a Namespace in the “Configuring InterSystems IRIS” chapter of the System Administration Guide.
  3. Select System Administration > Security > Applications > Web Applications.
  4. Select Create New Web Application and enter the following settings:
    1. Name: /coffee
    2. Namespace: The name of the interoperability-enabled namespace you created.
    3. Enable: Select CSP/ZEN.
    4. CSP File Settings/Physical Path:
      1. Click the Browse button to open the Directory Selection Dialog to the install-dir/Mgr directory (where install-dir is the instance’s installation directory); go up a level from Mgr/, then select the install-dir/csp directory.
      2. Outside the Management Portal, copy the coffee directory you downloaded to install-dir/csp, the location you have browsed to, for example C:\InterSystems\MYIRIS\csp.
      3. In the Directory Selection dialog, select the coffee directory, for example, C:\InterSystems\MYIRIS\csp\coffee.
  5. Select Save.
Now create a second web application to handle the REST calls.
  1. Select Create New Web Application again and enter the following settings:
    1. Name: /rest/coffeemakerapp — This specifies the URLs that will be handled by this web application. InterSystems IRIS will direct all URLs that begin with /rest/coffeemakerapp to this web application.
    2. Namespace: The name of the interoperability-enabled namespace you created.
    3. Enable: Select REST.
    4. Dispatch Class: Demo.CoffeeMakerRESTServer — This is the class that defines the URLMap.
    5. Security Settings/Allowed Authentication Methods: Select both the Unauthenticated and Password check boxes.
  2. Select Save.
Accessing the REST Interfaces
The CoffeeMaker REST application is now working. You will enter REST commands to access the coffee maker database. In your REST API tool, such as Postman, follow these steps:
  1. Specify a REST POST request to add a new coffee maker, using the information specific to your InterSystems IRIS instance where needed
    Although the data contains a value for coffeemakerID, that is a calculated field and a new value is assigned when the record is added. The call returns a success status:
    {"Status":"OK","Message":"New maker saved with ID 1"}
  2. Repeat the previous step to add the following two coffee makers:
    {"img":"img/coffee4.png","coffeemakerID":"99","name":"French Press","brand":"Coffee For You", \
    "color":"Blue","numcups":4,"price":50.00}
    {"img":"img/coffee9.png","coffeemakerID":"99","name":"XPress","brand":"Shiny Appliances", \
    "color":"Green","numcups":1,"price":95.00}
  3. Specify a REST GET request, using the same instance-specific information, to get a list of coffee makers in the database:
    The call returns a list of coffeemakers, such as:
    [{"img":"img/coffee3.png","coffeemakerID":"1","name":"Double Dip","brand":"Coffee+", \
    "color":"Blue","numcups":2,"price":71.73},
    {"img":"img/coffee4.png","coffeemakerID":"2","name":"French Press","brand":"Coffee For You", \
    "color":"Blue","numcups":4,"price":50},
    {"img":"img/coffee9.png","coffeemakerID":"3","name":"XPress","brand":"shiny Appliances", \
    "color":"Green","numcups":1,"price":95}]
    
  4. Specify the following REST call to delete the coffee maker with ID=2:
    The call returns a success status:
    {"Status":"OK"}
  5. Repeat the REST GET request. The call returns a list of coffeemakers, such as:
    [{"img":"img/coffee3.png","coffeemakerID":"1","name":"Double Dip","brand":"Coffee+", \
    "color":"Blue","numcups":2,"price":71.73},
    {"img":"img/coffee9.png","coffeemakerID":"3","name":"XPress","brand":"Shiny Appliances", \
    "color":"Green","numcups":1,"price":95}]
    
Documenting REST Interfaces
When you provide REST interfaces to developers you should provide documentation so that they know how to call the interfaces. You can use the Open API Spec to document REST interfaces and a tool, such as Swagger to edit and format the documentation. InterSystems is developing a feature to support this documentation. This release contains a feature in API Management that generates the document framework for your REST APIs. You still need to edit the generated documentation to add comments and additional information, such as content of arguments and HTTP return values.
To generate the documentation for the CoffeeMakerApp REST sample, enter the following REST call, using the information specific to your InterSystems IRIS instance and the name of the namespace you created:
You can paste the output from this call into the swagger editor. It converts the JSON to YAML (Yet Another Markup Language) and displays the doc. You can use the swagger editor to add more information to the documentation. The swagger editor displays the documentation as shown in the following:
For More Information on InterSystems IRIS and REST
See the following for more information on creating REST services in InterSystems IRIS:


Send us comments on this page
View this article as PDF   |  Download all PDFs
Copyright © 1997-2019 InterSystems Corporation, Cambridge, MA
Content Date/Time: 2019-08-23 06:47:59