REST API Endpoints

Joynare Nexus allows you to expose your Flow Services as production-ready HTTP endpoints with built-in support for routing, groups, path parameters, and authentication.

1. Server Configuration (routes/server.yaml)

The global server settings define how the ESB listens for requests. Joynare Nexus supports multiple listeners, allowing you to bind to several HTTP and HTTPS ports simultaneously.

server:
  host: "0.0.0.0"   # Interface to bind to
  listeners:
    - port: 9090
      protocol: "http"
    - port: 9091
      protocol: "http"
    # Example HTTPS configuration
    # - port: 9443
    #   protocol: "https"
    #   certFile: "./certs/server.crt"
    #   keyFile: "./certs/server.key"
  timeout: 30       # Request timeout in seconds
  cors:
    enabled: true
    allowedOrigins: ["*"]

---

2. Route Groups

Routes are organized into directories within the routes/ folder. Each directory represents a Route Group and must contain a routes.yaml file.

routes/
  showcase/
    routes.yaml    # Defined with basePath: /api/showcase
  integration/
    routes.yaml    # Defined with basePath: /api/v1/integration

Group Definition

At the top of routes.yaml, you define the group metadata:

group:
  name: "Showcase Features"
  basePath: /api/showcase
  version: "1.0"
  enabled: true

---

3. Defining Routes

Inside the routes list in routes.yaml, you define individual endpoints.

Simple Route

routes:
  - name: "VariableManipulation"
    path: /map
    method: POST
    flow: showcase.01-basics:MapStep

Path Parameters

You can capture variables from the URL using the :variable syntax. Multiple parameters can be used in a single path. These variables are automatically injected into the flow's pipeline as top-level keys.

Single Parameter

  - name: "GetOrder"
    path: /:id        # Full path: GET /api/v1/orders/123
    method: GET
    flow: showcase.02-mapping:ExplicitMapping
    # Result: ${id} = "123"

Multiple Parameters

  - name: "GetOrderFile"
    path: /:id/files/:filename  # Full path: GET /api/v1/orders/123/files/invoice.pdf
    method: GET
    flow: showcase.01-basics:SimplePipeline
    # Result: ${id} = "123", ${filename} = "invoice.pdf"

---

Query Parameters

Standard URL query parameters (e.g., ?status=shipped&limit=10) are automatically extracted and injected into the pipeline as top-level keys.

Example

Calling GET /api/v1/orders/search?status=shipped&limit=10:

• Result: ${status} = "shipped", ${limit} = "10"

Important Notes

• Multi-value Parameters: If a query parameter is provided multiple times (e.g., ?tag=blue&tag=red), only the first value is currently captured.
• Precedence: If a key exists in both path parameters and query parameters (e.g., path /:id and query ?id=99), the query parameter will take precedence and overwrite the path parameter in the pipeline.

---

Request Body (JSON & XML)

For POST and PUT requests, Joynare Nexus automatically decodes the request body based on the Content-Type header.

JSON Support

If Content-Type: application/json is sent, the body is decoded as JSON and merged into the pipeline.

• Nested Structure: Preserved as objects/arrays.
• Usage: Use system.json:Extract to navigate.

XML Support

If Content-Type: application/xml (or any XML-related type) is sent, the body is decoded into a map using the following conventions:

• Elements become keys.
• Attributes are prefixed with @.
• Repeated elements become arrays.
• Usage: Use system.xml:Extract to navigate.

Raw Body

Regardless of the content type, the original raw body is always available in the pipeline under the _rawBody key.

---

4. Unified Showcase Example

To see everything in action, you can use the built-in Web Showcase.

Route Definition:

  - name: "UnifiedGateway"
    path: /gateway/:category/process
    method: POST
    flow: showcase.08-integrations:WebIntegration

Example Request:POST /api/v1/integration/gateway/orders/process?priority=high

Request Body:

{
  "data": { "value": 100 },
  "meta": { "source": "web-portal" }
}

Pipeline Result:

• ${category}: "orders" (from path)
• ${priority}: "high" (from query)
• ${data}: { "value": 100 } (from body)
• ${summary}: "Processed ORDERS with HIGH priority" (after flow execution)

---

5. Authentication

Joynare Nexus supports several authentication methods per route.

Basic Auth

    auth:
      type: basic
      username: my_user
      password: my_password

API Key

    auth:
      type: apikey
      apikey: your-secret-key # Checked against 'X-API-Key' header

---

6. Automatic Flow Exposure

By default, Joynare Nexus can automatically expose all discovered flow services as REST endpoints without requiring manual route definitions. This is ideal for rapid development and internal service invocation.

Configuration

Enabled in routes/server.yaml:

server:
  autoExpose:
    enabled: true
    prefix: "/services" # Base path for all flows
    allowGet: true      # Also allow GET requests (POST is always allowed)
    auth:               # Optional: Global security for all auto-exposed flows
      type: basic
      username: "admin"
      password: "secret-password"

URL Mapping

The URL is constructed using the flow's namespace and name.

Flow Key	URL Path
ProcessOrder	/services/ProcessOrder
finance:CalculateTax	/services/finance/CalculateTax
orders.utils:GenerateID	/services/orders/utils/GenerateID

Features

• Dynamic Discovery: New flows are automatically exposed as soon as the server starts or restarts.
• Payload Merging: Query parameters and JSON/XML request bodies are automatically merged into the flow's pipeline.
• Always Active: Unlike manual routes, auto-exposed flows always return the full pipeline as a JSON response.

---

7. Management Commands

List Active Routes

To see all registered endpoints and their mapped flows:

./joynare-nexus list-routes

Start the Server

./joynare-nexus serve

---

8. Health Check

Joynare Nexus provides a built-in health check endpoint to monitor the status of the ESB and its connected resources.

Configuration

You can customize the health check path in routes/server.yaml:

server:
  host: "0.0.0.0"
  listeners:
    - port: 9090
      protocol: "http"
  healthPath: "/status" # Defaults to /health

Response Format

The endpoint returns a detailed JSON object:

{
  "status": "UP",
  "timestamp": "2026-04-30T10:00:00Z",
  "version": "1.0.0",
  "uptime": "1h20m30s",
  "checks": {
    "database": {
      "MySQL_Prod": "UP",
      "Postgres_Dev": "DOWN: connection refused"
    },
    "flows": {
      "loaded": 42,
      "adapters": 12
    }
  }
}

• Status UP (200): All systems are operational.
• Status DEGRADED (503): One or more database connections are down, but the server is still running.

---

See Also

• Flow Service Concept
• The Pipeline
• HTTP Built-in Service