Exposing a Basic REST API with InterSystems IRIS: Step-by-Step Docker Example

Introduction

InterSystems IRIS allows you to build REST APIs using ObjectScript classes and the %CSP.REST framework. This enables the development of modern services to expose data for web apps, mobile apps, or system integrations.

In this article, you'll learn how to create a basic REST API in InterSystems IRIS, including:

• A persistent data class
• A REST class with GET and POST methods
• A web application to expose the API
• A full demonstration using Docker

Step 1: Create the data class Demo.Producto

Class Demo.Producto Extends (%Persistent, %JSON.Adaptor) {
  Property Nombre As %String;
  Property Precio As %Numeric(10,2);
}

• %Persistent allows storing the object in the database.
• %JSON.Adaptor enables automatic JSON conversion.

Step 2: Create the REST class Demo.ProductoAPI

Class Demo.ProductoAPI Extends %CSP.REST {

XData UrlMap [ XMLNamespace = "http://www.intersystems.com/urlmap" ] {
  <Routes>
    <Route Url="/producto" Method="GET" Call="Listar"/>
    <Route Url="/producto" Method="POST" Call="Crear"/>
  </Routes>
}

ClassMethod Listar() As %Status
{
   Try {
    Set productos = []
    &sql(DECLARE C1 CURSOR FOR SELECT ID, Nombre, Precio FROM Demo.Producto)
    &sql(OPEN C1)
    While (SQLCODE=0) {
      &sql(FETCH C1 INTO :id, :nombre, :precio)
      Quit:SQLCODE'=0
      Do productos.%Push({"ID": (id), "Nombre": (nombre), "Precio": (precio)})
    }

    Do ##class(%REST.Impl).%SetContentType("application/json")
    Do ##class(%REST.Impl).%SetStatusCode("200")
    Write productos.%ToJSON()
    } Catch (ex) {
        Do ##class(%REST.Impl).%SetStatusCode("400")
       Write ex.DisplayString()
    }
  Quit $$$OK
}

ClassMethod Crear() As %Status
{
  Try {
    set dynamicBody = {}.%FromJSON(%request.Content)
    Set prod = ##class(Demo.Producto).%New()
    Set prod.Nombre = dynamicBody.%Get("Nombre")
    Set prod.Precio = dynamicBody.%Get("Precio")
    Do prod.%Save()

    Do ##class(%REST.Impl).%SetContentType("application/json")
    Do ##class(%REST.Impl).%SetStatusCode("200")
    Write prod.%JSONExport()
    } Catch (ex) {
        Do ##class(%REST.Impl).%SetStatusCode("400")
       Write ex.DisplayString()
    }
    Quit $$$OK
}

}

Step 3: Create a Web Application

From the Management Portal:

1. Go to System Administration > Security > Applications > Web Applications
2. Create a new application:
   • URL: /api/productos
   • Namespace: USER
   • Class: Demo.ProductoAPI
   • Enable REST and anonymous access for testing

http://localhost:52773/csp/sys/%25CSP.Portal.Home.zen  User=SuperUser Pass=SYS

Add Developer Application Functions

Step 4: Docker demonstration

Project structure

apirest-demo/
├── Dockerfile
├── iris.script
└── cls/
    ├── Demo.Producto.cls
    └── Demo.ProductoAPI.cls

Dockerfile

FROM intersystemsdc/iris-community:latest

COPY cls /irisdev/app/cls
COPY iris.script /irisdev/app/iris.script

RUN iris start IRIS \
 && iris session IRIS < /irisdev/app/iris.script \
 && iris stop IRIS quietly

Build and run the container

cd apirest-demo
docker build -t iris-apirest-demo .
docker run -d --name iris-api -p 52773:52773 -p 1972:1972 iris-apirest-demo

Testing with Postman or curl

GET products

curl http://localhost:52773/api/productos/producto

POST product

curl -X POST http://localhost:52773/api/productos/producto \
  -H "Content-Type: application/json" \
  -d '{"Nombre":"Cafe","Precio":2500}'

to download the example code https://github.com/MarcoBahamondes/apirest-demo

git clone https://github.com/MarcoBahamondes/apirest-demo