IBM i in a Microservices Architecture: What Actually Works (and What Doesn't)

🔍 IBM i's Real Role in Microservices

IBM i is at its strongest when it remains the system of record and business logic engine. Your decades of tested, reliable RPG code does not need to be rewritten — it needs to be exposed as services.

What IBM i Does Best

• Exposing existing programs as REST APIs using ILEastic or IBM's Integrated Web Services
• Wrapping business logic in thin API layers
• Maintaining transactional integrity for critical operations
• Serving as the system of record via DB2 for i
• Change Data Capture for event-driven architectures

What Does Not Work

Running containers on IBM i is technically possible but rarely practical. Limited container ecosystem, resource overhead, and licensing complexity make it the wrong tool for the job. Keep IBM i running native applications and run your containers on Linux — integrating via APIs.

Batch jobs that run once a day, tightly coupled business processes, and legacy code that simply works and is not changing — none of these are microservice candidates.

🏗️ Three Architectural Patterns That Actually Work

Pattern 1 — The Hybrid Gateway

A single API gateway in the cloud or DMZ serves as the entry point for all traffic, routing to either cloud services or IBM i services behind the firewall. This provides a security boundary, centralized authentication, rate limiting, and circuit breaker protection for IBM i services.

Pattern 2 — Event-Driven Integration

IBM i publishes events to a message bus. Downstream services subscribe and react independently. IBM i never needs to know who is consuming its events — making this the cleanest decoupling pattern available.

Three implementation options exist depending on your environment and tooling preferences.

CREATE TRIGGER ORDER_CHANGE
  AFTER INSERT ON ORDERS
  FOR EACH ROW MODE DB2ROW
  BEGIN ATOMIC
    CALL PUBLISH_EVENT('order.created', NEW.ORDER_ID);
  END

// RPG writes event to data queue
QSNDDTAQ DTAQ('ORDEREVENTS') DTAQLIB('MYLIB') DATA(eventData);

// Separate Node.js or Python service monitors the queue
// and publishes events to Kafka or RabbitMQ

For Option C, CDC tools such as IBM InfoSphere CDC, Precisely Connect, or Debezium capture database changes and stream them directly to your message bus — no application code changes required.

Pattern 3 — Backend for Frontend (BFF)

Each frontend (mobile, web, partner API) gets its own dedicated BFF service that aggregates multiple IBM i calls, transforms data into the right shape, and handles caching. This dramatically reduces the number of round trips to IBM i and keeps response payloads lean.

// Mobile BFF — parallel calls, minimal response payload
app.get('/api/mobile/order/:id', async (req, res) => {
    const order = await ibmiService.getOrder(req.params.id);

    // Fetch related data in parallel — not sequentially
    const [customer, items] = await Promise.all([
        ibmiService.getCustomer(order.customerId),
        ibmiService.getOrderItems(order.id)
    ]);

    // Return only what mobile needs — nothing more
    res.json({
        id: order.id,
        status: order.status,
        total: order.total,
        customerName: customer.name,
        itemCount: items.length
    });
});

// Web BFF — same IBM i calls, richer response
app.get('/api/web/order/:id', async (req, res) => {
    const order = await ibmiService.getOrder(req.params.id);

    const [customer, items, history] = await Promise.all([
        ibmiService.getCustomer(order.customerId),
        ibmiService.getOrderItems(order.id),
        ibmiService.getOrderHistory(order.id)
    ]);

    res.json({ order, customer, items, history });
});

⚙️ Technology Stack Recommendations

For Exposing IBM i Services

dcl-proc getCustomer;
  dcl-pi *n;
    request  likeds(IL_REQUEST);
    response likeds(IL_RESPONSE);
  end-pi;

  dcl-s customerId varchar(10);
  dcl-s customerData varchar(1000);

  customerId = il_getPathParameter(request: 'id');

  exec sql SELECT JSON_OBJECT(
    'id':    CUST_ID,
    'name':  CUST_NAME,
    'email': CUST_EMAIL
  ) INTO :customerData
  FROM CUSTOMERS
  WHERE CUST_ID = :customerId;

  il_responseWrite(response: customerData);
  il_responseWriteStatus(response: 200);
end-proc;

const { Connection, Statement } = require('idb-connector');

app.get('/api/customers/:id', async (req, res) => {
    const conn = new Connection({ url: '*LOCAL' });
    conn.connect();

    const stmt = new Statement(conn);
    const result = await stmt.exec(
        'SELECT * FROM CUSTOMERS WHERE CUST_ID = ?',
        [req.params.id]
    );

    res.json(result[0]);
    conn.close();
});

For the Integration Layer

🚨 Four Common Pitfalls and How to Avoid Them

// getCustomerName service
// getCustomerAddress service
// getCustomerPhone service
// getCustomerEmail service
// Four network calls where one would do

// Customer Service — handles all customer operations
// GET  /customers/:id  → returns full customer object
// PUT  /customers/:id  → updates customer
// POST /customers      → creates customer
// One service, one network call, all customer data

// Order Creation Saga
// Step 1: Create order (IBM i)        ✓
// Step 2: Reserve inventory (IBM i)   ✓
// Step 3: Process payment (Cloud)     ✗ FAILS
// Step 4: Compensate → Release inventory (IBM i)
// Step 5: Compensate → Cancel order (IBM i)
// System returns to consistent state automatically

⚡ Performance Considerations

Connection Pooling

Opening IBM i connections is expensive. Never open and close a connection per request.

app.get('/api/data', (req, res) => {
    const conn = new Connection();
    conn.connect();
    // use connection
    conn.close(); // Expensive open/close on every request
});

const pool = new ConnectionPool({ size: 10 });

app.get('/api/data', async (req, res) => {
    const conn = await pool.acquire();
    try {
        // use connection
    } finally {
        pool.release(conn); // Always release back to pool
    }
});

Key Metrics to Monitor

🗺️ Migration Roadmap

📈 Real-World Success Story

🛑 When NOT to Use Microservices with IBM i

Before committing to microservices, understand when they are the wrong choice. They are not a universal solution — and for IBM i environments, the bar for adopting them should be high.

Microservices are the wrong choice when you have a single small team (the operational overhead is unsustainable), when operations must be atomic across multiple entities (distributed transactions are complex and error-prone), when your code changes quarterly or annually (the overhead is not justified), when you lack CI/CD pipelines and automated deployment, or when you cannot clearly define service boundaries — in which case you will create a distributed monolith, which is worse than a regular one.