AS400 REST API: A Developer’s Guide to IBM i Integration

  • August 15, 2026
  • Ty Woods
  • 23 min read

The right approach to an AS400 REST API depends on which side of the connection you own. To consume outside data from RPG code, use QSYS2/SYSTOOLS HTTP SQL functions for quick jobs or Scott Klement’s HTTPAPI for full control. To expose IBM i data and logic to the outside world, use IBM Integrated Web Services (IWS) for read-only SQL results, or run Node.js in PASE when you need to call RPG programs and handle real application logic. Middleware like MuleSoft’s AS400Gateway or Kafka connectors enters the picture only once you have multiple consumers or enterprise governance requirements to satisfy.

Here’s the one-line version for the four situations developers hit most often:

  • Read-only internal reporting or dashboards: IWS or IAS REST. Zero custom code, JSON quickly.
  • Internal tools that need to call RPG business logic: Node.js in PASE with a thin wrapper over your service programs.
  • External, public-facing APIs with versioning and governance needs: Node.js in PASE behind an API gateway, or a commercial connector.
  • High-throughput or batch data movement between systems: middleware or connector platforms built for transformation and scale. Not a hand-rolled endpoint.

The rest of this guide walks through each option with working examples, so you can pick a lane and start building instead of guessing.

Key Takeaways

The most reliable path to a working AS400 REST API is matching the simplest tool to your actual use case, then mapping dependencies before you expose anything to the outside world.

Point Details
Match tool to use case Use IWS or QSYS2 SQL functions for read-only internal needs; use Node.js in PASE for full logic and control.
Consume with HTTPAPI or SQL HTTPAPI (RPGLE) and QSYS2 HTTP functions cover most outbound calls without new infrastructure.
Map dependencies before wrapping Identify every caller and data sensitivity level before adding an HTTP front door to RPG logic.
Add middleware only when justified Gateways and connectors earn their cost with multiple consumers or governance needs, not single integrations.
Golden Path Digital maps the ground first AS/Forward parses RPG dependencies before API wrapping begins, reducing surprise scope during a pilot.

Table of Contents

What Is an AS400 REST API and Why the Terminology Gets Confusing

“AS400 REST API” isn’t a single product. Its shorthand developers use for any RESTful HTTP interface built on or around an IBM i system, whether that means calling out to a third-party service from RPG code or exposing your own Db2 data and RPG logic to a web or mobile front end. IBM stopped using the name AS/400 decades ago in favor of IBM i, but the term persists in job postings, forum threads, and search queries because it’s what a generation of developers still calls the platform.

That naming mismatch matters here because the practical answer splits into two very different problems: consuming REST APIs from IBM i, and exposing IBM i functionality as a REST API for other systems to consume. Confusing the two leads to wasted effort, like installing HTTPAPI when what you actually need is IWS, or building a whole Node.js service when a single SQL function call would do the job. The sections below treat them separately, because the tools, skill sets, and risk profiles don’t overlap much.

Comparing the Main Approaches for IBM i API Integration

Six architectures show up repeatedly in real IBM i shops, and each one solves a different problem well. Picking the wrong one for your constraints is the most common source of wasted modernization budget.

  • QSYS2/SYSTOOLS HTTP SQL functions: SQL-callable functions (HTTP_GET, HTTP_POST, and related routines) that let any SQL-capable program, including RPG with embedded SQL, make outbound HTTP calls without touching a separate library.
  • Scott Klement’s HTTPAPI: A free, open-source RPG toolkit built specifically for HTTP and HTTPS communication, including authentication and multipart encoding, when you need more control than SQL functions offer.
  • IBM Integrated Web Services (IWS): A GUI-driven tool bundled with IBM i that maps HTTP requests directly to RPGLE programs or SQL statements and returns JSON, largely without writing new code.
  • CGI/CGIDEV2 wrapping RPG: An older but still functional pattern where a CGI program acts as the HTTP handler and calls existing RPGLE service programs, often via XMLSERVICE or itoolkit, to expose logic without touching the underlying RPG source.
  • Node.js running in PASE: A full Node.js runtime supported directly on IBM i, capable of running Express routes, connecting to Db2 for i, and calling RPG or CL programs when you need genuine application logic behind your endpoints.
  • API gateways and connectors: Commercial or managed platforms that sit in front of IBM i and handle transformation, throttling, and multi-consumer governance instead of leaving that work to hand-written code.
