lab

Lab — Exponer un dato de IBM i por REST con IWS

Crear un programa RPG, exponerlo como servicio REST/JSON usando Integrated Web Services (IWS) y consumirlo desde un cliente externo.

Desarrollo

Lab — Exponer un dato de IBM i por REST con IWS

Objetivo

Escribir un programa RPG simple que devuelva información de un cliente, exponerlo como servicio REST/JSON vía Integrated Web Services (IWS) de IBM i, y consumirlo desde un cliente externo (curl, Node.js o Python). Validar la observabilidad de IWS sobre quién/qué/cuándo invocó el endpoint (mejorada en IBM i 7.5 — fuente: IBM i 7.5 — Base Enhancements).

Tiempo estimado

120 minutos.

Prerequisitos

Paso 1 — Inicializar repositorio Git

En la home del usuario en IBM i (vía PASE o SSH):

mkdir -p ~/labs/lab-rest && cd ~/labs/lab-rest
git init
echo "# Lab REST API IBM i" > README.md
git add . && git commit -m "init"

Paso 2 — Crear biblioteca de trabajo

CRTLIB LIB(RESTLAB) TEXT('Lab REST IBM i')

Paso 3 — Crear tabla de prueba (con journaling)

CRTJRNRCV JRNRCV(RESTLAB/RCV0001) THRESHOLD(100000)
CRTJRN JRN(RESTLAB/JRNREST) JRNRCV(RESTLAB/RCV0001) MNGRCV(*SYSTEM)

CREATE TABLE RESTLAB.CLIENTES (
    CLIENTE_ID INT NOT NULL PRIMARY KEY,
    NOMBRE VARCHAR(50),
    CIUDAD VARCHAR(30),
    SALDO DECIMAL(10,2)
);

INSERT INTO RESTLAB.CLIENTES VALUES (1, 'Juan Perez', 'Buenos Aires', 1500.00);
INSERT INTO RESTLAB.CLIENTES VALUES (2, 'Maria Lopez', 'Cordoba', 2700.50);
INSERT INTO RESTLAB.CLIENTES VALUES (3, 'Pedro Garcia', 'Mendoza', 980.25);

STRJRNPF FILE(RESTLAB/CLIENTES) JRN(RESTLAB/JRNREST) IMAGES(*BOTH)

El journaling no es estrictamente necesario para REST, pero es buena práctica de la organización: toda tabla productiva nace journaled (ver Anexo de seguridad y track de Desarrollo).

Paso 4 — Escribir el programa RPG

Archivo getcliente.rpgle (free-form):

**FREE
ctl-opt option(*nodebugio:*srcstmt) dftactgrp(*no);

dcl-pi getcliente;
   inClienteId int(10) const;
   outNombre varchar(50);
   outCiudad varchar(30);
   outSaldo packed(10:2);
   outFound ind;
end-pi;

exec sql
   select NOMBRE, CIUDAD, SALDO
     into :outNombre, :outCiudad, :outSaldo
   from RESTLAB.CLIENTES
   where CLIENTE_ID = :inClienteId;

if SQLCODE = 0;
   outFound = *on;
else;
   outFound = *off;
   outNombre = '';
   outCiudad = '';
   outSaldo = 0;
endif;

return;

Compilar:

CRTSQLRPGI OBJ(RESTLAB/GETCLIENTE) SRCFILE(QRPGLESRC) +
           SRCMBR(GETCLIENTE) OBJTYPE(*PGM) DBGVIEW(*SOURCE)

(Ajustar el SRCFILE según donde haya quedado el fuente. Si usás Code for IBM i, el flujo de compilación es desde el editor.)

Paso 5 — Exponer el programa como servicio REST con IWS

Vía la consola web de IWS (típicamente http://<sistema>:10010/HTTPAdmin o similar — validar contra docs de IWS instalado):

  1. •Crear un HTTP server dedicado (o reusar uno) en el puerto deseado (p.ej. 10080).
  2. •Crear un Integrated Web Services server asociado.
  3. •Deployar el programa RESTLAB/GETCLIENTE como servicio:
    • •Nombre del servicio: clientes.
    • •Operación: getCliente.
    • •HTTP method: GET.
    • •URL pattern: /clientes/{id}.
    • •Mapping: inClienteId ← path param {id}. Salida: JSON con los campos nombre, ciudad, saldo, found.
  4. •Iniciar el servicio.

Los nombres y pasos exactos dependen de la versión de IWS instalada. Ver IBM Documentation — Integrated Web Services.

Paso 6 — Probar el servicio

Desde un cliente externo (curl):

curl http://<ibm-i-host>:10080/web/services/clientes/getCliente?id=1

Respuesta esperada (formato JSON, exacto depende de la config del servicio):

{
  "outNombre": "Juan Perez",
  "outCiudad": "Buenos Aires",
  "outSaldo": 1500.00,
  "outFound": true
}

Paso 7 — Cliente externo Node.js

// client.js
const fetch = require('node-fetch'); // npm install node-fetch@2

async function getCliente(id) {
  const url = `http://<ibm-i-host>:10080/web/services/clientes/getCliente?id=${id}`;
  const res = await fetch(url);
  return res.json();
}

(async () => {
  console.log(await getCliente(1));
  console.log(await getCliente(2));
  console.log(await getCliente(99)); // no existe
})();

npm init -y
npm install node-fetch@2
node client.js

Paso 8 — Validar observabilidad de IWS

IBM i 7.5 mejora la trazabilidad de uso de REST APIs. Verificar:

(Fuente: IBM i 7.5 — Base Enhancements)

Paso 9 — Versionar en Git

cd ~/labs/lab-rest
cp /algun/path/getcliente.rpgle .
cp /algun/path/client.js .
git add . && git commit -m "lab REST funcional"

Paso 10 — Cleanup

DROP TABLE RESTLAB.CLIENTES;

ENDJRNPF FILE(RESTLAB/CLIENTES)
DLTJRN JRN(RESTLAB/JRNREST)
DLTJRNRCV JRNRCV(RESTLAB/RCV0001) DLTOPT(*IGNINQMSG)
DLTPGM PGM(RESTLAB/GETCLIENTE)
DLTLIB LIB(RESTLAB)

Detener y eliminar el servicio en IWS.

Validación esperada

Lecciones del lab

Recursos