The Real Problem: Lack of Deterministic Execution

Most teams do not struggle with calling APIs.

They struggle with:

This is not a testing problem.

It is a determinism problem .

The Daily Pain (What Actually Happens)

Scenario 1: The Production 400

You deploy an endpoint. Everything passed locally and in Postman.

Production fails.

Why?

Because:

The mismatch is discovered at runtime.

Scenario 2: DB Snapshot Hell

You seed staging from a snapshot.

Tests pass.

But:

You are not testing the system. You are testing a static dataset.

Scenario 3: Manual Workflow Testing

You test a flow manually:

This is:

And impossible to scale in CI.

Why Current Approaches Break Down

Typical tools focus on interaction, not execution.

What is missing:

A way to define and execute API workflows deterministically.

What SphereIntegrationHub Is

SphereIntegrationHub (SIH) is a deterministic API workflow engine .

It enables teams to define, execute, and reproduce API-driven workflows with predictable behavior.

It is designed to:

What It Is Not

SIH focuses on execution, not interaction .

How SIH Solves These Problems

1. Contract Validation Before Execution

Instead of discovering issues at runtime:

  
    sih --workflow create-order.workflow --env dev --dry-run

You validate against OpenAPI before execution.

Result:

2. API-First State Creation

Instead of DB snapshots:

  
    forEach: "{{input.userCount}}"
parallel: true
body: |
  {
    "id": "{{rand:guid()}}",
    "email": "user_{{rand:text(8)}}@test.com"
  }
ensure:
  mode: "CreateIfMissing"

Now:

3. Deterministic Workflow Execution

Instead of manual steps:

  
    - name: login
  output:
    jwt: "{{response.body.token}}"

- name: create-order
  headers:
    Authorization: "Bearer {{context.jwt}}"

No copy/paste.
No scripts.

4. Execution Model

SIH supports:

This enables modeling real flows, not just requests.

What You Gain

Before

After

Deterministic Workflow Tracing (Visual Execution)

SIH does not just execute workflows. It produces a deterministic, visual trace of their execution .

Each run generates:

Unlike traditional logs, this is a full, inspectable execution graph of the workflow.

What You Can See

The HTML trace provides:

This is conceptually similar to distributed tracing systems like Jaeger, but with a key difference:

Why This Matters

Typical debugging relies on:

SIH replaces that with a single, self-contained execution trace .

What You Gain

With a single trace, you can inspect:

This makes the trace useful for:

Example Output Files

  
    customer-order.a3f2b5c8.workflow.output
customer-order.a3f2b5c8.workflow.trace.json
customer-order.a3f2b5c8.workflow.trace.html

Example JSON Structure

  
    {
  "workflowName": "customer-order",
  "executionId": "a3f2b5c8",
  "startTime": "2026-04-20T10:30:00Z",
  "duration": "00:00:01.245",
  "stages": [
    {
      "name": "login",
      "status": "Ok",
      "duration": "00:00:00.120",
      "httpStatus": 200,
      "output": {
        "jwt": "eyJhbGc..."
      }
    },
    {
      "name": "create-order",
      "status": "Failed",
      "duration": "00:00:00.110",
      "httpStatus": 400,
      "error": "Expected status 201, got 400"
    }
  ]
}

Visual Trace Example

SCR-20260420-nedh

-- Deterministic workflow trace showing execution timeline, branching, parallel stages, and per-stage input/output inspection. --

This is one of the most differentiating aspects of SIH: it makes workflow behavior visible, reproducible, and explainable without relying on external tracing systems.

This is not a log. It is a deterministic execution trace.

MCP Integration

SIH exposes workflows via MCP.

Instead of exposing raw APIs to AI:

You expose controlled execution units .

This enables:

CI/CD Native

SIH runs directly in pipelines.

  
    - name: Run workflows
  run: |
    sih --workflow workflows/smoke-test.workflow \
        --env staging \
        --report-format both

No adapters. No transformation.

GitHub Action

SIH also provides a GitHub Action for direct integration.

  
    - name: Run SIH workflow
  uses: PinedaTec-EU/sphere-integration-hub-action@v1
  with:
    workflow: workflows/smoke-test.workflow
    env: staging
  env:
    ADMIN_PASSWORD: ${{ secrets.ADMIN_PASSWORD }}

This allows:

Reports can be uploaded as artifacts for later inspection.

What SIH Requires to Work Well

SIH can provide deterministic execution, but only if the systems it interacts with expose enough determinism themselves.

