A real-world approach to handling complex SOAP APIs when traditional IBM i tools fall short
I've been doing integrations on IBM i for a while now. Most of the time, HTTPAPI handles everything I throw at it — REST, SOAP, whatever. It just works.
But a few months ago, I hit a wall with a SOAP API that refused to play nice. And honestly, it took me longer than I'd like to admit to figure out why.
This is what happened and how I ended up solving it.
What went wrong
The setup was straightforward. Call a vendor's SOAP endpoint, send a request, get a response, process it in RPG. Standard stuff.
Except the response kept coming back wrong.
- Connection was fine
- HTTP 200 every time
- But the response body was either empty or garbage
⚠️ In some cases, the request returns HTTP 200 but the response isn’t usable. In other cases, the request may not return a proper response at all—especially when working with older SOAP-based APIs.
When You Don’t Even Get a Proper Response
In some scenarios, the issue goes beyond receiving an unusable response.
With certain SOAP services—especially older or more rigid implementations—the request may fail before returning a meaningful HTTP response at all. This can show up as:
- Connection resets
- Timeouts
- SSL handshake failures
- Inconsistent or empty responses
These situations are often harder to debug because there’s very little feedback to work with. The request appears to fail silently, and it’s not always clear whether the issue is with the request structure, the transport layer, or compatibility between systems.
I spent a solid chunk of time convinced it was my SOAP envelope. Then I thought it was a namespace issue. Then maybe the headers. I kept tweaking things, and nothing changed.
The frustrating part? When I tested the exact same request in Postman, it worked perfectly.
The debugging spiral
I went through all the usual steps:
- Rebuilt the SOAP envelope from scratch
- Double-checked every namespace and header
- Verified SSL certificates were in place
- Compared raw payloads character by character
Everything matched. The request was identical. But HTTPAPI kept giving me bad responses while Postman returned clean data every time.
At some point I had to accept that the problem wasn't my request — it was somewhere in how the request was being sent.
Stepping back
Once I stopped trying to force HTTPAPI to work, the answer became pretty obvious.
The vendor's SOAP implementation was strict about certain HTTP behaviors — things like exact header ordering, specific TLS negotiation patterns, and chunked transfer encoding. HTTPAPI handles most of this fine for typical APIs, but this particular endpoint was picky in ways that were hard to control from RPG.
So I asked myself: what if I just let something else handle the HTTP part?
The fix: Java as a middle layer
I wrote a small Java program. Nothing fancy — maybe 80 lines. Its only job is to make the SOAP call and write the response to a file.
The flow looks like this:
RPG / CL
↓
Parameter file on the IFS
↓
Java program (handles the SOAP call)
↓
Vendor API
↓
Response file on the IFS
↓
Back to RPG for processing
RPG still runs the show. It writes out the parameters, kicks off the Java program, waits for the response, and processes it. The Java piece is just a bridge.
Why Java specifically
I've seen people suggest Python or Node for this kind of thing, and those would work too. I went with Java because it's already on every IBM i, no extra setup needed.
Java also gave me:
- Predictable TLS behavior (the JVM handles negotiation well)
- Full control over HTTP headers, including ordering
- Proper chunked encoding support
- Stack traces when things fail — which beats staring at a job log
The first time I ran it, the response came back clean. Same request that had been failing for days.
Keeping it reusable
I didn't want to hardcode anything, so the Java program reads from a parameter file:
ENDPOINT=https://api.vendor.com/soap
SOAP_ACTION=SomeAction
PAYLOAD=<Soap:Envelope>...</Soap:Envelope>
OUTPUT=/home/files/response.txt
Different API? Just change the file. The Java program doesn't care what it's calling.
The response gets written in a simple format:
HTTP Response Code: 200
Response Body:
<Soap:Envelope>...</Soap:Envelope>
STATUS: SUCCESS
RPG reads the status, grabs the body if it's good, and moves on. Clean and predictable.
This was part of what led me to try a different approach.
What I'd do differently
Looking back, I probably should have switched approaches sooner instead of spending so much time debugging HTTPAPI. The signs were there — identical requests working in other tools but failing from RPG.
I've since used this same pattern for two other integrations that had similar quirks. It's become a go-to option when the standard approach doesn't cooperate.
When this makes sense
I'm not saying stop using HTTPAPI. For most APIs, it's still my first choice.
But if you're dealing with:
- SOAP endpoints that are strict about HTTP behavior
- Responses that work everywhere except from IBM i
- TLS issues you can't pin down
- Debugging that's hit a dead end
...it's worth considering a hybrid approach. Sometimes the best thing you can do is let each tool handle what it's best at.
Wrapping up
This wasn't a glamorous fix. No new framework, no architectural overhaul. Just a small Java program sitting between RPG and an API that wouldn't behave.
But it solved a problem that had been eating up my time, and it's been solid since.
⚠️ Note on Java Setup
Make sure Java is properly available on your IBM i system.
A quick check is to run theJAVAcommand from a CL prompt or QP2TERM to confirm it executes successfully.
Also ensure your classpath and IFS paths are correctly set, as misconfiguration here can quietly cause failures.
If you've hit similar walls with SOAP on IBM i, I'd be curious to hear how you handled it. There's probably a dozen different ways to approach this — this just happened to be the one that worked for me.
Top comments (0)