Publishing Web Services

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
jyoung
Posts: 652
Joined: Thu Jan 21, 2016 6:43 am
Location: Oklahoma City, OK USA

Publishing Web Services

Post by jyoung » Fri Oct 12, 2018 4:12 am

Trying to explore the API Definition stuff.

First, is there documentation on how to set this up?
The only thing I have found so far is this link. https://docs.lansa.com/14/en/lansa004/i ... 2_0040.htm

Second, that link states that a Windows or Linux server is required. You mean I can't publish an API if I am running on an iSeries?

Joe

Pablo
Posts: 43
Joined: Wed Dec 02, 2015 10:35 am

Re: Publishing Web Services

Post by Pablo » Fri Oct 12, 2018 8:21 am

Hi Joe,

There is a tutorial being finalized but in the meantime, attached is a quick export of a web page and server module.
It uses the xContacts table shipped with the demonstration material and the examples use Get/Put/Delete of one or more Contacts.
Any problems please let us know, thanks.
Regards,
Pablo
Attachments
xDemoWebServicesLiveDemo.zip
(25.66 KiB) Downloaded 136 times

Pablo
Posts: 43
Joined: Wed Dec 02, 2015 10:35 am

Re: Publishing Web Services

Post by Pablo » Fri Oct 12, 2018 8:27 am

PS: You need v14 SP2 + EPC142010

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

Re: Publishing Web Services

Post by jyoung » Fri Oct 12, 2018 8:43 am

Hey Pablo,

Thanks for that, I will dig into it.

Any word on whether or not it will be available on the iSeries?

Many Thanks,
Joe

Pablo
Posts: 43
Joined: Wed Dec 02, 2015 10:35 am

Re: Publishing Web Services

Post by Pablo » Fri Oct 12, 2018 11:10 pm

Hi Joe,

Yes ... I think it's available now but you need EPC142010.

Pablo

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

Re: Publishing Web Services

Post by jyoung » Sat Oct 13, 2018 2:11 am

Hi Pablo,

Having an interesting problem. I keep getting an error

Code: Select all

{"error":{"messages":["X_COMP returned error code 22. Check X_ERR.LOG for more information."]}}
The fact that I am getting JSON back tells me something is working.

Checking the Error Log I find

Code: Select all

Fri Oct 12 09:56:48 2018 
Version 14.2.0 Build 4158 Windows 10 Enterprise Edition (10.0.0.0 Build 14393)
---LANSA Installation/Upgrade 14.2.0 Build: 4158 (5/11/2018 4:31:05 PM)
---EPC (14-05-2018 10:06:42)
---EPC (14-05-2018 10:21:44)
---EPC (14-05-2018 10:50:44)
---EPC (16-05-2018 11:09:05)
---EPC (11-07-2018 10:47:23)
---EPC142010 (Visual LANSA V14 SP2 first EPC)
---EPC142012 (LANSA Communications V14 SP2 fixes)
---EPC142013 (LANSA Web Server V14 SP2 fixes)
---EPC (15-08-2018 07:51:40)
---EPC (12-10-2018 09:28:46)
Message : Unable to load/locate module XDEMOW_94 or the module is not a LANSA component.
Routine : File LpCrRt at line 1144.
Job Number: 011996 OS User : LANSA
DBII=LANSAVCS DBUT=MSSQLS GUSR=QOTHPRDOWN PROC=*WSTP W3ST=1 WSIF=handle(4) WSCX=5 PART=toh LANG=ENG
ROOT=C:\Program Files (x86)\LANSAVCS\x_win95
XDEMOW_94 is the identifier of the Server Module and it's compiled. Thinking it may be something the with the import, I created another ServerModule and put up a skeleton routine. When I invoke it from the browser I get the same error.

Not sure what is going on here. I started digging around and I noticed that the complied file drops the first character off the file. Don't know if this is an issue or not. But for the Module XDEMOW_94 the generated files are DEMOW_94.
Capture.PNG
Capture.PNG (48.5 KiB) Viewed 9737 times
Is this an issue?

Pablo
Posts: 43
Joined: Wed Dec 02, 2015 10:35 am

Re: Publishing Web Services

Post by Pablo » Sat Oct 13, 2018 6:46 am