Approach Best for Language/platform Latency/throughput Security/auth support Maintenance fit
QSYS2/SYSTOOLS HTTP functions Simple outbound calls from RPG or SQL SQL, RPGLE with embedded SQL Good for occasional or batch calls Basic TLS, header-based auth Low overhead, easy to maintain
HTTPAPI (Scott Klement) RPG shops needing full HTTP control RPGLE Fine for synchronous calls, not built for high concurrency TLS, custom auth headers, certs Requires RPG skill, stable long-term
IWS Internal read-only reporting RPGLE or SQL via wizard Good for light, internal traffic Limited; no built-in OAuth or versioning Fast to build, weak for external APIs
CGI/CGIDEV2 wrapping RPG Exposing existing service programs as-is RPGLE, ILE Adequate for moderate synchronous loads Depends on web server config Preserves logic, but aging pattern
Node.js in PASE Full-control endpoints calling RPG/Db2 JavaScript/Node.js Strong; handles async and concurrency well Full OAuth2/JWT support via libraries Modern skill set, active ecosystem
API gateway/connector Multi-consumer, governed, high-volume integration Platform-specific Built for scale and transformation Enterprise-grade, built in Offloads hardening, adds licensing cost

How Do You Call an External REST API From IBM i?

Start with the built-in Db2 for i HTTP functions before reaching for anything else. QSYS2.HTTP_GET and QSYS2.HTTP_POST (also available under SYSTOOLS on some releases) let an SQL statement or an RPGLE program with embedded SQL make an outbound HTTP call directly, without a separate library, service program, or open-source dependency. A read-only lookup against a shipping-rate API or a currency-conversion service is a textbook case: one SQL call in, one JSON response out.

Hands connecting Ethernet cable in server rack

SELECT JSON_TABLE(
  QSYS2.HTTP_GET('https://api.example.com/v1/rates',
    '{"headers":{"Authorization":"Bearer " CONCAT :token}}'
  ), '$' COLUMNS (rate DECIMAL(9,4) PATH '$.rate')
) AS r;

That’s the whole integration for a simple, low-volume lookup. Check your PTF level before relying on it. Not every IBM i release ships the same function set, and older Technology Refreshes may be missing options like custom headers or client certificate support.

When you need more than a single request/response, reach for Scott Klement’s HTTPAPI. It’s the tool most RPG-centric shops turn to for anything involving authentication flows, retries, or multipart form data, because it was purpose-built as a native RPG HTTP client rather than a thin SQL wrapper. A typical POST with a JSON body looks like this in RPGLE:

D httpRequest    PR             10I 0 ExtProc('http_xml_service')
D  ...
C     eval      url = 'https://api.example.com/v1/orders'
C     callp     http_url_post(url: jsonBody: %addr(response): responseLen)
C     if        httpapi_error <> *zero
C                exsr          HandleError
C     endif

The error-handling subroutine matters more than the happy path here. HTTPAPI exposes distinct error indicators for connection failures versus HTTP-level errors (a 404 or 500 response), and treating them identically is a common mistake that turns a debuggable API failure into a silent data gap.

For consumers that need genuinely asynchronous behavior, connection pooling, or modern client libraries (retry-with-backoff packages, OAuth token refresh helpers), Node.js running in PASE is worth the extra setup. It gives you the same fetch or axios patterns any web developer already knows, running on the same physical IBM i partition as your Db2 data.

