IBM i

 View Only
Expand all | Collapse all

How to implement the RESTful API with a mixed set of *ENTRY parameter list

  • 1.  How to implement the RESTful API with a mixed set of *ENTRY parameter list

    Posted Sat March 12, 2022 01:59 AM
    We use IBM i for our core banking solution, the main challenge though are:

    1. the "modernization" or the screens for browser based access, we still use HATS with Webfacing - are there alternatives to this? 

    2. we also wanted to modernize the API stack to expose our RPG APIs as RESTful APIs via IWS, however there is scant material that we could refer to with regards to this topic. Do you have any recommended reference materials for this? We have followed parts 1-3 of this article:
    Part 1: Building a REST service with integrated web services server for IBM i – IBM Developer

    and we've had some success but it would be very helpful if we can get a more detailed reference esp how to implement the RESTful API given a mixed set of *ENTRY parameter list for our API wrapper programs.

    ------------------------------
    Joel Jawili
    ------------------------------


  • 2.  RE: How to implement the RESTful API with a mixed set of *ENTRY parameter list

    IBM Champion
    Posted Sat March 12, 2022 03:02 AM

    1.  There are many ways to modernize screens for browser access, and many tools available.  Are you looking for a method where your program continues to output a 5250 screen, and then that 5250 screen is convered to a web display on-the-fly like HATS?  There are at least a dozen of these on the market.  The company that I work for (Profound Logic Software) has one called Genie.  We have many competitors.  The disadvantage of this approach is that your program is still coded as a green-screen, so in many ways it still has the limitations of a green-screen. We also have a tool that will convert the DDS code for a 5250 screen into a newer format that no longer uses the 5250 protocol, which allows you to get online quickly, and eliminate the limitations of 5250.  We also have tools for writing traditional web applications that can be used from RPG and similar environments.   We have perhaps 8 or 9 competitors that provide similar tools.  You can also write your programs to output REST APIs, and call them from traditional web applications, mobile apps, etc.  Or you can convert your code to a newer, open source based language (we offer one of these, too.)   Many people would also consider rewriting the applications to be modernization, so rewriting for Java, PHP, Python, Ruby, or (my preference) Node.js. 

    It's hard to answer your question, honestly, because there are so many possibilities.  Do you have specific requirements, or something that could narrow it down?

    2. IWS is very easy to use, but also very limited in what you can do with it.  It has been getting better over the years, though.  Have you looked at the help inside IWS itself while it's running?   That's what I typically use.  In addition to IWS there are many other tools for creating APIs.  (We also make various tools for this where I work -- notably Profound API -- which is much more powerful than IWS.)

    Can you give an example of what is meant by "mixed set of *ENTRY plist"?    Given a variety of programs, don't they all have a mixed set of parameters?  What is different about yours, and what challenges do you face?



    ------------------------------
    Scott Klement
    Director
    Profound Logic Software
    Oak Creek WI
    ------------------------------



  • 3.  RE: How to implement the RESTful API with a mixed set of *ENTRY parameter list

    Posted Mon March 14, 2022 02:45 AM
    Good morning Scott, 

    First of all please allow me to say i am a HUGE fan. I have been reading your articles and how to's through the years and it has helped me a LOT. I have used your YAJL, HTTPAPIR4 in our projects with great success. My apologies in advance as this is a long message to try to explain my problem with IWS. 

    Anyway, we have 2 types of wrapper programs for our core banking APIs. One is for the transactions and one is for the enquiries, but they are pretty much the same. We are able to expose these API wrapper programs as stored procedures on IBM i, and were were able to call these from an external JVM via java JDBC call. I was hoping to be able to expose these RPGLE wrapper programs as RESTful apis using IBM IWS, as this is already freely available to us in IBM i. This is so that our clients will be able to call the APIs as more modern RESTful apis rather than the traditional jdbc/java call. 

    The tricky part is how to define the parameter list in IWS, below is our *ENTRY PLIST for our wrapper program: 

    * Entry parameter list fields
    D @RPGM S 10A
    D @BRNM S 4A
    D @WSID S 4A
    D @USID S 4A
    D @SUID S 4A
    D @SPWD S 10A
    D @JTT S 1A
    D @GZA S 9999A varying
    D @GZB S 9999A varying
    D @RREC S 1A
    D @ERRORS S 740A varying
    D @WARNINGS S 740A varying
    D @CRM S 9999A varying
    D @AEXT S 1A
    D @AREC S 1A
    D @EMH S 37 DIM(20)
    D @EA S 15 0 DIM(20)
    D @EB S 4 DIM(20)
    D @DR S 1 DIM(20)
    D @GYDET S 4096A varying
    D @GYCTR S 4096A varying
    D @JRNKY S 4096A varying

    * Entry
    C *ENTRY PLIST
    C PARM @RPGM
    C PARM @BRNM
    C PARM @WSID
    C PARM @USID
    C PARM @SUID
    C PARM @SPWD
    C PARM @JTT
    C PARM @GZA
    C PARM @GZB
    C PARM @RREC
    C PARM @ERRORS
    C PARM @WARNINGS
    C PARM @CRM
    C PARM @AEXT
    C PARM @AREC
    C PARM @EMH
    C PARM @EA
    C PARM @EB
    C PARM @DR
    C PARM @GYCTR
    C PARM @GYDET
    C PARM @JRNKY

    The key parameter here is the @GZA because this is essentially a varying length field where the values are moved to an externally defined data structure called DSAIM whose definition is based on a table for an API, sample below: 

    DSAIM DS DSAIM
    D AIM 1 9999 DIM(9999) DSAIM

    C MOVEL DSAIM DGZH15


    DGZH15 E DS EXTNAME(GZH151) INZ
    D GZWSID 4A
    D GZDIM 2S 0
    D GZTIM 6S 0
    D GZSEQ 7P 0
    D GZIMG 1A
    D GZAB 4A
    D GZAN 6A
    D GZAS 3A
    D GZBRNM 4A
    D GZPBR 5A
    D GZPSQ 5P 0
    D GZVFR 7S 0
    D GZBRND 4A
    D GZDRF 16A
    D GZAMA 15P 0
    ....+++



    In IWS, I have defined the varying fields as STRUCT, however IBM doesn't provide guidance on how the arrays should be defined in the parameter list in IWS. I have reached out to IBM via PMR but they said that questions like these are part of paid engagement with IBM Labs already, rather than standard IBM support. There are no other IBM redbooks or how to articles that i could find that could provide an example similar to our use case. I did try to define the arrays in our parameter list as type OUTPUT, as they are essentially output parameters from the API wrapper program we have, for things like error and warning messages from the actual RPG API program.

    When i test the REST API endpoint i defined above, using Postman tool, i am able to send the request to the API wrapper program, and i am able to debug the API wrapper program as well as the actual API program, but i noticed that the numeric values passed from @GZA>DSAIM>DGZH15 (like GZSEQ, GZAMA) have invalid values resulting to decimal data errors and Low-order nibble of the byte at array offset 7 is not valid. Byte value: 00. error in Postman. 

    I asked IBM if they have sample code or use cases similar to this but they did not, i also installed IBM PTF in IBM i but this did not help also. 

    SE66307 - OSP-IWS ADD ABILITY TO CONTROL WRAPPER ELEMENT IDENTIFIER (ibm.com)

    Have you tried something similar before? I just wanted to make sure the value i passed don't get into decimal data errors. IBM doesn't provide too much guidance on how to deal with this type of use case so for now i have no way forward in this one. 

    Anyway thank you so much for your time and for any inputs you might have on this. Have a great day ahead. 

    All the best
    Joel

    ------------------------------
    [Joel]
    ------------------------------



  • 4.  RE: How to implement the RESTful API with a mixed set of *ENTRY parameter list

    Posted Tue March 15, 2022 03:16 AM
    I think the problem could be in the varying length field, it looks like it is transmitted as string since i defined it as string in Postman, but the receiving RPGLE program is expecting to parse the subfields of the varying length field into zoned/char/packed fields etc. Its the packed decimal fields that are getting problems.

    ------------------------------
    [Joel]
    ------------------------------



  • 5.  RE: How to implement the RESTful API with a mixed set of *ENTRY parameter list

    Posted Tue March 15, 2022 08:11 AM

    Hi Joel, can you explain further why you need to define the parameter as a varying length field instead of defining it LIKEDS(DGZH15)?

    Assuming it's necessary to handle it as a string, maybe you could define another version of the data structure for Postman to use, where the packed subfields are defined as zoned subfields. Then use EVAL-CORR in RPG from the zoned-DS to the packed-DS. You would have to define at least one of the data structures with the QUALIFIED keyword so the subfields would all have the same name.



    ------------------------------
    Barbara Morris
    ------------------------------



  • 6.  RE: How to implement the RESTful API with a mixed set of *ENTRY parameter list

    Posted Wed March 16, 2022 02:34 AM
    Good afternoon Barbara, 

    Thank you for your response. It is a varying length field because the program is essentially a wrapper program for the back end RPG APIs. So, depending on the API to be called, the LIKEDS(GZH151)  would be any of the other 800 or so files used by the other APIs. It was once of the ways the backend core banking system managed to expose all the backend RPG APIs using only 1 wrapper API, for things like direct jdbc calls from java and from 3rd party RPG applications. 

    I was hoping to leverage the same, i.e. we will only need to expose the wrapper program / stored procedure as RESTful endpoint, then we will already be able to call all underlying RPG APIs as RESTful APIs to a degree. 

    Have a great day ahead. 

    thanks, 

    Joel

    ------------------------------
    [Joel]
    ------------------------------



  • 7.  RE: How to implement the RESTful API with a mixed set of *ENTRY parameter list

    IBM Champion
    Posted Tue March 15, 2022 01:20 PM
    Joel, I think ultimately the problem is that you haven't defined the parameters to your program in a way that another application, such as IWS, can see what they are.

    Instead, you've defined one big long character string.   I realize that you (and anyone you teach) know that these strings should be broken down into subfields using an externally defined data structure.  But, how could IWS know that?   How would it know to create separate fields in the JSON/XML documents that it exchanges over the network?

    I think your best bet is to create a parameter list that defines all of the parameters instead of providing one big character string that you move to a data structure.

    ------------------------------
    Scott Klement
    Director
    Profound Logic Software
    Oak Creek WI
    ------------------------------



  • 8.  RE: How to implement the RESTful API with a mixed set of *ENTRY parameter list

    Posted Wed March 16, 2022 02:46 AM
    Thank you Scott for your response, that was actually my worry as well. It looks like exposing the wrapper program as the RESTful endpoint will not work because of the way the API parameter is passed as a long string, and of course as you have mentioned, IWS has no way of knowing that it needs to somehow parse the JSON documents into separate fields for the backend APIs.

    I will try to look into the approach that you have mentioned above, in conjunction with the inputs from Barbara in the previous post. Again thank you so much for taking the time to reply and have a nice day ahead.

    ------------------------------
    [Joel]
    ------------------------------



  • 9.  RE: How to implement the RESTful API with a mixed set of *ENTRY parameter list

    Posted Sun March 13, 2022 10:04 PM
    Dear Joel

    The articles you mentioned were published in May 2015 and there were a few more articles after this date. Please try digesting these additional articles to see if they help. The additional articles can be accessed from this URL :   https://www.ibm.com/support/pages/node/1142632

    ------------------------------
    Satid Singkorapoom
    ------------------------------



  • 10.  RE: How to implement the RESTful API with a mixed set of *ENTRY parameter list

    Posted Sun March 13, 2022 10:56 PM
    Thanks Satid. I will have a go at these articles. Much appreciated.

    ------------------------------
    [Joel]
    ------------------------------



  • 11.  RE: How to implement the RESTful API with a mixed set of *ENTRY parameter list

    Posted Tue March 15, 2022 02:54 AM
    Hello Joel,

    If you are new to IWS, tutorial videos may help, e.g.
    - https://www.youtube.com/watch?v=Q-hp0_a6ka8
    - https://mediacenter.ibm.com/media/How+To+Create+an+Integrated+Web+Services+%28IWS%29+Server+on+IBM+i+OS/1_c69xitaw
    - https://youtu.be/RUOfH6U5tRk (YouTube can translate caption from Japanese to other languages)

    Yahagi@Japan



    ------------------------------
    Hideyuki Yahagi @ Japan
    ------------------------------



  • 12.  RE: How to implement the RESTful API with a mixed set of *ENTRY parameter list

    Posted Tue March 15, 2022 03:17 AM
    Thank you Yahagi, yes i am new to IWS and exploring if this is something we can use to modernize our back end core system. I will have a look at the tutorial videos. Thank you, this is much appreciated.

    ------------------------------
    [Joel]
    ------------------------------