Rest APIs for beginners

Question

Question

Rochdi Badis · Oct 13, 2022

Hi Guys,

I'm really not that familiar with Rest APIs in Ensemble and came across one while investigating some issues.

I got the below code which I'm guessing that is a Rest API that provide services that can be accessed providing url and would like to understand it and my question is, does this url http://52.24.106.151:80/Csp/Upload/CreateRoute/Bmc means that someone use it to run cmCreateRouteBmcDev classmethod for example and does POST means we can send a request or we can receive a request (a post), this MSDS.BluMicello.InterfaceServices class has a list of class methods and cmCreateRouteBmcDev is one of them?

this API is used by one of our clients to send data to us and we've given them a URL in the past to be able to do so but they can't remember the url and I'm not that familiar with this, so normally does the url should be just the route url eg. http://52.24.106.151:80/Csp/Upload or do they nedd the exact call to a specific method be able to send data eg.http://52.24.106.151:80/Csp/Upload/CreateRoute/Bmc ?

Include MSDSInclude

// Provide a REST interface to the document server service
Class MSDS.BluMicello.InterfaceServices Extends %CSP.REST
{

// http://localhost:57772/Csp/Upload/LocEquipUpload

// http://52.24.106.151:80/Csp/Upload/CreateRoute/BmcDev
XData UrlMap [ XMLNamespace = "http://www.intersystems.com/urlmap" ]
{
<Routes>
<Route Url="/LocEquipUpload" Method="POST" Call="cmCreateRoute"/>
<Route Url="/CreateRoute/BmcDev" Method="POST" Call="cmCreateRouteBmcDev"/>
<Route Url="/CreateRoute/BmcPlayGround" Method="POST" Call="cmCreateRouteBmcPlayGround"/>
<Route Url="/CreateRoute/BmcTesting" Method="POST" Call="cmCreateRouteBmcTesting"/>

any info will be helpfull

Thanks Guys

Product version: Caché 2014.1

Discussion (4)1

Log in or sign up to continue

score 0 · Answer 1 · 2022-10-13T13:18:44-04:00

There should be a web application defined in your Caché/Iris server that calls the class MSDS.BluMicello.InterfaceServices (in the field REST Dispatch class).
The web application is probably called /Csp/Upload and will define the first part of the url after the domain (/Csp/Upload).

(In theory you could have more that one web application that handle each part of the url part).

Your customer should use the complete url :

e.g. POST http://52.24.106.151:80/Csp/Upload/CreateRoute/BmcDev

This url will call your classmethod cmCreateRouteBmcDev

The :80 in your url implies you are using a separate webserver that internally will connect to your Caché/Iris server.

score 0 · Answer 2 · 2022-10-13T18:33:54-04:00

Thanks you very much Danny that really helped.

but not sure what you meant by :"The :80 in your url implies you are using a separate webserver that internally will connect to your Caché/Iris server."

isn't :80 means the port, and if I would like to set a url to only grant access through a specific port where do I configure that?

Thanks

score 1 · Answer 3 · 2022-10-14T09:02:51-04:00

Caché/Iris normally use a port like 57772 which goes to the Apache web server that was installed together with Caché/Iris. This web server is best used only for internal usage. In your example the localhost url uses this to acess the service locally when you try that on the server itself.
Because you cannot configure that Apache server for security, you have to use an external webserver where you can completely configure the access (together with the firewall).
An external webserver like IIS or the full blown Apache usually uses 80 as the default public port. In your example you mention the port 80 in with http://52.24.106.151:80/Csp/Upload/CreateRoute/Bmc.
So that's why i think there was an external webserver installed, and you will have to start there if you want to set access rights. (You can also use the firewall to limit any unwanted ip addresses)

Another thing : this class is for receiving REST calls, if you want to send a POST from Cache/Iris, you would have to use the %HtppRequest class.

score 0 · Answer 4 · 2022-10-14T09:37:49-04:00

@Rochdi Badis in addition to what Danny mentioned here, if you see a part of a URL that starts with a colon in the url map, that part of the url is going to be passed as an argument to the method listed in Call. For example, I'm working on an API for an ERP system, and I've got an endpoint that can be called to get a customer record. The route in the url map is defined as:

<Route Url="/customer/:cust" Method="GET" Call="RequestCust" />

The RequestCust method is defined as:

ClassMethod RequestCust(cust As %String) As %Status

So if a user sends a request to /customer/123456, that gets passed to the RequestCust method with 123456 as the cust argument, and they get customer record 123456. If they send the request to /customer/999999, they get customer record 999999.