Exposing RPGLE as Webservices - Testing

IBM i developers, if you're building or debugging web services on your Power Systems platform – whether it's a Node.js Express API, an RPGLE-exposed REST endpoint via iToolkit, or a custom Apache hosted service, testing them efficiently is key to smooth integrations.

Visual Studio Code, and other VS-Code based IDE's like IBM BOB, offer seamless ways to run curl commands directly, leveraging its integrated terminal or extensions like REST Client for a more structured experience.

Curl, the versatile command-line HTTP client, lets you simulate GET, POST, PUT, DELETE requests with headers, JSON payloads, and authentication, all while targeting your IBM i host (e.g., http://your-ibmi-host:3000/api/food).

Here, we will cover two primary methods: using the VS Code integrated terminal for raw curl execution and the REST Client extension for file-based, reusable tests. 

Both approaches work identically for IBM i services, assuming your web service is accessible over the network (e.g., via HTTP/HTTPS on ports 80/443 or custom like 3000). 

We'll focus on practical steps, verification, and IBM i-specific considerations like authentication and firewall rules.

As of October 2025, these instructions align with VS Code 1.95+ and curl 8.10+ (bundled in most modern systems).

Method 1: Using VS Code's Integrated Terminal for Raw Curl Commands

This is the quickest way for one-off tests – no extensions needed. VS Code's terminal emulates a full shell, supporting cross-platform curl execution.

Open VS Code and Your Workspace: Launch VS Code and open a folder (e.g., your local project mirroring the IBM i app) via File > Open Folder. This keeps tests organized.

Open the Integrated Terminal: Press `Ctrl+`` (backtick) or go to Terminal > New Terminal. Select your preferred shell (PowerShell on Windows, bash/zsh on macOS/Linux).

Navigate and Prepare: Change to a working directory if needed: cd /path/to/your/project. For JSON payloads, save them to a file (e.g., payload.json) using VS Code's editor:

• Create a new file: File > New File, paste the JSON, and save as payload.json

Run Curl Commands: Target your IBM i endpoint. Examples for common HTTP methods:

GET Request (e.g., fetch data):

-X GET: Specifies the method (optional for GET).

The expected result is a JSON response from your service.

POST Request (e.g., add food record)

-d @payload.json: Reads the body from the file.
For inline JSON: Replace with -d '{"function":"ADD",...}' (escape quotes if needed).

With Basic Authentication (common for IBM i Apache setups):

-u: Prompts for credentials or embeds them (use --user for security).

With Bearer Token (for JWT/OAuth):

Verbose Mode for Debugging: Add -v or -vv for headers, timings, and errors:

Look for HTTP status (e.g., 200 OK, 401 Unauthorized) and response body.

Interpret Results:

•  Success: JSON output in the terminal (e.g., {"status": "Record added"}).
• Errors: Check for 4xx/5xx codes. Common IBM i issues: Connection refused (firewall/port), 401 (auth), or 500 (service crash – check IBM i job logs with DSPJOBLOG).
• Save Output: Pipe to a file: curl ... > response.json, then open in VS Code for pretty-printing (install JSON extension if needed).

Automate with Tasks

For repeatable tests, create a VS Code task (Terminal > Configure Tasks). Add to .vscode/tasks.json:

Run with Ctrl+Shift+P > "Tasks: Run Task" > "Test POST Food API".

Method 2: Using the REST Client Extension for Structured Testing

For ongoing development, the REST Client extension (by Huachao Mao) turns VS Code into a lightweight Postman alternative. It supports curl-like syntax in .http or .rest files, with syntax highlighting, environment variables, and response previews.

• Open Extensions view (Ctrl+Shift+X).
• Search for "REST Client" (publisher: Huachao Mao).
• Click Install. Restart VS Code if prompted.

• New file: File > New File.
• Save as api-tests.http (extension triggers syntax mode).
• VS Code auto-detects HTTP language mode; if not, Ctrl+Shift+P > "Change Language Mode" > "HTTP".

Write Requests: Use markdown-like syntax for comments and curl-equivalent blocks. Example for your food API:

###: Separates requests (click to send).

Variables: Define in .vscode/settings.json or a rest-client.env file (e.g., {{host}} = your-ibmi-host:3000, {{token}} = your-jwt).

Auth: Add headers like Authorization: Basic {{base64-creds}}.

• Click the "Send Request" link above each block (appears on hover).
• Response appears in a split pane: status, headers, body (auto-formatted JSON/XML).
• For errors: Inline diagnostics highlight issues (e.g., invalid JSON).

• Environments: Create rest-client.env for dev/prod (e.g., host=your-ibmi-host:3000).
• Response Handling: Save responses to files: > response.json after the request.
• GraphQL/WebSocket: Supported for advanced IBM i services.
• Debugging: Use ### @name Test POST for naming; view history in the extension's output panel (Ctrl+Shift+U > REST Client).

Verify and Iterate: Test against IBM i – expect quick round-trips (<1s for local network). For HTTPS: Prefix with https:// and handle self-signed certs with --insecure in terminal or extension settings.

IBM i-Specific Tips and Troubleshooting

Host Resolution: Use the IBM i's IP or hostname (e.g., from DSPNETA). For local testing from IBM i PASE, run curl in QP2TERM.

Performance: Add -w "%{time_total}\n" to curl for latency; optimize if >500ms.

Security: Always use HTTPS in prod (curl -k for dev cert bypass). Integrate with IBM i's DCM for certs.

• Connection Refused: Verify service with WRKACTJOB on IBM i; check ports with NETSTAT *CNN.
• JSON Errors: Validate payloads with VS Code's JSON linting.
• Encoding Issues: Add -H "Accept-Charset: UTF-8" for CCSID mismatches.
• Large Payloads: Use --data-binary for binaries; monitor IBM i CPU with WRKSYSSTS.

Alternatives: If REST Client doesn't suit, try Thunder Client extension (more UI-focused, like Postman).

Conclusion: Streamline Your IBM i API Testing

With VS Code's terminal or REST Client, testing IBM i web services becomes an integrated part of your dev loop – no context-switching to separate tools. Start with terminal curl for speed, graduate to REST Client for documentation. This setup scales from quick sanity checks to full regression suites.

Wrapping Up the Series

Boom—you've turned legacy RPGLE into a sleek web API! From data files to JSON responses, your IBM i now speaks the web's language. Deploy this in dev, then scale to microservices.