A few configuration details trip up almost every team on their first outbound HTTPS call from IBM i:

  • Import the target server’s certificate chain into IBM i’s digital certificate manager (DCM) before your first call, or every request will fail TLS validation.
  • If your network requires an outbound proxy, both HTTPAPI and the QSYS2 HTTP functions support proxy configuration, but it has to be set explicitly; neither assumes one exists.
  • Set explicit timeouts. A hung outbound call in a batch job can block an entire job queue if you leave the default (often no timeout at all) in place.
  • Pool connections where you’re making repeated calls to the same host, rather than opening and closing a new TLS handshake every time.

Pro Tip: Never authenticate outbound API calls with an IBM i user profile and password. Use a scoped API key or OAuth token stored in a secured data area or key vault instead, so a compromised credential can’t be used to sign into the system itself.

How Do You Expose IBM i Data and Logic as a REST API?

The fastest path from zero to a working JSON endpoint is IBM Integrated Web Services. Its wizard walks you through linking an HTTP resource to either an RPGLE program’s parameters or a straight SQL statement, and IWS generates the plumbing. For an internal dashboard that just needs to read order status or inventory counts, this can mean a working endpoint in under an hour with no new RPG code written.

The trade-off is real, though. IWS-generated endpoints tend to return data in a column-array JSON shape rather than clean nested objects, they don’t offer built-in versioning, and they weren’t designed with public-facing rate limiting or OAuth scopes in mind. Treat IWS as the right tool for internal, read-heavy traffic and look elsewhere once you need to publish something externally.

For exposing existing business logic rather than just query results, wrapping RPG service programs is the pattern most modernization teams land on. A CGI or CGIDEV2 program acts as the HTTP entry point, translates the incoming request into parameters, calls the existing RPGLE service program (often through XMLSERVICE or itoolkit), and serializes the result back to JSON, all without modifying the underlying RPG source. That’s the appeal: your validated business rules never move.

For anything beyond simple request/response, Node.js in PASE is the more durable choice. A typical setup looks like this:

  1. Install Node.js in PASE and confirm the idb-connector or odbc package can reach Db2 for i.
  2. Scaffold an Express app with routes mapped to specific business functions, not raw table names, so the API surface stays stable even if the underlying schema changes.
  3. Call RPG programs through itoolkit or a service program wrapper for anything beyond simple SQL reads.
  4. Manage the running process with PM2 or a similar supervisor so the service restarts automatically after a crash or IPL.
  5. Add authentication middleware (JWT validation, API key check) before any route touches production data.
  6. Log every request with a correlation ID before returning a response, not after.

Transactions and long-running jobs need separate handling. If a request triggers something that takes longer than a few seconds (a batch update, a report generation), don’t make the caller wait on an open HTTP connection. Push the work to a data queue or message queue, return a 202 Accepted with a job ID immediately, and let the client poll a status endpoint or receive a callback when the job finishes. Trying to force a five-minute RPG batch process into a synchronous REST call is one of the more common design mistakes in early IBM i API projects, and it usually surfaces as timeout errors under load rather than during initial testing.

When Should You Use Middleware Instead of Building Native Endpoints?

Middleware earns its cost the moment you have more than one consumer of the same data, or when a compliance team needs governance features a hand-built endpoint doesn’t have out of the box. If your only requirement is “let our mobile app read order status,” a native IWS or Node.js endpoint is almost always cheaper to build and simpler to run. If you’re feeding data to five internal systems, a partner’s ERP, and a public developer portal simultaneously, that’s a different problem, and it usually justifies a gateway.

  • Enterprise API gateways and connectors (examples include MuleSoft’s AS400Gateway and Kafka-based connectors, both referenced in enterprise integration literature from Infoview Systems) handle transformation, rate limiting, and centralized authentication, so individual endpoint code doesn’t need to reimplement them.
  • ETL-style platforms like Integrate.io are built for bulk data movement between systems on a schedule, not for real-time request/response traffic, and fit best when the use case is genuinely batch synchronization rather than live API calls.
  • Event streaming connectors (Kafka-based) suit scenarios where Db2 for i changes need to propagate to multiple downstream systems continuously, rather than on request.

