· Jul 27, 2022

%REST disp.cls, apps, and packages - How to structure?

After some trials, I am comfortably on my way developing spec first REST APIs using /api/mgmt/, OpenAPI 2.0, testing with Postman.

My question is related to scaling up.

Assume these things:

- Our software is CSP web app and it's web application is '/csp/application'

- I created a new REST enabled web app called '/csp/application/v1' and for my first API I created a spec that defines an endpoint /getTeapots so the endpoint is localhost/csp/application/v1/getTeapots

- Using the /api/mgmt/ endpoint, I loaded the spec into API.TeapotLibrary

- The dispatch class in '/csp/application/v1' thus is 'API.TeapotLibrary.disp'

So that's all good and well.  I'm going add some more GET and POST operations to that spec so our front end people can make beautiful interfaces and operations around our teapots.

Now what do I do when I want to add kettles? And ironStoves? And hotPlates?  I would like to keep things organized in terms of packages so I'd have API.Kettles, API.IronStoves, etc.  But that creates a different dispatch class for each one.  

I would like my end points to all be under the same place so one could call localhost/csp/application/v1/getTeapots or localhost/csp/application/v1/getKettles or localhost/csp/application/v1/getHotPlates, etc.

But I can only list a single dispatch class in '/csp/application/v1'.

What is the solution?

- Make the dispatch class more generic and put potentially hundreds of end points under one dispatch and implementation class?  This seems less than ideal trying to shove everything into one class file.

- Divide my application in sub applications so each set of end points still rolls up to v1? E.g. a web app called '/csp/application/v1/teapots', a web app called '/csp/application/v1/kettles', a web app called '/csp/application/v1/hotplates', etc.  This seems less than ideal now having to manage a large set of endpoints.  By the time we release v5 it's going to be a mess.

- Other ideas?  

Interested to hear how others organize this within IRIS.


$ZV: IRIS for Windows (x86-64) 2020.1.1 (Build 408U) Sun Mar 21 2021 22:04:09 EDT
Discussion (6)3
Log in or sign up to continue

Hi, Michael,

I am interested to see how this can be solved in a good way. First thing came to my mind was to have a more generic table than teapot so multiple categories can be in one table. Then category can be one of the parameters to query on. I like to develop an example we can improve upon.

Are you willing to share your configuration / definition / code?

I looked for an example of API first and I found this app on OpenExchange:

InterSystems Open Exchange

It did not build in my AWS environment ...

I started my own version of it and imported phoneapp which can be found here:

Hi @Michael Davidovich 

We are also developing a library of REST endpoints and have this same question - to which we can't seem to find the answer! Unless I am mistaken (I am new to REST in IRIS) the suggestion made by @Sergei Shutov only works for 'manually created' REST services and not for Open API spec first? As the URL Map for spec first is stored in the .disp class which is automatically generated by the import of the swagger.json so cannot be modified to split the endpoints into different .impl classes?

I would be very interested to know what conclusion you came to for how to structure your REST app so it is scalable. 

Many thanks,