InterSystems IRIS REST Application Patterns

Article

Yuri Marx · Aug 2, 2021 30m read

#REST API #Tutorial #InterSystems IRIS

This article suggests to you some patterns to create REST API applications using IRIS.

Note: source code in https://github.com/yurimarx/movie

Class Pattern to the REST Application

To begin, see my suggestion for classes needed to create IRIS API applications:

IRISRESTApplication: CSP.REST class that will be the central controller for all REST requests and responses processed by the business services.
BusinessService: class with a business topic implementation. It can use one or more Persistent Domain Classes to persist and query data required by the business topic requirements.
Persistent Domain: persistent class to manage a SQL table.

Prereqs

VSCode;
Docker Desktop;
InterSystems ObjectScript Extension Pack.

Class Diagram to the Sample Application

I will create a Movie Catalog application to demonstrate the patterns suggested in the article:

Note: thanks to the https://openexchange.intersystems.com/package/iris-rest-api-template application. It was the base to this tutorial.

Setup the Sample Application

1. Create a folder movie in your file system. Open this folder in a new VSCode window.

2. Create the Dockerfile file inside movie folder to run IRIS Community edition into a Docker container instance. Content:

Docker file content

3. Create the docker-compose.yml file inside movie folder to allows you run your docker instance and other instances together (not in this sample, but it is a good practice run from docker-compose instead dockerfile. Content:

Docker composer content

4. Create the iris.script file inside movie folder to do some actions before run IRIS. This file is important to do custom terminal actions necessary for the application, like disable password expiration. Content:

iris.script content

5. Create the module.xml file inside movie folder to install and run your application using ZPM. This file is important to do the application endpoint configuration and install swagger-ui (web app used to run and test your API using swagger file). Content:

Module.xml content

You can see CSPApplication tag, used to run the application API in the /movie-api URI and enable or disable password to consume the API.

6. Create the LICENSE file inside movie folder to setting the license of your application. Content:

LICENSE content

7. Create the README.md file inside movie folder to document your application to the users using markdown language. Content:

## movie-rest-application

This is a sample of a REST API application built with ObjectScript in InterSystems IRIS.

8. Create .vscode folder inside movie folder. Create settings.json file inside .vscode folder to configure server connection between VSCode and your IRIS instance. Content:

Settings content

9. Create the folder src inside movie folder to put your source code folders and files.

10. Create dc folder inside src folder. This is a convention when your build projects to the InterSystems Developer Community, otherwise is not necessary.

11. Create movie folder inside dc folder. This folder will be the folder to your objectscript classes.

12. Create our first class, MovieRESTApp.cls file, inside src\dc\movie folder. This file will be the IRISRESTApplication class. Content:

MovieRESTApp content

Class dc.movie.MovieRESTApp Extends %CSP.REST

{

Parameter CHARSET = "utf-8";

Parameter CONVERTINPUTSTREAM = 1;

Parameter CONTENTTYPE = "application/json";

Parameter Version = "1.0.0";

Parameter HandleCorsRequest = 1;

XData UrlMap [ XMLNamespace = "http://www.intersystems.com/urlmap" ]

{

</Routes>

}

ClassMethod %ProcessResult(pStatus As %Status = {$$$OK}, pResult As %DynamicObject = "") As %Status [ Internal ]

{

#dim %response As %CSP.Response

SET tSC = $$$OK

IF $$$ISERR(pStatus) {

SET %response.Status = 500

SET tSC = ..StatusToJSON(pStatus, .tJSON)

IF $isobject(tJSON) {

SET pResult = tJSON

} ELSE {

SET pResult = { "errors": [ { "error": "Unknown error parsing status code" } ] }

}

ELSEIF pStatus=1 {

IF '$isobject(pResult){

SET pResult = {

}

ELSE {

SET %response.Status = pStatus

SET error = $PIECE(pStatus, " ", 2, *)

SET pResult = {

"error": (error)

}

IF pResult.%Extends("%Library.DynamicAbstractObject") {

WRITE pResult.%ToJSON()

}

ELSEIF pResult.%Extends("%JSON.Adaptor") {

DO pResult.%JSONExport()

}

ELSEIF pResult.%Extends("%Stream.Object") {

DO pResult.OutputToDevice()

}

QUIT tSC

}

ClassMethod SwaggerSpec() As %Status

{

Set tSC = ##class(%REST.API).GetWebRESTApplication($NAMESPACE, %request.Application, .swagger)

Do swagger.info.%Remove("x-ISC_Namespace")

Set swagger.basePath = "/movie-api"

Set swagger.info.title = "Movie API"

Set swagger.info.version = "1.0"

Set swagger.host = "localhost:52773"

Return ..%ProcessResult($$$OK, swagger)

}

Note 1: The class extends CSP.REST to be used as the REST Endpoint.

Note 2: the parameter chaset is used to encode requests and responses with UTF-8.

Note 3: the CONVERTINPUTSTREAM is used to force the request content in the UTF-8, without this you can have problems with special latin chars.

Note 4: CONTENTTYPE is used to declare the content using JSON, not XML.

Note 5: HandleCorsRequest = 1 is necessary to allows you consume the API from other servers different from the IRIS server.

Note 6: Routes are used to declare API URI to each class method.

Note 7: SwaggerSpec from CSP.REST class allows you generate the API swagger (API web documentation) content.

Now you have the following folders and files:

13. Open VSCode Terminal (menu Terminal > New Terminal) and type:

docker-compose up -d --build

This will build the docker instance and run it.

14. Test your API with Swagger-UI. In the browser and type: http://localhost:52773/swagger-ui/index.html. Pay attention to the address bar (fix the url, if necessary to correct address)

Connection beetween VSCode and IRIS

1. Click in the ObjectScript bar (in the VSCode footer)

2. Select Toogle Connection in the Top:

3. Check the connection status into ObjectScript Explorer (you will be able to see folders and classes created):

Persistent Classes to the Movie Catalog Application

In this section we will create the persistent domain classes to store and query the business data. See the DBeaver Diagram:

1. Create the folder model inside src\dc\movie folder.

2. Create the Actor.cls file inside model folder. Write the content:

Class dc.movie.model.Actor Extends (%Persistent, %JSON.Adaptor)

{

Parameter %JSONREFERENCE = "ID";

Property actorId As %Integer [ Calculated, SqlComputeCode = { set {*}={%%ID}}, SqlComputed ];

Property name As %VarString(MAXLEN = 120);

Property dob As %Date;

Property genre As %Integer(VALUELIST = ",1,2");

}

3. Create the Movie.cls file inside model folder. Write the content:

Class dc.movie.model.Movie Extends (%Persistent, %JSON.Adaptor)

{

Parameter %JSONREFERENCE = "ID";

Property movieId As %Integer [ Calculated, SqlComputeCode = { set {*}={%%ID}}, SqlComputed ];

Property name As %VarString(MAXLEN = 120);

Property releaseDate As %Date;

Property duration As %Integer;

Property imdb As %String(MAXLEN = 300);

Property movieCategory As dc.movie.model.MovieCategory;

ForeignKey MovieCategoryFK(movieCategory) References dc.movie.model.MovieCategory();

}

4. Create the MovieCategory.cls file inside model folder. Write the content:

Class dc.movie.model.MovieCategory Extends (%Persistent, %JSON.Adaptor)

{

Parameter %JSONREFERENCE = "ID";

Property movieCategoryId As %Integer [ Calculated, SqlComputeCode = { set {*}={%%ID}}, SqlComputed ];

Property name As %VarString(MAXLEN = 120);

}

5. Create the Casting.cls file inside model folder. Write the content:

Class dc.movie.model.Casting Extends (%Persistent, %JSON.Adaptor)

{

Parameter %JSONREFERENCE = "ID";

Property castingId As %Integer [ Calculated, SqlComputeCode = { set {*}={%%ID}}, SqlComputed ];

Property movie As dc.movie.model.Movie;

ForeignKey MovieFK(movie) References dc.movie.model.Movie();

Property actor As dc.movie.model.Actor;

ForeignKey ActorFK(actor) References dc.movie.model.Actor();

Property characterName As %String(MAXLEN = 100);

Index CastingIndex On (movie, actor) [ Unique ];

}

See the created files:

Note 1: Parameter %JSONREFERENCE = "ID" allows return ID value inside JSON response.

Note 2: Property actorId As %Integer [ Calculated, SqlComputeCode = { set {*}={%%ID}}, SqlComputed ] and the other similar properties are used to return class+id into JSON response.

Note 3: (VALUELIST = "1,2") set possible values to 1 or 2 only.

Note 4: ForeignKey MovieFK(movie) References dc.movie.model.Movie() and similar are used to create a SQL foreign key reference.

Note 5: Index CastingIndex On (movie, actor) [ Unique ] and similar are used to not allows duplicate values combining properties in the On (movie and actor).

Note 6: I'm using Camel Case to property names because a best practice for JSON attribute names.

Business Service Classes to the Movie Catalog Application

In this section we will create the classes with business logic (methods to do persistence, query and calculations).

1. Create the service folder inside src\dc\movie.

2. Create CrudUtilService.cls file inside service folder. Write the content:

CrudUtilService content

Class dc.movie.service.CrudUtilService Extends %CSP.REST

{

Parameter CHARSET = "utf-8";

Parameter CONVERTINPUTSTREAM = 1;

Parameter CONTENTTYPE = "application/json";

Parameter Version = "1.0.0";

Parameter HandleCorsRequest = 1;

/// Return all the records

ClassMethod GetAll(DomainClass As %Persistent) As %Status

{

#dim tSC As %Status = $$$OK

Set rset = DomainClass.ExtentFunc()

Set %response.ContentType = ..#CONTENTTYPEJSON

Set %response.Headers("Access-Control-Allow-Origin")="*"

Write "["

if rset.%Next() {

Set actor = DomainClass.%OpenId(rset.ID)

Do actor.%JSONExport()

}

While rset.%Next() {

Write ","

Set actor = DomainClass.%OpenId(rset.ID)

Do actor.%JSONExport()

}

Write "]"

Quit tSC

}

/// Return one record

ClassMethod GetOne(DomainClass As %Persistent, id As %Integer) As %Status

{

#dim tSC As %Status = $$$OK

#dim e As %Exception.AbstractException

#; Set the response header to plain text

Set %response.ContentType = ..#CONTENTTYPEJSON

Set %response.Headers("Access-Control-Allow-Origin")="*"

Set domain = DomainClass.%OpenId(id)

If '$IsObject(domain) Quit ..Http404()

Do domain.%JSONExport()

Quit tSC

}

/// Creates a new record

ClassMethod Create(DomainClass As %Persistent) As %Status

{

#dim tSC As %Status = $$$OK

#dim e As %Exception.AbstractException

Set domain = DomainClass.%New()

Set data = {}.%FromJSON(%request.Content)

$$$TOE(tSC, domain.%JSONImport(data))

$$$TOE(tSC, domain.%Save())

Write domain.%JSONExport()

Set %response.Status = 204

Set %response.ContentType = ..#CONTENTTYPEJSON

Set %response.Headers("Access-Control-Allow-Origin")="*"

Quit tSC

}

/// Update a record with id

ClassMethod Update(DomainClass As %Persistent, id As %Integer) As %Status

{

#dim tSC As %Status = $$$OK

#dim e As %Exception.AbstractException

Set domain = DomainClass.%OpenId(id)

If '$IsObject(domain) Return ..Http404()

Set data = {}.%FromJSON(%request.Content)

$$$TOE(tSC, domain.%JSONImport(data))

$$$TOE(tSC, domain.%Save())

Write domain.%JSONExport()

Set %response.Status = 200

Set %response.ContentType = ..#CONTENTTYPEJSON

Set %response.Headers("Access-Control-Allow-Origin")="*"

Quit tSC

}

/// Delete a record with id

ClassMethod Delete(DomainClass As %Persistent, id As %Integer) As %Status

{

#dim tSC As %Status = $$$OK

#dim e As %Exception.AbstractException

Set domain = DomainClass.%OpenId(id)

If '$IsObject(domain) Return ..Http404()

$$$TOE(tSC, domain.%DeleteId(id))

Set %response.Status = 200

Set %response.ContentType = ..#CONTENTTYPEJSON

Set %response.Headers("Access-Control-Allow-Origin")="*"

Quit tSC

}

3. Create MovieService.cls file inside service folder. Write the content:

MovieService content

4. Create MovieCategoryService.cls file inside service folder. Write the content:

MovieCategoryService content

5. Create ActorService.cls file inside service folder. Write the content:

ActorService content

6. Create CastingService.cls file inside service folder. Write the content:

CastingService content

7. Update the file MovieRESTApp.cls to create paths to all new service class methods. Write the content:

MovieRESTApp updated content

Class dc.movie.MovieRESTApp Extends %CSP.REST

{

Parameter CHARSET = "utf-8";

Parameter CONVERTINPUTSTREAM = 1;

Parameter CONTENTTYPE = "application/json";

Parameter Version = "1.0.0";

Parameter HandleCorsRequest = 1;

XData UrlMap [ XMLNamespace = "http://www.intersystems.com/urlmap" ]

{

</Routes>

}

/// List movies

ClassMethod GetAllMovies() As %Status

{

Return ##class(dc.movie.service.MovieService).GetAll()

}

/// Get movie casting

ClassMethod GetMovieCasting(id As %Integer) As %Status

{

Return ##class(dc.movie.service.MovieService).GetMovieCasting(id)

}

/// Get a movie

ClassMethod GetMovie(id As %Integer) As %Status

{

Return ##class(dc.movie.service.MovieService).GetOne(id)

}

// Create a new movie

ClassMethod CreateMovie() As %Status

{

Return ##class(dc.movie.service.MovieService).Create()

}

// Update a movie

ClassMethod UpdateMovie(id As %Integer) As %Status

{

Return ##class(dc.movie.service.MovieService).Update(id)

}

// Delete a movie

ClassMethod DeleteMovie(id As %Integer) As %Status

{

Return ##class(dc.movie.service.MovieService).Delete(id)

}

/// List movies categories

ClassMethod GetAllMovieCategories() As %Status

{

Return ##class(dc.movie.service.MovieCategoryService).GetAll()

}

/// Get a movie category

ClassMethod GetMovieCategory(id As %Integer) As %Status

{

Return ##class(dc.movie.service.MovieCategoryService).GetOne(id)

}

// Create a new movie category

ClassMethod CreateMovieCategory() As %Status

{

Return ##class(dc.movie.service.MovieCategoryService).Create()

}

// Update a movie category

ClassMethod UpdateMovieCategory(id As %Integer) As %Status

{

Return ##class(dc.movie.service.MovieCategoryService).Update(id)

}

// Delete a movie category

ClassMethod DeleteMovieCategory(id As %Integer) As %Status

{

Return ##class(dc.movie.service.MovieCategoryService).Delete(id)

}

/// List actors

ClassMethod GetAllActors() As %Status

{

Return ##class(dc.movie.service.TestActorService).GetAll()

}

/// Get an actor

ClassMethod GetActor(id As %Integer) As %Status

{

Return ##class(dc.movie.service.ActorService).GetOne(id)

}

// Create a new actor

ClassMethod CreateActor() As %Status

{

Return ##class(dc.movie.service.ActorService).Create()

}

// Update an actor

ClassMethod UpdateActor(id As %Integer) As %Status

{

Return ##class(dc.movie.service.ActorService).Update(id)

}

// Delete an actor

ClassMethod DeleteActor(id As %Integer) As %Status

{

Return ##class(dc.movie.service.ActorService).Delete(id)

}

/// List castings

ClassMethod GetAllCastings() As %Status

{

Return ##class(dc.movie.service.CastingService).GetAll()

}

/// Get a casting

ClassMethod GetCasting(id As %Integer) As %Status

{

Return ##class(dc.movie.service.CastingService).GetOne(id)

}

// Create a new casting item

ClassMethod CreateCasting() As %Status

{

Return ##class(dc.movie.service.CastingService).Create()

}

// Update a casting

ClassMethod UpdateCasting(id As %Integer) As %Status

{

Return ##class(dc.movie.service.CastingService).Update(id)

}

// Delete a casting

ClassMethod DeleteCasting(id As %Integer) As %Status

{

Return ##class(dc.movie.service.CastingService).Delete(id)

}

/// General information

ClassMethod GetInfo() As %Status

{

SET version = ..#Version

SET fmt=##class(%SYS.NLS.Format).%New("ptbw")

SET info = {

"Service": "Movie API",

"version": (version),

"Developer": "Yuri Gomes",

"Status": "Ok",

"Date": ($ZDATETIME($HOROLOG))

}

Set %response.ContentType = ..#CONTENTTYPEJSON

Set %response.Headers("Access-Control-Allow-Origin")="*"

Write info.%ToJSON()

Quit $$$OK

}

ClassMethod %ProcessResult(pStatus As %Status = {$$$OK}, pResult As %DynamicObject = "") As %Status [ Internal ]

{

#dim %response As %CSP.Response

SET tSC = $$$OK

IF $$$ISERR(pStatus) {

SET %response.Status = 500

SET tSC = ..StatusToJSON(pStatus, .tJSON)

IF $isobject(tJSON) {

SET pResult = tJSON

} ELSE {

SET pResult = { "errors": [ { "error": "Unknown error parsing status code" } ] }

}

ELSEIF pStatus=1 {

IF '$isobject(pResult){

SET pResult = {

}

ELSE {

SET %response.Status = pStatus

SET error = $PIECE(pStatus, " ", 2, *)

SET pResult = {

"error": (error)

}

IF pResult.%Extends("%Library.DynamicAbstractObject") {

WRITE pResult.%ToJSON()

}

ELSEIF pResult.%Extends("%JSON.Adaptor") {

DO pResult.%JSONExport()

}

ELSEIF pResult.%Extends("%Stream.Object") {

DO pResult.OutputToDevice()

}

QUIT tSC

}

ClassMethod SwaggerSpec() As %Status

{

Set tSC = ##class(%REST.API).GetWebRESTApplication($NAMESPACE, %request.Application, .swagger)

Do swagger.info.%Remove("x-ISC_Namespace")

Set swagger.basePath = "/movie-api"

Set swagger.info.title = "Movie API"

Set swagger.info.version = "1.0"

Set swagger.host = "localhost:52773"

Return ..%ProcessResult($$$OK, swagger)

}

8. The files and folders to the final project are:

9. Test your new methods acessing http://localhost:52773/swagger-ui/index.html.

Note 1: REST paths are following business topic in plural with /id when we need pass id to the entity and camel case to paths to.

Note 2: We use verb GET to queries, POST to new records, PUT to update record and DELETE to delete a record.

Note 3: In <Route Url="/movies/casting/:id" Method="GET" Call="GetMovieCasting" /> I used /casting indicating a second purpose (get the movie and it casting). This method runs ToJSON(), because is a DynamicArray ([]) with Dynamic items ({}).

Note 4: I created the CrudUtilService class utility to do generic CRUD methods, following the Dont Repeat Yourself principle.

Enjoy this tutorial!