RESTful on IBM i

This Q&A forum allows users to post and respond to "How Do I Do ....." questions. Please do not use to report (suspected) errors - you must use your regional help desk for this. The information contained in this forum has not been validated by LANSA and, as such, LANSA cannot guarantee the accuracy of the information.
Post Reply
atostaine
Posts: 562
Joined: Wed Jan 20, 2016 7:38 am

RESTful on IBM i

Post by atostaine » Thu Jul 09, 2020 3:40 am

I recall seeing documentation that a windows server is required to publish REST from LANSA. Is that true? Has it been made available on IBM i in V15? Thanks
Art Tostaine

jimwatterson
Posts: 20
Joined: Thu Jul 09, 2020 8:31 am

Re: RESTful on IBM i

Post by jimwatterson » Thu Jul 09, 2020 8:47 am

Using the new API facility still requires an external web server (definitely Windows but also Linux I believe). I have been told that direct iSeries support support is on the road-map and this year was mentioned. I believe this requirement is related to the need to use RESTful looking urls e.g.

https://myserver.com.au/prd/MySchoolSer ... ch='sydney'

which needs to be converted into a lansaweb wam call.

I assume this will require a custom apache module.

We have been playing around with in the last few days and it seems pretty impressive. There is a useful course on LANSA Learn which makes up for the sparsity of the documentation. We need to get our heads around the security implementation (and there is a LANSA Learn course covering this pending, I am told) and hopefully we can get something robust and industry standard.

We will be going down the path the windows server for proof of concept testing but ultimately we want to run everything off our iSeries so we will be pushing for that.

This product seems to have been gestating for 4-5 years so its nice to finally see it approaching usability.

atostaine
Posts: 562
Joined: Wed Jan 20, 2016 7:38 am

Re: RESTful on IBM i

Post by atostaine » Thu Jul 09, 2020 9:01 am

I doubt we will deploy a windows or Unix server for this add me to the +1 list for IBM i deployment
Art Tostaine

jimwatterson
Posts: 20
Joined: Thu Jul 09, 2020 8:31 am

Re: RESTful on IBM i

Post by jimwatterson » Thu Jul 09, 2020 9:24 am

I'll add to this thread whenever I hear something.

atostaine
Posts: 562
Joined: Wed Jan 20, 2016 7:38 am

Re: RESTful on IBM i

Post by atostaine » Thu Jul 09, 2020 10:05 am

Thanks.

I’ve told my customer I can write it in RPG as well.
Art Tostaine

jyoung
Posts: 690
Joined: Thu Jan 21, 2016 6:43 am
Location: Oklahoma City, OK USA

Re: RESTful on IBM i

Post by jyoung » Thu Jul 09, 2020 11:45 pm

We have a REST API in production on the IBM i, but as others have mentioned, you must have a Windows IIS server in front of it.

Interestingly, you don't actually do anything with it once you get the LANSA bits on it, it just proxies the request through.

One word of caution I would tell anyone who is thinking about deploying an API on the IBM i (besides the aforementioned Windows Server) is the need to understand the webmodules.conf file. This may have (hopefully) changed in v15 but I have not seen any documentation regarding it.

If you are "checking-in" to Production then its not that big of an issue, but if you check in into a DEVELOPMENT server and then export / import to a PRODUCTION server, you have to manually edit the PRODUCTION webmodules.conf file. I have not seen any documentation on this file and all I know is from support. This file is a JSON file that maps URL to Server Modules. When you check-in the file gets automatically updated, but I have yet to see this in an export / import scenario. I don't know if you can export / import the conf file, but manually editing the file in PROD is complete PIA, especially as you add more endpoints to the file.

Joe

jimwatterson
Posts: 20
Joined: Thu Jul 09, 2020 8:31 am

Re: RESTful on IBM i

Post by jimwatterson » Fri Jul 10, 2020 8:42 am

Joe

We are keen to set up a Windows server to access the iSeries but cannot find any information on how to configure this. I have contact support am still waiting for a response. Can you point me at any documentation?

Cheers
Jim

BrendanB
Posts: 45
Joined: Tue Nov 24, 2015 10:29 am

Re: RESTful on IBM i

Post by BrendanB » Fri Jul 10, 2020 8:52 am

Jim,

try here:

https://www.lansa.com/downloads/support ... -multi.pdf

I have used this guide successfully at with a few sites.

Additionally,

if you add something like:

Code: Select all