Hi Joe,

Sorry, I don't know what's going on there.

Dropping the first character is not a problem or should not be as it's been like this for a long time for components with names > 8 chars.

Your screen shot shows the source folder ... have you looked for the .DLL in the execute folder, for example:
DLL.PNG
DLL.PNG (2.15 KiB) Viewed 9732 times
Other than that please contact support. If I find something in the meantime I'll send you an email.

Regards,
Pablo

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

Re: Publishing Web Services

Post by jyoung » Sat Oct 13, 2018 7:30 am

Hey Pablo,

Yeah the DLL is there (have the wrong one highlighted, but you can see the _94 one)
Capture2.PNG
Capture2.PNG (24.31 KiB) Viewed 9730 times
I my other test LANSA loaded the module just fine and I can execute the normal server routines with it.
Its when I try to access the API routine through a standard request (browser, postman etc) that I get the error.

Will contact support and see what they say.

Thanks!
Joe

PierreLefrancois
Posts: 23
Joined: Wed Nov 09, 2016 3:02 am

Re: Publishing Web Services

Post by PierreLefrancois » Fri Dec 14, 2018 12:17 am

Hello Joe,

On this topic, did you get further and managed to publish your WebServices on the IBM i ?

If so, did you get access to some documentation?

When I run Pablo's example against our IBM i server, I get: "Method Not Allowed" - "Have you defined /xContacts in your Server Modules". If I try to access it from Postman, I get a similar message that basically tells me that /xContacts is not found on the server.

I checked-in and compiled this Server Module successfully. Is there anything else that needs to be done to publish the services contained in the Server Modules? Maybe with the Apache configuration?

Hopefully, a more detailed guide is provided soon for publishing Web Services.

Thanks - Pierre

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

Re: Publishing Web Services

Post by jyoung » Fri Dec 14, 2018 1:21 am

Hi Pierre,

I am still having problems with running locally, now I am getting random x_run errors with not much (any) logging.

Oddly enough, yesterday I talked with some folks at LANSA Chicago and they mentioned that you cannot run this on the IBM i. The reason being is that the web server is CGI based.

The solution then would be to stand up a Windows IIS webserver that forwards requests to the IBM i. I assume much like the multi-tier setup, we did not discuss implementation details. They did mention they were working on getting it to work on the IBM i, but no word on timing.

No other documentation that I can find or have access to.

I don't know what the plan with publishing web services is, but it would be nice to get some guidance / feedback from LANSA.

Joe

PierreLefrancois
Posts: 23
Joined: Wed Nov 09, 2016 3:02 am

Re: Publishing Web Services

Post by PierreLefrancois » Fri Dec 14, 2018 1:35 am

Joe,

Based on discussions in this thread, it looks like EPC142010 is needed to get this to work on the IBM i.

Would love to have an official statement regarding this.

Pierre

LANSASupport
Posts: 11
Joined: Fri Jun 23, 2017 11:08 am

Re: Publishing Web Services

Post by LANSASupport » Thu Dec 20, 2018 5:46 pm

Hi Pierre

The option to use an IBM web server is not available at any EPC level.

The V14 SP2 documentation contains the following
https://docs.lansa.com/14/en/lansa004/i ... s%7C_____2
Publish RESTful Web Services
LANSA developers can now develop RESTful web services using RDML. A Windows or a Linux web server is required.

So, you must use a mixed multi tier setup with Windows or Linux as the web server to an IBM i backend D/A server. Using an IIS web server (for example) will work OK and has been tested.

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

Re: Publishing Web Services

Post by jyoung » Fri Dec 28, 2018 2:11 am

Finally got this hooked up and working.

First off, if you are using an IBM i, you MUST setup a Windows / Linux web server to act as a front end.
I followed these instructions and it went well. https://docs.lansa.com/14/en/lansa085/i ... 0020ws.htm

Secondly, after talking with support, I think the API Definition is pretty much ALL meta data used to build the Swagger / Open API docs. However where those docs get generated is still unknown.

IMHO, the way the API Definition is displayed, it implies you are defining your API; complete with security and object definitions. This does not seem to be the case. I've also had numerous IDE crashes when trying to enter a route/path parameter. If you define security requirements, parameters etc. you will not get anything in the code, YOU MUST code it all your self, i.e. reading / validating header params, path params etc.

