Flow API Engine

A lightweight Node.js library to execute dependency-aware API workflows using a single declarative flow definition.

Flow API Engine allows developers to define and execute multi-step API calls (with dependencies and data passing) in one flow, instead of manually chaining multiple REST calls.

📦 Installation

npm install @your-username/flow-api-engine

Replace @your-username with your actual npm scope.

🤔 Why Flow API Engine?

Traditional REST APIs require multiple sequential requests:

Client → API 1 → API 2 → API 3 → Merge Logic

With Flow API Engine, you define the entire workflow once:

Client → Flow Definition → Engine Executes Everything

✔ Fewer network calls ✔ Cleaner client code ✔ Centralized orchestration

✨ Features

• Dependency-aware execution (DAG based)
• Automatic data passing between APIs
• Declarative JSON flow definition
• HTTP API execution support
• Transform nodes for data processing
• Easy integration with Node.js backends

🧠 Basic Usage

import { FlowEngine } from "@your-username/flow-api-engine";

const engine = new FlowEngine();

const result = await engine.execute({
  nodes: {
    getUser: {
      type: "http",
      method: "GET",
      url: "https://jsonplaceholder.typicode.com/users/1"
    },
    extractUser: {
      type: "transform",
      depends_on: ["getUser"],
      script: `
        return {
          name: context.getUser.name,
          email: context.getUser.email
        };
      `
    }
  }
});

console.log(result);

📤 Output Example

{
  "getUser": {
    "id": 1,
    "name": "Leanne Graham",
    "email": "Sincere@april.biz"
  },
  "extractUser": {
    "name": "Leanne Graham",
    "email": "Sincere@april.biz"
  }
}

🔁 Flow Definition Structure

{
  "nodes": {
    "<nodeId>": {
      "type": "http | transform",
      "depends_on": ["otherNodeId"],
      "method": "GET | POST",
      "url": "https://api.example.com",
      "body": {},
      "script": "JavaScript code"
    }
  }
}

🔗 Supported Node Types

1️⃣ HTTP Node

Used to call REST APIs.

{
  "type": "http",
  "method": "POST",
  "url": "https://api.example.com/order",
  "body": {
    "userId": "{{nodes.getUser.id}}",
    "item": "Laptop"
  }
}

2️⃣ Transform Node

Used to process or merge data from previous nodes.

{
  "type": "transform",
  "depends_on": ["getUser"],
  "script": "return { username: context.getUser.name };"
}

🔄 Data Passing Between Nodes

Results of previous nodes are automatically available:

Inside transform scripts

context.getUser.name

Inside request bodies

"userId": "{{nodes.getUser.id}}"

🧪 Example: Dependent POST Requests

engine.execute({
  nodes: {
    createUser: {
      type: "http",
      method: "POST",
      url: "https://jsonplaceholder.typicode.com/users",
      body: { name: "Zubair" }
    },
    createOrder: {
      type: "http",
      depends_on: ["createUser"],
      method: "POST",
      url: "https://jsonplaceholder.typicode.com/posts",
      body: {
        userId: "{{nodes.createUser.id}}",
        product: "Laptop"
      }
    }
  }
});

🧩 Internal Architecture (For Understanding)

FlowEngine
 ├─ Flow Validator
 ├─ Dependency Resolver (DAG)
 ├─ Context Store
 ├─ HTTP Node Executor
 └─ Transform Executor

⚠️ Limitations

• Sequential execution only (parallel execution planned)
• Transform scripts are not sandboxed (trusted input recommended)
• Not designed for long-running workflows

🔮 Roadmap

• Parallel node execution
• Retry & timeout policies
• Conditional branching
• Secure transform sandbox
• Visual flow designer

📄 License

MIT License

⭐ Summary

Flow API Engine simplifies backend orchestration by allowing developers to define what should happen, not how to chain API calls.

Perfect for:

• Microservices orchestration
• Backend automation
• Complex API workflows