APIs REST con IBM i

// Verificar que el servidor HTTP esta activo
WRKACTJOB SBS(QHTTPSVR)

// Iniciar el servidor de administracion (Navigator for i)
STRTCPSVR SERVER(*HTTP) HTTPSVR(*ADMIN)

// Verificar puertos en uso
NETSTAT *CNN
// Buscar el puerto 2001 (Navigator) y 10010+ (IWS)

// Crear un servidor IWS
QSYS/STRTCPSVR SERVER(*IWS) INSTANCE('MISERVIDOR')

// Detener un servidor IWS
QSYS/ENDTCPSVR SERVER(*IWS) INSTANCE('MISERVIDOR')

// Ver servidores IWS activos
WRKACTJOB SBS(QHTTPSVR) JOB(MISERVIDOR)

// Crear servidor IWS via script (alternativa)
QSH CMD('/QIBM/ProdData/OS/WebServices/bin/createWebServicesServer.sh
  -server MISERVIDOR
  -startingPort 10020
  -userid QWSERVICE')

/www/
  MISERVIDOR/                     <- Raiz del servidor IWS
    conf/
      httpd.conf                  <- Configuracion Apache
    htdocs/
      webservices/                <- Servicios desplegados
        MISERVICIO/
          WEB-INF/
            web.xml               <- Descriptor del servicio
            pcml/
              MIPROGRAMA.pcml     <- Descripcion de parametros
    logs/
      access_log                  <- Log de acceso HTTP
      error_log                   <- Log de errores

**free
// ---------------------------------------------------------------
// GETCLIENTE: Retorna datos de un cliente por ID
// Expuesto via IWS como: GET /api/clientes/{id}
// ---------------------------------------------------------------
ctl-opt dftactgrp(*no) actgrp(*caller);
ctl-opt option(*srcstmt : *nodebugio);

dcl-f clientes disk usage(*input) keyed;

// Interfaz del programa (mapeada por IWS a parametros REST)
dcl-pi *n;
  prmId        packed(7:0);       // Input: ID del cliente
  prmNombre    varchar(100);      // Output: nombre
  prmEmail     varchar(200);      // Output: email
  prmSaldo     packed(11:2);      // Output: saldo
  prmActivo    char(1);           // Output: S/N
  prmHttpCode  int(10);           // Output: codigo HTTP
  prmMensaje   varchar(200);      // Output: mensaje
end-pi;

// Buscar el cliente por clave
chain prmId clientes;

if %found(clientes);
  prmNombre   = cliNom;
  prmEmail    = cliMail;
  prmSaldo    = cliSaldo;
  prmActivo   = cliActivo;
  prmHttpCode = 200;
  prmMensaje  = 'OK';
else;
  prmNombre   = '';
  prmEmail    = '';
  prmSaldo    = 0;
  prmActivo   = 'N';
  prmHttpCode = 404;
  prmMensaje  = 'Cliente no encontrado';
endif;

*inlr = *on;
return;

<?xml version="1.0" encoding="UTF-8"?>
<pcml version="7.0">
  <program name="GETCLIENTE" path="/QSYS.LIB/MILIB.LIB/GETCLIENTE.PGM">
    <data name="prmId"       type="packed" length="7" precision="0"
          usage="inputoutput"/>
    <data name="prmNombre"   type="char"   length="100"
          usage="output"/>
    <data name="prmEmail"    type="char"   length="200"
          usage="output"/>
    <data name="prmSaldo"    type="packed" length="11" precision="2"
          usage="output"/>
    <data name="prmActivo"   type="char"   length="1"
          usage="output"/>
    <data name="prmHttpCode" type="int"    length="4"
          usage="output"/>
    <data name="prmMensaje"  type="char"   length="200"
          usage="output"/>
  </program>
</pcml>

// GET https://miibmi:10020/web/services/clientes/1001
// Content-Type: application/json

{
  "prmId": 1001,
  "prmNombre": "Fernando Secchi",
  "prmEmail": "fernando@empresa.com",
  "prmSaldo": 50000.00,
  "prmActivo": "S",
  "prmHttpCode": 200,
  "prmMensaje": "OK"
}

-- En Navigator for i > IWS > Deploy New Service > SQL
-- Se define la consulta que sera el endpoint

-- GET /api/clientes?estado=A&limite=50
SELECT CLI_ID    as id,
       CLI_NOM   as nombre,
       CLI_MAIL  as email,
       CLI_SALDO as saldo,
       CLI_ACTIV as activo
  FROM MILIB.CLIENTES
 WHERE CLI_ACTIV = :estado
 ORDER BY CLI_NOM
 FETCH FIRST :limite ROWS ONLY;

-- GET /api/clientes/{id}
SELECT CLI_ID    as id,
       CLI_NOM   as nombre,
       CLI_MAIL  as email,
       CLI_SALDO as saldo,
       CLI_ACTIV as activo,
       CLI_FALTA as fechaAlta
  FROM MILIB.CLIENTES
 WHERE CLI_ID = :id;

-- POST /api/clientes (INSERT)
INSERT INTO MILIB.CLIENTES
  (CLI_NOM, CLI_MAIL, CLI_SALDO, CLI_ACTIV, CLI_FALTA)
VALUES
  (:nombre, :email, 0, 'A', CURRENT_DATE);

-- Stored procedure que encapsula logica de negocio
CREATE OR REPLACE PROCEDURE MILIB.CREAR_PEDIDO (
  IN  p_cliente   INTEGER,
  IN  p_producto  VARCHAR(20),
  IN  p_cantidad  INTEGER,
  OUT p_pedido_id INTEGER,
  OUT p_total     DECIMAL(11,2),
  OUT p_mensaje   VARCHAR(200)
)
LANGUAGE SQL
BEGIN
  DECLARE v_precio DECIMAL(11,2);
  DECLARE v_stock  INTEGER;

  -- Verificar stock
  SELECT PROD_PRECIO, PROD_STOCK
    INTO v_precio, v_stock
    FROM MILIB.PRODUCTOS
   WHERE PROD_COD = p_producto;

  IF v_stock < p_cantidad THEN
    SET p_pedido_id = 0;
    SET p_total = 0;
    SET p_mensaje = 'Stock insuficiente';
    RETURN;
  END IF;

  -- Crear el pedido
  INSERT INTO MILIB.PEDIDOS
    (PED_CLI, PED_PROD, PED_CANT, PED_TOTAL, PED_FECHA)
  VALUES
    (p_cliente, p_producto, p_cantidad,
     v_precio * p_cantidad, CURRENT_TIMESTAMP);

  SET p_pedido_id = IDENTITY_VAL_LOCAL();
  SET p_total = v_precio * p_cantidad;

  -- Actualizar stock
  UPDATE MILIB.PRODUCTOS
     SET PROD_STOCK = PROD_STOCK - p_cantidad
   WHERE PROD_COD = p_producto;

  SET p_mensaje = 'Pedido creado exitosamente';
END;

**free
ctl-opt dftactgrp(*no) actgrp(*caller);

// Data structure que mapea la estructura JSON
dcl-ds pedido qualified;
  cliente    int(10);
  producto   varchar(20);
  cantidad   int(10);
  dcl-ds direccion;
    calle    varchar(100);
    ciudad   varchar(50);
    cp       varchar(10);
  end-ds;
end-ds;

// JSON de entrada (recibido como parametro o desde HTTP)
dcl-s jsonInput varchar(2000);
jsonInput = '{"cliente": 1001, "producto": "PROD-A1", '
          + '"cantidad": 5, "direccion": '
          + '{"calle": "Av. Corrientes 1234", '
          + '"ciudad": "Buenos Aires", "cp": "C1043"}}';

// Parsear JSON a la data structure
data-into pedido %data(jsonInput : 'case=any')
                 %parser('YAJLINTO');

// Ahora podemos usar los datos nativamente
dsply ('Cliente: ' + %char(pedido.cliente));
dsply ('Producto: ' + pedido.producto);
dsply ('Ciudad: ' + pedido.direccion.ciudad);

**free
// Data structure con datos para serializar
dcl-ds respuesta qualified;
  codigo     int(10) inz(200);
  mensaje    varchar(100) inz('Pedido creado');
  pedidoId   int(10) inz(5042);
  total      packed(11:2) inz(12500.00);
end-ds;

dcl-s jsonOutput varchar(5000);

// Generar JSON desde la data structure
data-gen respuesta %data(jsonOutput : 'renameprefix=EGNA')
                   %gen('YAJLGEN');

// jsonOutput contiene:
// {"codigo":200,"mensaje":"Pedido creado",
//  "pedidoId":5042,"total":12500.00}

**free
// Para JSON mas complejo, usar YAJL directamente
/include YAJL/QRPGLESRC,YAJL_H

yajl_genOpen(*on);  // pretty print

yajl_beginObj();
  yajl_addChar('status' : 'success');
  yajl_addNum('code' : %char(200));

  // Array de items
  yajl_beginArray('items');
    yajl_beginObj();
      yajl_addChar('producto' : 'LAPTOP-01');
      yajl_addNum('precio' : '1250.00');
      yajl_addBool('disponible' : *on);
    yajl_endObj();
    yajl_beginObj();
      yajl_addChar('producto' : 'MOUSE-03');
      yajl_addNum('precio' : '25.50');
      yajl_addBool('disponible' : *off);
    yajl_endObj();
  yajl_endArray();

yajl_endObj();

// Obtener el JSON generado
dcl-s jsonPtr pointer;
dcl-s jsonLen int(10);
dcl-s jsonStr varchar(10000);

yajl_copyBuf(jsonPtr : jsonLen);
jsonStr = %str(jsonPtr : jsonLen);
yajl_genClose();

-- Consumir una API REST externa con HTTP_GET
-- Disponible desde IBM i 7.3 TR6+ / 7.4+
SELECT *
  FROM JSON_TABLE(
    QSYS2.HTTP_GET(
      'https://api.ejemplo.com/clientes/1001',
      '{
        "header": "Authorization, Bearer mi-token-jwt",
        "header": "Accept, application/json",
        "sslTolerate": "true"
      }'
    ),
    '$' COLUMNS(
      id       INTEGER     PATH '$.id',
      nombre   VARCHAR(100) PATH '$.nombre',
      email    VARCHAR(200) PATH '$.email',
      saldo    DECIMAL(11,2) PATH '$.saldo'
    )
  ) AS datos;

