%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.
Thanks!
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
https://github.com/drechema/iris-explorer
It did not build in my AWS environment ...
I started my own version of it and imported phoneapp which can be found here:
https://github.com/oliverwilms/iris-explorer
Hi Michael,
You should have one top-level dispatch class which will dispatch individual API calls to separate endpoint classes.
@Sergei Shutov Thank you!
How does one define this in an OpenAPI 2.0 spec?
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,
Amy
Yes but you can have one top-level 'manually created' one and have individual ones based on separate OpenAPI files
Ah OK, great. That sounds promising! I will give that a try.
Thanks for your quick response