Topic outline

• Developing REST Interfaces

  Developing REST Interfaces

  Learn how to develop REST interfaces in InterSystems IRIS® data platform. In this exercise, you will:

  • Define data classes.
  • Write InterSystems ObjectScript functions to access your data.
  • Define a REST API based on these functions.
  • Expose your API specification for clients to build their own applications.
  • Use front-end UI tools to call your API.
• Collapse allExpand all
  Exercise Overview

  Exercise Overview

  • REST interfaces are a reliable way to interact with a server for executing methods and querying data. In this exercise, you will assemble the main parts of a REST interface in InterSystems IRIS, including:

    • An InterSystems IRIS server with relevant classes and data
    • A web application, internal to the server, which names the URL basepath for a REST interface
    • A dispatch class on the server which names all of routes in the REST API and associates each one with a function
    • An implementation class on the server which includes functions
    • A web client, either external to the server or also served by InterSystems IRIS, utilizing the API

    You will have access to a temporary remote InterSystems server, including an online IDE, as well as GitHub code for the REST interfaces.

    Note:

    To complete the exercise, you will need a tool to send REST requests, such as Postman, Chrome Advanced REST Client, or cURL.

• Try it

  Try it

  • In this exercise, you will take the role of an API developer working for a coffee maker company, whose back-end is an InterSystems IRIS server. On this server, you will do the following:

    1. Define a table of coffee maker data, where the coffee makers are your company's inventory.
    2. Add a class of endpoint methods that update the database, for example, a method that deletes a coffee maker from the inventory table once it has been sold. The endpoint methods will be exposed via a REST API.
    3. Test the REST API. You could eventually use the API in your company's online store.
  •  You must be logged in to launch an InterSystems IRIS instance.

    • Log in with your existing account.
    • Don't have an InterSystems account? Create a new account.
  • Download the sample application

    Start by opening your IDE and downloading the completed application, which includes all of the classes and endpoint methods for your inventory application. The code that you download in your IDE will be automatically shared with the InterSystems IRIS server.

    1. Open the IDE using the link in the launcher above.
    2. Open the command-line terminal in the IDE by clicking View > Terminal.
    3. Change the directory 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 Project, and the directory is also available on the InterSystems IRIS server in /home/project/shared.

  • Create an interoperability-enabled namespace

    1. Open the Management Portal for your instance in your browser using the link provided in the launcher above.
    2. Create an interoperability-enabled namespace. First, navigate to the Namespaces page:
       System Administration > Configuration > System Configuration > Namespaces.
    3. Create a new namespace:
       1. Click the Create New Namespace button.
       2. Enter the name INTEROP.
       3. Copy settings from the USER namespace, and enable the namespace for interoperability productions.
       4. Click Save and OK.
          
  • Build the sample code

    To build the sample code, follow this procedure:

    1. Open the InterSystems Terminal using the Web Terminal link in the launcher above.
    2. Log in with the credentials provided in the launcher above.
       
    3. Set the namespace to your interoperability-enabled namespace:
       
       set $namespace = "INTEROP"
    4. Enter the following two commands to load and build the sample classes from your downloaded repository:
       
       do $system.OBJ.Load("/home/project/shared/FirstLook-REST/buildsample/Build.RESTSample.cls","ck")
       do ##class(Build.RESTSample).Build()
    5. When prompted, enter the full path of the directory to which you downloaded this sample:
       
       /home/project/shared/FirstLook-REST

    The method then loads and compiles the code and performs other needed setup steps.

  • Define a web application

    Now that you have compiled the sample code with the REST interfaces on your server, follow these steps to define a web application:

    1. Return to the Management Portal for your instance.
    2. Click System Administration > Security > Applications > Web Applications.
    3. Click 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 class names all the routes in the REST API and associates each one with a function.
       • Security Settings/Allowed Authentication Methods: Select both Unauthenticated and Password.
    4. To allow unauthenticated access for this sample, you must give the web application the %All role. To do this:
       1. Click Save, then the Application Roles tab.
       2. Select the %All role from the Available roles.
       3. Click the right arrow (select) button to move the %All role to the Selected roles.
       4. Click the Assign button.

    The %All role is now listed as an Application Role. This ensures that a REST call from an unauthenticated user will have the privileges needed to access the coffeemakerapp data. Without this role, the REST call would have to specify authentication for a user who has sufficient privileges.

  • Access the REST interfaces

    The coffeemaker application is now functional, with a data table, an InterSystems IRIS web application, and exposed endpoints. Finally, you can test your API to make sure that these work as expected. You will submit API requests to access the coffee maker database. In your local REST API tool, such as Postman or Advanced REST Client, follow these steps:

    1. Send a REST POST request to add a new coffee maker, using your server details where needed. Your server address, port, and credentials are in the launcher above.
       • HTTP Action: POST
       • URL: http://server:port/rest/coffeemakerapp/newcoffeemaker, where server and port are the Host Server Address and Host Server Web Port for your instance.
       • Authorization: Basic Authorization, using login credentials for your instance.
       • Input data (request body):
         Begin code:
         {"img":"img/coffee3.png", "coffeemakerID":"99", "name":"Double Dip", "brand":"Coffee+", "color":"Blue", "numcups":2, "price":71.73}
         End code. 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"}
    2. Send another REST POST request to add the following coffee maker: Begin code:
       {"img":"img/coffee4.png", "coffeemakerID":"99", "name":"French Press", "brand":"Coffee For You", "color":"Blue", "numcups":4, "price":50.00}
       End code.
    3. Send another REST POST request:Begin code:
       {"img":"img/coffee9.png", "coffeemakerID":"99", "name":"XPress", "brand":"Shiny Appliances", "color":"Green", "numcups":1, "price":95.00}
       End code.
    4. Send 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:
         Begin code:
         [{"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}]
         End code.
    5. Send 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"}
    6. Repeat the REST GET request. The call returns a list of coffee makers, such as:
       Begin code:
       [{"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}]
       End code.
  • Document the REST interface

    Now that you have tested the API, you can provide it to clients or developers who will use it to build an online store. 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 IRIS 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:

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

    You can paste the response from this call into Swagger, a tool for API specifications. It converts the JSON to YAML (Yet Another Markup Language) and displays the documentation. You can use the Swagger editor to add more information. It displays each available endpoint and the expected parameters.
    

     

• What's next?

  What's next?

  Now that you have seen a REST API exposed by InterSystems IRIS, you can continue to extend your knowledge on the topic.

  • Get a full complete overview of REST Services in InterSystems IRIS (documentation).
  • Get the most out of your API by Using REST Services and Operations in Productions (documentation).
  • Go more in-depth on the coffee maker application with Setting Up RESTful Services (online course, 1h 30m).

  • Share Your Feedback!