-- HTTP_POST para enviar datos
VALUES QSYS2.HTTP_POST(
  'https://api.ejemplo.com/pedidos',
  '{"cliente": 1001, "producto": "PROD-A1", "cantidad": 5}',
  '{
    "header": "Authorization, Bearer mi-token-jwt",
    "header": "Content-Type, application/json"
  }'
);

**free
ctl-opt dftactgrp(*no) actgrp(*caller)
        bnddir('HTTPAPI');

/include HTTPAPI/QRPGLESRC,HTTPAPI_H

dcl-s url     varchar(500);
dcl-s respuesta varchar(10000);
dcl-s rc      int(10);

// Configurar SSL
https_init(*on);

// GET request
url = 'https://api.ejemplo.com/cotizacion/USD';
rc = http_string('GET' : url : respuesta);

if rc = 1;
  dsply ('Respuesta: ' + %subst(respuesta : 1 : 50));
else;
  dsply ('Error HTTP: ' + %char(http_error()));
endif;

// POST request con body JSON
dcl-s body varchar(2000);
body = '{"moneda": "USD", "monto": 1000}';

rc = http_string('POST'
               : 'https://api.ejemplo.com/convertir'
               : respuesta
               : body
               : 'application/json');

// Agregar headers personalizados
http_setAuth(HTTP_AUTH_BEARER : 'mi-token-jwt');
http_addHeader('X-API-Key' : 'clave-12345');