A rough use-case matrix helps decide fast:

Scenario Best-fit pattern
Single internal app, read-only data Native IWS or QSYS2 SQL endpoint
One external partner integration Node.js in PASE with API key auth
Multiple consumers, shared governance rules API gateway/connector
Continuous data sync across five or more systems Event streaming connector or ETL platform
Nightly bulk transfer to a data warehouse ETL-style batch connector

The operational trade-off is straightforward: integration platforms absorb the cost of building auth, rate limiting, and monitoring yourself, but that convenience comes with licensing fees and another system to operate. For a two-consumer internal project, that cost rarely pencils out. For a program feeding a dozen downstream systems, it usually does.

When Should You Use Middleware Instead of Building Native Endpoints? — overview diagram

What Security Practices Do IBM i REST Integrations Need?

Authentication is where most IBM i API projects either succeed quietly or fail publicly, and the mistake is almost always the same one: reusing an IBM i user profile and password as the API credential. Don’t do it. Use JWT or OAuth 2.0 tokens issued by an identity provider (Azure AD and Okta are common choices) for user-facing APIs, and scoped API keys for service-to-service calls where a full OAuth flow is overkill. A leaked API key limits blast radius to whatever that key was scoped for; a leaked system profile can touch anything that profile can touch.

TLS configuration deserves the same attention on IBM i as anywhere else. Import trusted root and intermediate certificates into DCM before your first outbound HTTPS call, and if you’re calling a partner system that requires client certificates for mutual TLS, generate and register that certificate in DCM as well. Don’t disable certificate validation “temporarily” to get past an error. That workaround has a well-documented habit of never getting removed.

Authorization needs to happen at the API layer, not just at the database. Map token scopes to specific IBM i logic rather than granting broad Db2 access and hoping the front end behaves. Row and column-level filtering belongs in the service program or the API middleware, applied consistently regardless of which client is calling.

OWASP’s API Security guidance translates cleanly to IBM i work even though it wasn’t written with the platform in mind:

  • Validate every input field against expected type and length before it reaches an SQL statement or RPG program, not just at the client.
  • Rate-limit endpoints, even internal ones, since a runaway internal script can take down a service as effectively as an external attacker.
  • Never log full request or response bodies that contain credentials, tokens, or personally identifiable information.
  • Return generic error messages to the client while logging full detail server-side, so error responses don’t leak internal schema or logic.

Pro Tip: Build a role-mapping table that translates external OAuth scopes into IBM i object-level authorities once, in one place, rather than scattering authorization checks across every RPG program that gets exposed. It turns a security audit from a code review into a single-table lookup.

For teams that need deeper performance tuning once security is in place, general API performance optimization techniques apply just as directly to IBM i endpoints as to any other backend, particularly around connection reuse and response caching.

How Do You Map JSON to Db2 and RPG Data Structures?

Parsing incoming JSON on IBM i comes down to three real options, and which one fits depends on how deeply nested the data is. SQL’s native JSON_TABLE and JSON_VALUE functions handle flat or lightly nested JSON well and require no separate library, which makes them the right default for straightforward request bodies. RPG-native parsing libraries (YAJL bindings are the common choice) give you more control when a payload has deeply nested arrays or optional fields that need conditional handling. Node.js, if you’re already running it in PASE, handles arbitrarily complex JSON transformation the way any JavaScript backend would, using plain object mapping instead of fixed-format parsing at all.