"map": [                      
  {                           
    "aliases": [              
      "WEBSERVICES/swaggerV2" 
    ],                        
    "method": "Get",          
    "module": "WEBSERVIC",    
    "routine": "*SwaggerV2"   
  },                          
  {                           
    "aliases": [              
      "WEBSERVICES/openApiV3" 
    ],                        
    "method": "Get",          
    "module": "WEBSERVIC",    
    "routine": "*OpenApiV3"   
  },                     
  
at the start of the 'map' section of the webmodules.conf file, (substitute 'WEBSERVIC' for the Identifier of your ServerModule that has the APIs in it) then you are able to get at the swagger and openApi maps... these can be used in the swagger.io editor (as one example) to show customers how to use your API.

Im not sure that is documented anywhere.

Brendan.

jimwatterson
Posts: 20
Joined: Thu Jul 09, 2020 8:31 am

Re: RESTful on IBM i

Post by jimwatterson » Fri Jul 10, 2020 9:10 am

Thanks Brendan - that's my Friday afternoon project sorted!

jimwatterson
Posts: 20
Joined: Thu Jul 09, 2020 8:31 am

Re: RESTful on IBM i

Post by jimwatterson » Fri Jul 10, 2020 9:24 am

I'm pretty sure that Other LANSA stuff is already installed. What I don't understand is what url I use to access an API Server Module on the iSeries. If I'm doing this from my desktop I access the webserver via localhost from Postman - how does this work with this set up?

jimwatterson
Posts: 20
Joined: Thu Jul 09, 2020 8:31 am

Re: RESTful on IBM i

Post by jimwatterson » Fri Jul 10, 2020 9:29 am

Hold on I just found some more pages on the printer!

jyoung
Posts: 690
Joined: Thu Jan 21, 2016 6:43 am
Location: Oklahoma City, OK USA

Re: RESTful on IBM i

Post by jyoung » Fri Jul 10, 2020 11:38 pm

Hey Jim,

You won't access the url from on the iSeries. You access the url from the Windows Proxy, which will call the corresponding ServerModule on the iSeries.

On your Windows Server, IIS will be installed and should be handling all the requests. The LANSA install on the Windows Server will install an ISAPI module that will handle the mapping to the iSeries.

The url would be the host (and port) of the windows box, with the path defined in the API Definition of the module.

For example, if the Windows server is MYSERVER and is listening on port 8080,
Paths are defined as
paths.PNG
paths.PNG (17.58 KiB) Viewed 3359 times
So the url would be

Code: Select all

http://myserver:8080/sys/us/1/associates/workforce/12345/link
Hope this helps,
Joe

jimwatterson
Posts: 20
Joined: Thu Jul 09, 2020 8:31 am

Re: RESTful on IBM i

Post by jimwatterson » Mon Jul 13, 2020 2:01 pm

Thanks for the feedback Joe. I was struggling to work out how this works but I think I've got enough to go on now.

jimwatterson
Posts: 20
Joined: Thu Jul 09, 2020 8:31 am

Re: RESTful on IBM i

Post by jimwatterson » Wed Jul 15, 2020 3:52 pm

I've setup a Windows 2019 server and installed IIS. I can see the IIS Welcome page when I go to my host name. I've installed the LANSA server extensions as per the document supplied and passed all the tests. In postman when I call the url

http://tstnesaapi/v40/MyServiceName/Status

I'm getting a 404 page from IIS. The url works from Postman If I go to local host and I've ensured that the server module is checked in but the call is not being redirected to the right spot.

Is there another configuration step that I've missed. Is there any tracing/error data anywhere on the iis server

Thanks
Jim

jyoung
Posts: 690
Joined: Thu Jan 21, 2016 6:43 am
Location: Oklahoma City, OK USA

Re: RESTful on IBM i

Post by jyoung » Wed Jul 15, 2020 11:48 pm

Hey Jim,

Have you been able to access the xvlwebtst.html from your server?
For example, localhost:{port}/{pgmlib}/{partition}/xvlwebtst.html

you should get blue LANSA box that states the web server is running.
If that works, then try out of localhost such as tstnesaapi:{port}/{pgmlib}/{partition}/xvlwebtst.html.

If both of those work, and the button that states "Send Request to Application Server" works, then I would assume the Windows Server IIS extension is working properly. So the next thing I would check is the webmodules.conf file.

This will be on your IBM i, in the install directory/run/conf folder.
That file should have a "map" object that has an alias of the path you defined in the API Definition
For example

Code: Select all

  "map": [
    {
      "aliases": [
        "/sys/myservice/status"
      ],
      "method": "Get",
      "module": "ASCAPIS01",
      "routine": "GetV1"
    },
Then you should be able to use that alias to test from you windows server, i.e. tstnesaapi:{port}/sys/myservice/status.

In regards to the logs for IIS, the only one I know of is the lansaweb.log at C:\Program Files (x86)\LANSA\log but I don't think its of much help.
As far as I know, if the xvlwebtst.html page works, the IIS extension is working, so any other log would be the typical logs on the IBM i (x_err.log etc.).

Hope this helps,
Joe

jimwatterson
Posts: 20
Joined: Thu Jul 09, 2020 8:31 am

Re: RESTful on IBM i

Post by jimwatterson » Thu Jul 16, 2020 8:27 am

Thanks for the info Joe. Turns out we didn't have port 8080 open in the firewall!

I often find that when we're doing something new and it doesn't work you end up looking for new problems rather than the obvious stuff!

Anyway we've made great progress being able to talk to the iseries.

This API support has come at a good time - I'm being asked about exposing APIs every week now and it now looks like we've got the tools to respond with at last.

Now I need to get a handle on security & access control and we'll be in business.

Cheers
Jim

jyoung
Posts: 690
Joined: Thu Jan 21, 2016 6:43 am
Location: Oklahoma City, OK USA

Re: RESTful on IBM i

Post by jyoung » Fri Jul 17, 2020 1:57 am

LOL, I can't tell you how many rabbit holes I have been down only to find out there was a port that was not open.

Glad you got it worked out.

Joe

jimwatterson
Posts: 20
Joined: Thu Jul 09, 2020 8:31 am

Re: RESTful on IBM i

Post by jimwatterson » Thu Jul 30, 2020 10:08 am

Just a progress report on this.

We got the Windows IIS server up and running and LANSA configured pretty quickly using Brendan's document. The generated code ran out of the box for simple use cases (eg get a list of items) but we did run into some issues with PUT requests. These ran OK on windows but crashed on the iseries. The good news here is that we were able to get a hotfix very quickly for this issue. We also ran into a problem trying to create JWT tokens on the iseries but again a hotfix was made available in very short order so we are able to continue to make progress.

As I think I mentioned before this tool has arrived at a moment when everybody seems to want REST APIs for various data requirements and its fantastic to be able to deliver them in an industry best practice way. The iSeries implementation seems to be slightly under tested but support have been very responsive in knocking over the problems as fast as we can discover them. We hope soon to have fully functional working examples pretty soon and hopefully LANSA can bundle up these hotfixes into an EPC.

All you iSeries people out there should have a look at this tool

Cheers
Jim

Speedlime
Posts: 2
Joined: Wed Feb 03, 2021 2:52 am

Re: RESTful on IBM i

Post by Speedlime » Fri Feb 12, 2021 10:02 pm

Morning,

I have been following this thread and implemented the steps to setup the environment to publish rest api's.

In the upgrade to V15 included LANSA for the WEB and created a local web instance in the development IDE install, ie on laptop with sql and iis. All the test web test pages are found (web tests in the IDE LANSA options) and I can connect to local app/db server (xvlwebsest), which is the iis on the laptop. Create an API, and I am able to call it from browser ie localhost and I can call it from postman.

So moved to setting up a new instance on laptop to test what I am going to do on the window web server. Installed using instructions mentioned in thread, and pointed the instance to the iSeries, and dcxpgmlib. In the web admin I can connect via test button, I have a website in the iis and I can run the web test on the web admin. I can access http://localhost:8081/dcxpgmlib/dev/xvlwebtst.html but when a click the button to send request to application server it fails fatal error. All latest EPC's added client and server side. Listener up and running port 4545. PWB/LXX license on iSeries.

Something is missing, as I expect this to work out of the box. Any suggestion as to what to check or look for, will be most helpful.

Also, from the thread it seems that you need to put the the webmodules.conf file onto the windows web server. ie the run folder. Is this a deployment package job or do you do this manually ?? Cannot find any documentation of this part of the process.

Any help or suggestions will be most welcome
Thanks
Leon

Speedlime
Posts: 2
Joined: Wed Feb 03, 2021 2:52 am

Re: RESTful on IBM i

Post by Speedlime » Thu Feb 18, 2021 11:58 pm

Got it working. Some things to take note of if you are going to do this.

/LANSA_dcxpgmlib/webserver/www/conf - httpd.conf In here it will tell you what profile has access to connect and run Web Admin app. ServerUserID = xxxxxxxx

When the Web Admin is connected from the server to the iSeries, make sure to configure all setting enable partition and run web test.
Setup user registration. partition specific Web user Id, using a profile you create with the appropriate Jobd to run jobs in DEV. This is used in the LWEB_Job instance in the listener.

Once configured you can run
http://localhost:8080/dcxpgmlib/dev/xvlwebtst.html from your webserver to test connection and request to App Server on iSeries.

For API endpoint definitions, copy the webmodules.conf out of your development instance (run/conf) and upload it to the IFS LANSA_dcxpgmlib/run/conf folder. This is to make sure you have the latest version there.

Post Reply