Topic outline

• Developing REST Interfaces

  Developing REST Interfaces

  Content Type
  Exercise

  Duration
  20m

  Level
  Introductory

  Learn how to assemble the key parts of a REST interface in InterSystems IRIS® data platform. REST is a reliable way to interact with a server for executing methods and querying data. In this exercise, you will see how an InterSystems IRIS server, web application, dispatch and implementation classes, and a web client come together to create the front-end website for a coffee maker company.

  To get hands-on practice creating an application, try Setting Up RESTful Services (online course, 1h 30m).

  • Mark me "complete" for this exercise.

    Not available unless: Your ID number is not empty
• Start the Exercise

  Start the Exercise
  • 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.
  • Launch the virtual machine (VM) below to begin working on the exercise. For responses to common questions on using VM-based Learning Labs, visit FAQ: Using Learning Services Virtual Machines.

    Your login information for the VM is the following:

    • Username: student
    • Password: LearningServices7
  •  You must be logged in to launch this virtual machine.

    • Log in with your existing account.
    • Don't have an InterSystems account? Create a new account.
  • Open your virtual machine

    Start by opening your virtual machine and familiarizing yourself with its contents.

    1. Terminal sessions can be opened using the left hand Favorites bar.
    2. Your instance of InterSystems IRIS is bookmarked within Google Chrome.
    3. Postman is installed and available via the Favorites bar. This will be used to send REST requests in the exercise.
  • Build the sample code

    To build the sample code, follow this procedure:

    1. Open a new terminal window via the left hand bar on your virtual machine.
    2. Run the following command to open a command line session on the container running your InterSystems IRIS server:
       
       docker exec -it iris bash
    3. Run the following command to open an InterSystems IRIS Terminal session within the container:
       
       iris session iris
    4. Set the current namespace to the INTEROP namespace:
       
       set $namespace = "INTEROP"
    5. Enter the following two commands to load and build the sample classes from your downloaded repository:
       
       do $system.OBJ.Load("/external/FirstLook-REST/buildsample/Build.RESTSample.cls","ck")
       do ##class(Build.RESTSample).Build()
    6. When prompted, enter the full path of the directory to which you downloaded this sample:
       
       /external/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. Open Google Chrome and navigate to the IRIS bookmark in your browser.
    2. Log in using username tech and password demo7.
    3. Click System Administration > Security > Applications > Web Applications.
    4. 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: INTEROP
       • 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.
    5. 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 the Postman application on your virtual machine (the orange icon in your left hand bar), 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://localhost:52773/rest/coffeemakerapp/newcoffeemaker.
       • Authorization: Basic Authorization, using tech / demo7.
       • Body (select raw as the body type):
         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://localhost:52773/api/mgmnt/v1/INTEROP/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!