{
  "openapi": "3.0.1",
  "info": {
    "title": "Gestion de Clientes API",
    "description": "API REST para gestion de clientes IBM i",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://miibmi:10020/web/services",
      "description": "Servidor de produccion"
    }
  ],
  "paths": {
    "/clientes/{id}": {
      "get": {
        "summary": "Obtener cliente por ID",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": { "type": "integer" }
          }
        ],
        "responses": {
          "200": {
            "description": "Cliente encontrado",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Cliente"
                }
              }
            }
          },
          "404": {
            "description": "Cliente no encontrado"
          }
        }
      }
    }
  }
}

// Crear certificado SSL para el servidor IWS
DCM   // Digital Certificate Manager (via Navigator)
// 1. Crear Certificate Authority local o importar cert
// 2. Asignar certificado al servidor IWS

// Configurar Basic Auth en httpd.conf del servidor IWS
// (se hace automaticamente desde Navigator for i)

// Verificar configuracion SSL
CFGTCPAPP APP(*HTTP) SET(SSL *YES)
           SSLCIPHER(*ALL)
           SSLPROT(*TLSV1.2 *TLSV1.3)

// Registrar API key en tabla de control
INSERT INTO MILIB.API_KEYS
  (APP_NAME, API_KEY, ACTIVA, FECHA_CREACION)
VALUES
  ('APP_MOVIL', 'ak_live_7f8g9h0j1k2l3m', 'S', CURRENT_TIMESTAMP);

**free
// Validar JWT recibido en header Authorization
dcl-pr validarJWT ind;
  token varchar(2000) const;
end-pr;

dcl-proc validarJWT;
  dcl-pi *n ind;
    token varchar(2000) const;
  end-pi;

  dcl-s payload  varchar(5000);
  dcl-s esValido ind;

  // Decodificar y verificar el JWT
  // (usando libreria JSONWEBTOKEN o validacion manual)
  monitor;
    // 1. Separar header.payload.signature
    // 2. Verificar firma con clave publica
    // 3. Verificar expiracion (exp claim)
    // 4. Verificar issuer (iss claim)

    // Usando SQL para decodificar Base64
    exec sql
      SET :payload = SYSTOOLS.BASE64DECODE(
        SUBSTR(:token,
               LOCATE('.', :token) + 1,
               LOCATE('.', :token,
                 LOCATE('.', :token) + 1) -
               LOCATE('.', :token) - 1));

    esValido = (payload <> '');
    return esValido;

  on-error *all;
    return *off;
  endmon;
end-proc;