Mapping need Recommended method
Flat JSON to Db2 columns, simple reads SQL JSON_TABLE
Nested JSON with optional fields into RPG data structures RPG parsing library (YAJL-based)
Complex transformation, arrays of objects, conditional logic Node.js transformation layer
Fixed-format legacy RPG structures needing JSON output Canonical DTO pattern with explicit field mapping

A canonical JSON shape, meaning a stable, documented structure for requests and responses that doesn’t just mirror your physical file layout, saves enormous rework later. Db2 column names change less often than business needs, but if your JSON API directly exposes column names, a database change becomes an API breaking change. Define a request/response DTO (data transfer object) pattern once, and translate between that shape and your physical Db2 structure in one place, not scattered across every endpoint.

Validate incoming JSON before it touches an RPG program: check required fields exist, types match, and numeric ranges are sane, and reject bad input with a clear 400-level error rather than letting a malformed field crash a program further downstream. For schema evolution, add new fields as optional rather than required, and version your endpoint (/v1/, /v2/) whenever you need to remove or restructure a field, rather than silently changing behavior under an existing path.

How Do You Handle Errors, Retries, and Monitoring?

Idempotency is the concept most teams skip until something breaks in production. Any operation that changes data (an order submission, a payment post) needs an idempotency key so a retried request doesn’t create a duplicate record. Generate that key client-side, store it with the transaction, and check for it before processing a repeat request. Combine that with an exponential backoff retry pattern on the client side (wait 1 second, then 2, then 4) rather than hammering a temporarily unavailable endpoint immediately.

Pagination deserves a deliberate choice rather than an afterthought. For SQL-backed endpoints, a cursor-based approach using FETCH FIRST n ROWS ONLY combined with a stable sort key tends to hold up better under concurrent writes than offset-based paging, which can skip or duplicate rows if data changes between page requests. QSYS2 functions and Node.js wrappers both support cursor-style paging without much extra code.

Testing an IBM i endpoint doesn’t require anything exotic. Build a Postman collection against your endpoints early, including negative test cases (missing auth header, malformed JSON, invalid IDs), not just the happy path. For Node.js endpoints in PASE, standard CI/CD tooling (Jest for unit tests, a pipeline that runs them on every commit) works exactly as it would for any other Node service. RPG wrappers are harder to unit test in isolation, but wrapping the core logic in a service program with well-defined inputs and outputs makes it testable independent of the HTTP layer.

A short monitoring checklist covers most of what production support teams actually need:

  • Log every request with a correlation ID, timestamp, endpoint, and response code, minimum.
  • Track response time percentiles (p50, p95, p99), not just averages, since averages hide the slow outliers users actually notice.
  • Alert on error rate spikes, not just total error counts, so a low-traffic overnight period doesn’t mask a real problem.
  • Feed logs into whatever APM or log aggregation tool your organization already uses, rather than building a custom dashboard from scratch.

How Should You Plan an AS400 API Modernization Project?

The single biggest mistake in IBM i modernization is treating APIs as a reason to rewrite RPG logic instead of a reason to expose it. Validated business rules that have run correctly for a decade or more carry real institutional value, and rewriting them from scratch introduces risk that dependency mapping and wrapping avoid entirely. Treat the existing RPG as the system of record, and put the API layer on top of it rather than underneath a rewrite.

Before you add an HTTP front door to anything, map its dependencies. That means:

  • Identify every program, job, and screen that currently calls the logic you’re about to expose.
  • Classify the data sensitivity involved (customer PII, financial totals, internal-only reference data) so you know what authorization level the new endpoint actually needs.
  • Define service boundaries. Decide what belongs behind one endpoint versus what should be split into two, based on how the data is actually used downstream, not how it’s currently structured in one RPG program.

A sensible pilot picks one low-risk, high-value target: something read-heavy, internally consumed, and not tied to a regulatory deadline. An inventory lookup or order-status endpoint for an internal dashboard is a common first choice, because a mistake there costs an afternoon of debugging, not a compliance incident. Measure success with concrete numbers: request volume served, error rate, and developer hours spent building versus the equivalent effort a full rewrite would have taken. A team that maps dependencies first commonly avoids weeks of rework compared with one that exposes an endpoint and discovers mid-project that three other programs depended on undocumented side effects of the logic they just wrapped.

