Using Flask, REST API, and IAM with InterSystems IRIS

Part 1 - REST API

 

Hello

In this article we will see the implementation of a REST API to perform the maintenance of a CRUD, using Flask and IAM.

In this first part of the article we will see the construction and publication of the REST API in Iris.

First, let's create our persistent class to store the data. To do this, we go to Iris and create our class:

Class ERP. Client Extends (%Persistent, %Populate, %XML.Adaptor)

{

 

Property name As %String;

 

Property age As %Integer;

 

}

 

Ready. We already have our persistent class created and ready to receive data. Now let's create our REST API.

When we talk about REST, we are talking about the HTTP protocol and its verbs. HTTP verbs are methods that define the operation that the client wants to do. Some examples of HTTP verbs are:

• GET: Requests a specific resource and returns only data. It is the standard for submitting data when submitting an HTTP form. 
• POST: Submits data to a resource, changing states of a resource present on the server. It is used to send information to be processed, such as creating a product or a customer. 
• HEAD: Similar to the GET method, however it does not require the body of the response.
• PUT: Replaces all current renditions of the target resource with the request's data payload.
• DELETE: Deletion.

As a response to the verbs we have, the status codes indicate the result of the request. For example, 200 indicates that the request was successful.

Iris implements REST in a very easy and robust way. The following documentation provides all the information you need to create a REST API: https://docs.intersystems.com/irislatest/csp/docbook/DocBook.UI.Page.cls?KEY=GREST

Let's then assemble the code of our REST API to perform basic maintenance on our ERP class. Customer. for this we will create a class that extends from %CSP. REST:

Class Rest.Servico Extends %CSP. REST

{

 

XData UrlMap

{

<Routes>

        <route url="/customer" method="POST" call="include" cors="true"/>

        <Route Url="/customer/:key" Method="PUT" Call="Change" Cors="true"/>

        <Route Url="/client/:key" Method="DELETE" Call="Delete" Cors="true"/>

        <Route Url="/customer/:key" Method="GET" Call="Search" Cors="true"/>

        <Route Url="/client" Method="GET" Call="List" Cors="true"/>

    </Routes>

}

 

ClassMethod Include() The %Status

{

             

              From ##class(%REST. Impl).%SetContentType("application/json")

             

    Set payload = %request. Content.Read()

    Set objJSON=##Class(%DynamicAbstractObject).%FromJSON(payload)

       

    Set objCustomer=##Class(ERP. Client).%New()

    Set objClient.name=objJSON.name

    Set objClient.age=objJSON.age

    Set st=objClient.%Save()

    If 'st

    {

                  From ##class(%REST. Impl).%SetStatusCode("404") Quit $$$OK

 

    }

   

              From ##class(%REST. Impl).%SetStatusCode("200")

 

    return $$$OK

}

 

ClassMethod Change(key As %Integer) As %Status

{

             

              From ##class(%REST. Impl).%SetContentType("application/json")

 

    Set payload = %request. Content.Read()

    Set objJSON=##Class(%DynamicAbstractObject).%FromJSON(payload)

       

    Set objCustomer=##Class(ERP. Client).%OpenId(key)

    If '$IsObject(objClient)

    {

                  From ##class(%REST. Impl).%SetStatusCode("404") Quit $$$OK

 

    }    

   

    Set objClient.name=objJSON.name

    Set objClient.age=objJSON.age

    Set st=objClient.%Save()

    If 'st

    {

                  From ##class(%REST. Impl).%SetStatusCode("500") Quit $$$OK

 

    }   

   

              From ##class(%REST. Impl).%SetStatusCode("200")

 

    return $$$OK

}

 

ClassMethod Delete(key As %Integer) As %Status

{

              From ##class(%REST. Impl).%SetContentType("application/json")

       

    Set st=##Class(ERP. Client).%DeleteId(key)

    If 'st

    {

                  From ##class(%REST. Impl).%SetStatusCode("404") Quit $$$OK

 

    }   

   

              From ##class(%REST. Impl).%SetStatusCode("200")

 

    return $$$OK

}

 

ClassMethod Search(key As %Integer) As %Status

{

       

    From ##class(%REST. Impl).%SetContentType("application/json")

             

    Set objCustomer=##Class(ERP. Client).%OpenId(key)

    If '$IsObject(objClient)

    {

                  From ##class(%REST. Impl).%SetStatusCode("404") Quit $$$OK

 

    }

   

              From ##class(%REST. Impl).%SetStatusCode("200")   

   

    Set objJSON={}   

    Set objJSON.id=key

    Set objJSON.name=objectClient.name

    Set objJSON.age=objCustomer.age

             

              Write objJSON.%ToJSON() 

 

    return $$$OK

}

 

ClassMethod List() As %Status

{

              From ##class(%REST. Impl).%SetContentType("application/json")          

                                         

              Set result=##class(%ResultSet).%New("%DynamicQuery:SQL")

 

              Set st=result. Prepare("select id, name, age from ERP. Client")

    If 'st

    {

                  From ##class(%REST. Impl).%SetStatusCode("500") Quit $$$OK

 

    }        

              Set st=result. Execute()

   

    Set objJSON={}

    Set clients=[]

             

              While result. Next(.st) {

                           

                            Set objCliente={}

                            Set objClient.id=result.%Get("ID")                                          

                            Set objClient.name=result.%Get("name")             

                            Set objectCustomer.age=result.%Get("age")       

                            From Customers.%Push(objectCustomer)

              }

       

              From ##class(%REST. Impl).%SetStatusCode("200")

             

              Set outputa={}

              Set out.customers=customers

             

              Write output.%ToJSON()

 

    return $$$OK

}

 

}

Notice the part of the code that defines the URLs (UrlMap) where we have the URL called, the verb (Method) triggered, and the method of the code that should be called. It is very easy to understand each of the calls made and the association of the call with the HTTP verb.

Now that we've created our class, let's set up a web application in the iris so that this application does the REST service we want to provide. To do this, we go to the Administration->System Administration->Security->Applications->Web Applications Portal and we will create a new application:

 

Enter the name of the application (/rest/service), the Namespace where the REST class was created, check the Activate application box. Select the REST option and enter the Dispatch class. Check the Password option under Methods for Authentication and save the setting.

Our REST class is published and ready to be consumed. Simple as that!

We're going to use Postman to do some testing on our API. The first test is to see if we can retrieve the customer list.

Let's open Postman, and in the address bar we'll enter the URL of our API: http://<ip_addr>/<config_iris>/rest/service/customer. Enter the authentication data (username and password) to access the API in the Authorization tab:

 

 

Now select the desired verb, GET, and submit the request. This setting will trigger the List method. And then we have as a response an HTTP 200 status and the list of clients.

We can make an inclusion with the call using the POST verb and creating a body for our request. To do this, go to the Body tab and enter the payload that will be sent (in our example {"name":"Pierre", "age":"45"}). Click Send and see the response (HTTP status 200):

 

 

Now we have Pierre's record created in our class. We can fetch the record with the GET by passing the record ID number:

Note that now, in the URL, we enter the ID of the desired record. This causes our API to call the Search method.

So we have our persistent class created, our REST API developed and published in Iris, and it can be safely consumed.

In the next part of this article we will see how we can consume this API through a FLASK application.