Design API

Joynare Nexus provides a built-in Design API to allow web-based frontend applications (like a visual flow designer) to directly interact with the ESB runtime.

These administrative REST endpoints allow you to list, read, update, and execute flows dynamically. The most powerful feature of the Design API is Hot-Reloading: when you save a flow via the API, the server instantly updates its live memory. You never need to restart the server during active development!

Note: All Design API endpoints automatically include Access-Control-Allow-Origin: * to prevent CORS issues during local UI development.

---

Configuration

For security and separation of concerns, the Design API can be bound to its own dedicated port, completely separate from your business logic routes.

To configure this, update your routes/server.yaml file:

server:
  # Normal execution listeners
  listeners:
    - port: 9090
      protocol: "http"

  # Dedicated Design API listener
  designApi:
    enabled: true
    port: 9092

When enabled, the Design API will listen only on the configured port (9092 in this example).

---

1. List Flows

Returns a list of all flows currently loaded in the ESB Registry.

• Method: GET
• Endpoint: /api/design/flows
• Response: 200 OK

  {
    "flows": [
      "showcase.01-basics:SimplePipeline",
      "orders:ProcessOrder"
    ]
  }

---

2. Get Flow Source

Retrieves the raw YAML definition of a specific flow directly from the local file system.

• Method: GET
• Endpoint: /api/design/flows/{namespace}/{name}
• Response: 200 OK (Content-Type: application/x-yaml) Returns the raw YAML payload.

---

3. Save & Hot-Reload Flow

Saves the updated YAML to the local file system and instantly hot-reloads the logic into the live ESB memory.

• Method: PUT
• Endpoint: /api/design/flows/{namespace}/{name}
• Body: Raw YAML content.
• Response: 200 OK

  {
    "status": "success",
    "message": "Flow saved and hot-reloaded successfully"
  }

---

4. Execute Flow (Test/Run)

Allows the UI to trigger a flow execution with custom JSON input and receive the final pipeline output. This mimics the "Run As -> Flow Service" feature in enterprise IDEs.

• Method: POST
• Endpoint: /api/design/execute
• Content-Type: application/json
• Body:

  {
    "flow": "showcase.01-basics:SimplePipeline",
    "input": {
      "key": "value"
    }
  }

• Response: 200 OK

  {
    "status": "success",
    "pipeline": {
      "key": "value",
      "result": "processed"
    }
  }