Differences Between IBM i Integrated Web Services (IWS) and CGI Web Services
IBM i Integrated Web Services (IWS) and CGI (Common Gateway Interface) web services are two approaches to exposing RPG (or other ILE language) programs as web-accessible APIs on the IBM i platform. Both leverage the built-in HTTP Server (powered by Apache), but they differ significantly in ease of implementation, flexibility, performance, and use cases.
IWS is a high-level, integrated tool designed for quick deployment of standardized RESTful or SOAP services, while CGI is a lower-level, script-based method that offers more customization but requires manual handling of web protocols.
Aspect | IWS (Integrated Web Services) | CGI Web Services |
|---|---|---|
Implementation | Wizard-driven setup via IBM Navigator for i. Uses PCML (auto-generated XML) to map RPG parameters to HTTP requests. Supports path templates (e.g., /{custno:\d+}) for REST. | Manual configuration in Apache's httpd.conf (e.g., ScriptAlias /cust /qsys.lib/restful.lib/custinfo.pgm). RPG reads input from environment variables (e.g., REQUEST_URI), stdin; writes to stdout. |
Ease of Use | High: Minimal web knowledge needed; handles HTTP, serialization/deserialization (XML/JSON) automatically. Quick for wrapping existing code. | Lower: Requires understanding of web protocols; manual parsing (e.g., via QtmhRdStin API or YAJL for JSON). |
Flexibility | Limited: Only XML/JSON formats; restricted parameter types (e.g., no complex nested structures); basic security (e.g., *BASIC auth). | High: Any data format (CSV, PDF, etc.); custom security (e.g., tokens, crypto); full control over HTTP methods/headers. |
Performance | Java-based, so potential overhead from JVM startup; suitable for moderate loads but may lag vs. native. | Potentially faster (pure RPG/ILE execution); can use FastCGI for pre-started jobs to optimize repeated calls. |
Security | Built-in SSL/TLS, auth methods; runs under QWSERVICE profile (*IOSYSCFG authority often needed). | Customizable (e.g., via headers/cookies); risks if misconfigured (e.g., ScriptAliasMatch exposing programs). |
Use Cases | Simple REST/SOAP APIs for existing RPG (e.g., customer lookup); rapid prototyping. | Complex/custom APIs needing non-standard formats or high performance (e.g., file uploads, real-time data). |
Requirements | IBM i 7.1+, HTTP Server, Java, QShell/PASE; no extra cost. | HTTP Server; optional open-source libs (e.g., YAJL); activation groups for ILE management. |
Let's go through this in more detail:
Core Mechanism: IWS acts as a "black box" wrapper, transforming RPG procedure interfaces into web endpoints without altering the core logic. For example, a GETCUST RPG program can be deployed with a single wizard step, automatically generating URLs like http://system:port/cust/{custno}. In contrast, CGI treats RPG programs as executable scripts invoked by the web server on each request, requiring explicit code for request parsing and response formatting.
Development Overhead: With IWS, compile your RPG with PGMINFO(*PCML:*MODULE) and deploy, no HTTP code needed. CGI demands RPG to interface with CGI APIs (e.g., getenv for headers) and handle errors manually, but it shines for developers familiar with RPG who want to avoid Java dependencies.
Limitations and When to Choose: IWS is ideal for straightforward integrations but falters with advanced needs (e.g., binary data). Opt for CGI (or FastCGI for speed) when you need granular control, though it involves more setup like editing Apache configs and testing with tools like SoapUI.
For hands-on examples, refer to IBM documentation or resources like Scott Klement's guides.
If you're building new services, my recommendation is to start with IWS for speed, then migrate to CGI for scalability.