YAML Authoring Guide

1. Canonical route shape

Recommended structure for all authored routes:

- route:
    id: order-processing
    from:
      uri: "platform-http:/orders?httpMethodRestrict=POST"
      steps:
        - unmarshal:
            json: {}
        - setHeader:
            name: correlationId
            simple: "${header.X-Correlation-ID}"
        - to:
            uri: "jms:queue:orders.in"

Alternate top-level shape is accepted, but wrapped form with route: is preferred for tooling consistency.

2. Core authoring rules

• Use explicit route IDs. Do not rely on auto-generated Camel IDs.
• Include from.uri and explicit steps list.
• Prefer kebab-case route IDs for readability and deterministic APIs.
• Keep one functional concern per route for easier lifecycle control.
• Add explicit error handling for non-trivial integrations.

3. Single-route constraints in app APIs and Flow Designer

Runtime can load multi-route files, but app route create/update endpoints enforce single-route content:

• POST /api/v1/apps/{appId}/routes
• PUT /api/v1/apps/{appId}/routes/{routeId}/content

Flow Designer import is also single-document, single-route oriented. Unsupported constructs may be preserved as custom nodes with warnings.

Schema: buzen-flow-designer-route.schema.json

4. Route IDs, step IDs, and collisions

• Route IDs must be unique in active runtime context.
• Route duplication workflows can auto-rename ingress paths, but route ID uniqueness still applies.
• When app APIs detect duplicate Flow Designer generated step IDs (node_*), Buzen can regenerate them.
• Duplicate non-generated user step IDs must be manually corrected.

5. Ingress path safety

Inbound HTTP style routes are validated against reserved platform paths. Conflicts cause deployment/update failure.

Typical reserved prefixes:

• /api/v1 (management API base path)
• /actuator
• /console
• /ws
• /api-docs, /swagger-ui, /v3/api-docs

6. Variables, placeholders, and data sources

Use global variable placeholders:

{{partner.base-url}}
{{db.user}}

Manage these via:

• /api/v1/variables
• /api/v1/data-sources for managed JDBC sources

DB routes should prefer dataSourceRef over embedding credentials in URIs.

- route:
    id: customer-lookup
    from:
      uri: "direct:lookup"
      steps:
        - to:
            uri: "buzen-db:execute?dataSourceRef=crm-db&query=select+*+from+customers+where+id=:#id"

7. Reference patterns

Pattern: HTTP -> JMS

- route:
    id: webhook-to-jms
    from:
      uri: "platform-http:/webhook/orders?httpMethodRestrict=POST"
      steps:
        - unmarshal:
            json: {}
        - to:
            uri: "jms:queue:orders.in"

Pattern: Robust outbound HTTP with dead letter

- route:
    id: outbound-partner-call
    errorHandler:
      deadLetterChannel:
        deadLetterUri: "jms:queue:dead.letter"
        useOriginalMessage: true
        maximumRedeliveries: 3
        redeliveryDelay: 1000
    from:
      uri: "direct:invokePartner"
      steps:
        - to:
            uri: "https://partner.example.com/api/orders"

Pattern: split + aggregate

- route:
    id: split-and-aggregate
    from:
      uri: "direct:bulk"
      steps:
        - split:
            simple: "${body.items}"
            steps:
              - to:
                  uri: "bean:itemProcessor?method=process"
        - to:
            uri: "bean:resultCollector?method=finish"

8. Pre-deploy checklist

• Route contains explicit id and valid from.uri.
• One route per file for app API and Flow Designer workflows.
• No reserved ingress collisions.
• Variables and dataSourceRef values exist in target environment.
• Route and step IDs are unique.
• Manifest autoStart values reflect intended startup behavior.