AI and Bot Integration Guide

1. Non-negotiable rules for agents

1. Authenticate before any management API write call.
2. Parse the response envelope and branch on success.
3. For app route upsert endpoints, submit exactly one route per file/content.
4. Always include explicit route ID and ensure it matches target route ID.
5. Never bind ingress paths under reserved internal prefixes.
6. Treat .bar + buzen.json as canonical deployable artifact.
7. Validate payloads against provided schemas before submit.

2. Recommended output profiles

Route YAML profile

- route:
    id: <route-id>
    from:
      uri: "<source-uri>"
      steps:
        - <step-type>:
            <step-config>

Manifest profile

{
  "name": "<app-name>",
  "version": "1.0.0",
  "routes": [
    { "file": "routes/<route-id>.yaml", "autoStart": true }
  ]
}

Use explicit route files under routes/ and avoid multi-route documents for bot-generated updates.

3. Deterministic API sequences

Deploy archive

1. Login
2. POST /api/v1/apps multipart upload
3. GET /api/v1/apps/{appId}
4. GET /api/v1/apps/{appId}/routes

Create empty app and add first route

1. Login
2. POST /api/v1/apps JSON create shell
3. POST /api/v1/apps/{appId}/routes route upsert
4. Read back content endpoint for verification

Safe route update

1. Fetch current route content
2. Generate new single-route YAML with same route ID
3. Submit PUT /api/v1/apps/{appId}/routes/{routeId}/content
4. On failure, parse envelope and decide retry/rollback

Route duplication with ingress conflicts

1. Read duplicate capabilities endpoint
2. Choose FAIL, AUTO_RENAME, or MANUAL strategy
3. Submit duplicate request with conflict policy
4. If 409, parse conflicts and retry with explicit remaps

4. Source-first validation

Use source-synced contracts first, then compatibility schemas for payload shaping.

• source-snapshot.json (active source commit + runtime versions)
• management-endpoints.json (controller-derived endpoint map)
• Runtime OpenAPI: /api-docs and /swagger-ui.html
• Compatibility profile: buzen-archive-manifest.schema.json
• Compatibility profile: app-route-upsert-request.schema.json
• Compatibility profile: app-route-duplicate-request.schema.json
• Compatibility profile: buzen-flow-designer-route.schema.json

5. Error branching logic for bots

if HTTP 400 -> fix payload and retry
if HTTP 401 -> re-authenticate
if HTTP 403 -> escalate role error
if HTTP 404 -> verify appId/routeId
if HTTP 409 -> resolve conflict then retry
if HTTP 500 -> bounded retry with backoff, then escalate

Always record request IDs, app IDs, and route IDs in bot logs for replay and audit.

6. Prompt template for route generation

Generate a Buzen ESB route for app <appId>.
Constraints:
- Single route per file.
- Explicit route.id = <routeId>.
- YAML follows canonical route/from/steps shape.
- Do not bind ingress under /api/v1, /actuator, /console, /api-docs, /swagger-ui.
- Prefer dataSourceRef for DB access.
- Provide matching AppRouteUpsertRequest payload.