Michael Davidovich · Jul 27

%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
0 198
Discussion (3)2
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,

You should have one top-level dispatch class which will dispatch individual API calls to separate endpoint classes.

<!-- teapots -->
<Map Prefix="/teapots" Forward="REST.Teapots"/>
<!-- kettles -->
<Map Prefix="/kettles" Forward="REST.Kettles"/>