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. You can optionally secure this API by specifying an apikey under the designApi section.

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

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

  # Dedicated Design API listener with optional API Key security
  designApi:
    enabled: true
    port: 9092
    apikey: "your-secure-api-key"

When apikey is provided:

• All incoming HTTP requests to /api/design/* and /api/admin/* must include a matching X-API-Key: your-secure-api-key request header.
• Unauthenticated requests are rejected with a 401 Unauthorized status.
• CORS preflight OPTIONS requests pass through automatically to allow UI browser clients to communicate seamlessly.

If apikey is omitted or left blank, the Design API remains fully unauthenticated (highly convenient for local developer execution).

---

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"
    }
  }