The only thing of interest is the Path which allows you to map a URL to a Server Module and Routine. After digging through the file system (again no docs on this), a webmodules.conf file is generated in the LANSA_install/run/conf folder. This conf file is a JSON file that contains the mappings.

NOTE
If you edit this file yourself, the next time you compile your Server Module, your changes will be overwritten! This brings up a catch however. If you try to add a parameter to the the path using the API Definition the IDE crashes (at least for me). If you add the parameter to the conf file, your changes disappear when you compile the Server Module.

Here is my file with the demo maps and the two mappings I added at the bottom, after the module has been compiled

Code: Select all

{
  "-auto-alias": false,
  "default": {
    "language": "ENG",
    "partition": "dem"
  },
  "realms": {},
  "map": [
    {
      "aliases": [
        "/xContact/{ContactId}"
      ],
      "method": "Get",
      "module": "XDEMOW_94",
      "routine": "GetContact"
    },
    {
      "aliases": [
        "/xContact/{ContactId}"
      ],
      "method": "Put",
      "module": "XDEMOW_94",
      "routine": "PutContact"
    },
    {
      "aliases": [
        "/xContact/{ContactId}"
      ],
      "method": "Delete",
      "module": "XDEMOW_94",
      "routine": "DeleteContact"
    },
    {
      "aliases": [
        "/xContacts"
      ],
      "method": "Get",
      "module": "XDEMOW_94",
      "routine": "GetContacts"
    },
    {
      "aliases": [
        "/xContacts"
      ],
      "method": "Put",
      "module": "XDEMOW_94",
      "routine": "PutContacts"
    },
    {
      "aliases": [
        "/sys/offices"
      ],
      "method": "Get",
      "module": "MGSOFCS02",
      "routine": "GetOffices",
      "partition": "sys"
    },
    {
      "aliases": [
        "/sys/offices/{number}"
      ],
      "method": "Get",
      "module": "MGSOFCS02",
      "routine": "GetOffice",
      "partition": "sys"
    }
  ]
}
The other thing to note, is that this file DOES NOT get generated automatically when you check in the server module. You must copy this file to your server (in my case the IBM i) with the same path.

After you have established the web server and it can successfully talk to your application server (IBM i) and you have uploaded the webmodules.conf file to the IBM i, you should be able to access the path defined in the module.

Don't forget to enable the port on your web server! I had to create a rule to allow inbound 8080 requests.

Now I can go to my web server url such as http://mywebserver:8080/sys/offices/1002 and it will invoke the GetOffice Routine in the MGSOFCS02 Module.

Hope this helps,
Joe

BTW: I really hope LANSA takes this a step further and
  1. improves the documentation
  2. improves the API Definition tab
  3. provide hooks / resources to do automatic security validation, documentation, field / parameter binding etc.

PierreLefrancois
Posts: 23
Joined: Wed Nov 09, 2016 3:02 am

Re: Publishing Web Services

Post by PierreLefrancois » Thu Jan 10, 2019 3:18 am

Ok thanks for sharing.

I also managed to publish on the IBM i with the technique you described and a bit of help from support.

I will dig deeper into this in the coming weeks and I will try to share my experiences also.

Pierre

PierreLefrancois
Posts: 23
Joined: Wed Nov 09, 2016 3:02 am

Re: Publishing Web Services

Post by PierreLefrancois » Wed Jan 16, 2019 12:55 am

Hello all,

Can anyone share ideas or best practices on how to implement a Login WebService with LANSA ?

What would be the best way for the client to provide secure user/password information.

This is what I had in mind for the overall process.

- Client invokes Login Web service (user/password protocol TBD).
- Web service retrieves user/password, validates it, and returns a login ticket that would expire after say 5 minutes of inactivity.
  • The login ticket would take the form of a long random string (30 bytes of so)
- Client can then invoke other WebServices (GetPrice, GetInventory ...) by providing login ticket along with other service specific information.
- The system maintains an inactivity timer for the login ticket.
- If a client request is made on an expired ticket, error message is returned.
- When done, the client invokes the Logout service.

Thanks - Pierre

Post Reply