First Look: Developing REST Interfaces in InterSystems Products

Creating a Subclass of %CSP.REST and Defining the URLMap

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> 
}

• Url — this identifies the REST URL that can be handled by this Route. Since IRIS directs URLs starting with /rest/coffeemakerapp, this property specifies the part of the URL immediately after that. If the Url property is /coffeemakers, this Route handles URLs starting with /rest/coffeemakerapp/coffeemakers.
• Method — this identifies the verb that the Route handles. Note that the last two lines have the same value for Url, /coffeemaker/:id. The Route with the PUT method will handle PUT verbs with a URL starting with /rest/coffeemakerapp/coffeemaker/:id and the Route with the DELETE method will handle DELETE verbs with the same starting URL.
• Call — specifies the method to call to process this REST call. The method is passed the complete URL and any data so it can base its response on the URL.

Coding the Methods

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
}

• There are no parameters. Whenever this method is called it executes an SQL statement that selects all records from the demo.coffeemaker database.
• For each record in the database, it appends the values to an array as name, value pairs.
• It converts the array to JSON and returns the JSON to the calling application by writing the JSON out to stdout.
• Finally, it quits with a success.

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
}

• First it tests if the payload contains a valid JSON object by calling the GetJSONFromRequest() and ValidateJSON() methods defined later in the class.
• Then it uses the JSON object to create a new demo.coffeemaker and then saves the record in the database.
• It returns the status by writing it to stdout.

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
}

• Getting any parameter as a call argument.
• Accessing the payload through obj value.
• Returning the response to the client application by writing it to stdout.

Before you Begin

Downloading the Sample Application

• If you are using an ICM-deployed instance:
  1. Use the icm ssh command with the -machine and -interactive options to open your default shell on the node hosting the instance, for example:

     icm ssh -machine MYIRIS-AM-TEST-0004 -interactive
     

  2. On the Linux command line, use one of the following commands to clone the repo to the data storage volume for the instance. For a configuration deployed on Azure, for example, the default mount point for the data volume is /dev/sdd, so you would use commands like the following:

     $ git clone https://github.com/intersystems/FirstLook-REST /dev/sdd/FirstLook-REST
     OR
     $ wget -qO- https://github.com/intersystems/FirstLook-REST/archive/master.tar.gz | tar xvz -C /dev/sdd
     

  The files are now available to InterSystems IRIS in /irissys/data/FirstLook-REST on the container’s file system.
• If you are using a containerized instance (licensed or Community Edition) that you deployed by other means:
  1. Open a Linux command line on the host. (If you are using Community Edition on a cloud node, connect to the node using SSH, as described in Getting Started with InterSystems IRIS Community Edition.)
  2. On the Linux command line, use either the git clone or the wget command, as described above, to clone the repo to a storage location that is mounted as a volume in the container.
     • For a Community Edition instance, you can clone to the instance’s durable %SYS directory (where instance-specific configuration data is stored). On the Linux file system, this directory is /opt/ISC/dur. This makes the files available to InterSystems IRIS in /ISC/dur/FirstLook-REST on the container’s file system.
     • For a licensed containerized instance, choose any storage location that is mounted as a volume in the container (including the durable %SYS directory if you use it). For example, if your docker run command included the option -v /home/user1:/external, and you clone the repo to /home/user1, the files are available to InterSystems IRIS in /external/FirstLook-REST on the container’s file system.
• If you are using an InterSystems Learning Labs instance:
  1. Open the command-line terminal in the integrated IDE.
  2. Change directories to /home/project/shared and use the git clone command to clone the repo:

     $ git clone https://github.com/intersystems/FirstLook-REST 
     

  The folder is added to the Explorer panel on the left under Shared, and the directory is available to InterSystems IRIS in /home/project/shared.
• If you are using an installed instance:
  • If the instance’s host is a Windows system with GitHub Desktop and GitHub Large File Storage installed:
    1. Go to https://github.com/intersystems/FirstLook-REST in a web browser on the host.
    2. Select Clone or download and then choose Open in Desktop.
    The files are available to InterSystems IRIS in your GitHub directory, for example in C:\Users\User1\Documents\GitHub\FirstLook-REST.
  • If the host is a Linux system, simply use the git clone command or the wget command on the Linux command line to clone the repo to the location of your choice.

Building the Sample Code

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.

Defining a Web Application

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
   • 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.
   • Namespace: The name of the interoperability-enabled namespace you created.
   • Enable: Select REST.
   • Dispatch Class: Demo.CoffeeMakerRESTServer — This is the class that defines the URLMap.
   • Security Settings/Allowed Authentication Methods: Select both the Unauthenticated and Password check boxes.
5. Select Save.

Accessing the REST Interfaces

1. Specify a REST POST request to add a new coffee maker, using the information specific to your InterSystems IRIS instance where needed
   • HTTP Action: POST
   • URL: http://server:port/rest/coffeemakerapp/newcoffeemaker, where server and port are the host identifier and web server port for your instance.
   • Login credentials for your instance.
   • Input data:

     {"img":"img/coffee3.png","coffeemakerID":"99","name":"Double Dip","brand":"Coffee+", 
       "color":"Blue","numcups":2,"price":71.73}
     

   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:
   • HTTP Action: GET
   • URL: http://server:port/rest/coffeemakerapp/coffeemakers
   • Login credentials for your instance.
   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:
   • HTTP Action: DELETE
   • URL: http://server:port/rest/coffeemakerapp/coffeemaker/2
   • Login credentials for your instance.
   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

• HTTP Action: GET
• URL: http://server:port/api/mgmnt/v1/namespace/spec/rest/coffeemakerapp/
• Login credentials for your InterSystems IRIS instance.