In practice, SIH works best when APIs are:

This matters because SIH does not invent determinism out of thin air.
It makes deterministic execution possible when the underlying APIs make that achievable .

Examples

If an API:

then SIH can model reusable and idempotent workflows very effectively.

If an API instead:

then workflow determinism becomes harder to guarantee.

Important Distinction

SIH can enforce workflow logic, branching, validation, and traceability.

But its ability to provide reliable idempotency and predictable execution depends on the quality of the API surface behind it.

That is not a limitation of SIH alone. It is a property of any system that aims to orchestrate real APIs deterministically.

Where It Fits

SIH is most useful when:

Where It Does Not Fit

Status: Active Development

SIH is under continuous improvement.

The model is stable.
The engine is evolving.

Focus remains on:

End-to-End Example: From Login to Confirmed Order

A single workflow can model a real user journey across services, with deterministic execution and no manual steps.

In this example:

Main Workflow

  
    version: "3.11"
name: "e2e-order-flow"

input:
  - name: "customerName"
    type: "Text"
    required: true
  - name: "customerEmail"
    type: "Text"
    required: true

references:
  workflows:
    - name: "ensure-customer"
      path: "./workflows/ensure-customer.workflow"

stages:
  - name: "login"
    kind: "Endpoint"
    endpoint: "/api/auth/login"
    httpVerb: "POST"
    body: |
      {
        "username": "admin",
        "password": "{{env:ADMIN_PASSWORD}}"
      }
    output:
      jwt: "{{response.body.token}}"

  - name: "ensure-customer"
    kind: "Workflow"
    workflowRef: "ensure-customer"
    inputs:
      customerName: "{{input.customerName}}"
      customerEmail: "{{input.customerEmail}}"
      jwt: "{{stage:login.output.jwt}}"

  - name: "create-order"
    kind: "Endpoint"
    endpoint: "/api/orders"
    httpVerb: "POST"
    headers:
      Authorization: "Bearer {{stage:login.output.jwt}}"
    body: |
      {
        "customer_id": "{{stage:ensure-customer.workflow.output.customerId}}",
        "items": [
          { "product_id": "prod-1", "quantity": 2 }
        ]
      }
    output:
      orderId: "{{response.body.id}}"

  - name: "confirm-order"
    kind: "Endpoint"
    endpoint: "/api/orders/{{stage:create-order.output.orderId}}/confirm"
    httpVerb: "POST"
    headers:
      Authorization: "Bearer {{stage:login.output.jwt}}"

endStage:
  output:
    customerId: "{{stage:ensure-customer.workflow.output.customerId}}"
    orderId: "{{stage:create-order.output.orderId}}"

Child Workflow: Ensure Customer Exists

  
    version: "3.11"
name: "ensure-customer"

input:
  - name: "customerName"
    type: "Text"
    required: true
  - name: "customerEmail"
    type: "Text"
    required: true
  - name: "jwt"
    type: "Text"
    required: true

stages:
  - name: "find-customer"
    kind: "Endpoint"
    endpoint: "/api/customers/by-email/{{input.customerEmail}}"
    httpVerb: "GET"
    headers:
      Authorization: "Bearer {{input.jwt}}"
    expectedStatuses: [200, 404]
    output:
      exists: "{{response.status == 200}}"
      customerId: "{{response.body.id}}"

  - name: "jump-if-customer-exists"
    kind: "NoOp"
    runIf: "{{stage:find-customer.output.exists}} == true"
    jumpTo: "finish"

  - name: "create-customer"
    kind: "Endpoint"
    runIf: "{{stage:find-customer.output.exists}} == false"
    endpoint: "/api/customers"
    httpVerb: "POST"
    headers:
      Authorization: "Bearer {{input.jwt}}"
    body: |
      {
        "name": "{{input.customerName}}",
        "email": "{{input.customerEmail}}"
      }
    output:
      customerId: "{{response.body.id}}"

endStage:
  name: "finish"
  output:
    customerId: "{{stage:find-customer.output.customerId || stage:create-customer.output.customerId}}"

Run it:

  
    sih --workflow e2e-order-flow.workflow \
    --env staging \
    --input customerName="John Doe" \
    --input customerEmail="[email protected]" \
    --report-format both

What this demonstrates:

The same workflow can run in dev, staging, or production by switching the environment.

No scripts. No manual steps. No hidden logic.

Final Thought

Most teams do not need more tools.

They need predictability .

SphereIntegrationHub provides that by turning API interactions into:

That is the shift