The Default Architecture Most Teams Should Start With

Most IBM i shops overthink the starting point. For new external-facing endpoints, Node.js in PASE is the right default: it gives developers a modern, testable runtime with a large ecosystem of libraries for auth, validation, and monitoring, while still running on the same partition as your Db2 data and RPG programs. For internal, read-only tools, don’t build anything custom when IWS or a QSYS2 SQL function call solves the problem in an afternoon.

Where I’d push back on conventional wisdom: teams over-invest in middleware too early, often because a vendor pitch made API gateways sound mandatory rather than situational. If you have one or two consumers and no external governance requirement, a gateway adds licensing cost and operational surface area without a matching benefit. Bring in middleware when you actually have the multi-consumer problem it solves, not preemptively because it appears on every modernization roadmap. The pattern that balances developer productivity, security, and long-term maintenance best isn’t the most sophisticated one on paper. It’s the one your team can actually operate and debug at 2 a.m. without paging three vendors first.

How Golden Path Digital Supports Your IBM i API Project

Wrapping RPG safely starts with knowing exactly what depends on the program you’re about to expose, and that’s the step most teams underestimate before their first API goes live. Golden Path Digital built AS/Forward specifically to parse IBM i RPG codebases and map those dependencies before any API layer gets added, so your pilot endpoint doesn’t surface an undocumented caller three months into production.

Golden Path Digital

That structured, dependency-first approach is what separates a modernization effort that stays on schedule from one that gets stalled by a surprise. If your team is planning a REST API pilot on IBM i and wants a clear picture of what that program touches before you write a line of wrapper code, start with an IBM i modernization assessment to map the ground you’re building on.

Sources

FAQ

Does Costco Still Use AS400?

Large retailers, including Costco, have historically run core operations on IBM i (the platform once called AS/400), and IBM i remains widely used across retail, wholesale distribution, and manufacturing for exactly the transaction reliability that made it popular decades ago. Specific current vendor details for any one company aren’t publicly confirmed, but the pattern of large enterprises running IBM i behind modern web and mobile front ends is common industry-wide.

What Are the Four Types of REST APIs?

There’s no single official “four types” classification, but REST APIs are commonly grouped by purpose: public APIs (open for external developers), private/internal APIs (used only within an organization), partner APIs (shared with specific business partners under contract), and composite APIs (which combine multiple resource calls into one request). On IBM i, most projects start as private APIs and expand to partner or public status as governance needs grow.

How Do You Set Up a REST API on IBM i?

Pick your exposure method based on complexity: use the IBM Integrated Web Services wizard for a fast, read-only SQL endpoint, or set up Node.js in PASE with Express routes if you need to call RPG programs and handle real business logic. Either way, map dependencies and add authentication before the endpoint goes live, rather than treating security as a post-launch step.

What Is Replacing REST APIs?

REST remains the dominant style for IBM i integrations, but GraphQL and gRPC are gaining ground in specific scenarios: GraphQL for clients that need flexible, single-request data shapes, and gRPC for high-throughput internal service-to-service calls. For most IBM i modernization projects, REST is still the pragmatic default because of its broad tooling support and the fact that Node.js, HTTPAPI, and IWS all already speak it fluently.

Should You Rewrite RPG Programs Before Exposing Them as APIs?

No. Wrapping validated RPG logic behind a thin API layer is generally lower risk than rewriting it, since it preserves business rules that already work correctly in production. A dependency-mapping step before wrapping, the approach Golden Path Digital’s AS/Forward is built around, catches hidden callers before they become production incidents.

Leave a Reply

Your email address will not be published. Required fields are marked *