API Orchestration¶

Overview¶

The API Orchestration feature in Yappes enables gateway-level multi-step API composition. Each orchestration exposes a single API endpoint while coordinating multiple backend interactions using sequencing, parallel execution, and conditional logic.

This capability allows organizations to:

Compose multiple backend APIs into one logical gateway endpoint.
Execute steps sequentially or in parallel for optimal flow design.
Centralize integration logic at the gateway without changing client applications.
Test orchestration flows before attaching them to production endpoints.
Monitor workflow runs with per-step HTTP details.

Why This Matters¶

Aggregate data from multiple backend services through one API call.
Standardize multi-step integrations at the gateway layer.
Improve observability with workflow run tracking and step-level drill-down.
Reuse orchestration policies across endpoints when appropriate.

Scope¶

Multi-step orchestration policy creation and management.
YAML-based flow definition with visual flow chart.
Endpoint-level policy attachment.
Test orchestration with sample request data.
Workflow run monitoring and execution preview.
Orchestration workflow templates (load, save, and manage).

Outcome¶

Faster multi-service integrations.
Consistent gateway-mediated API composition.
Reduced backend and client-side changes.
Testable, observable orchestration flows.

When to Use API Orchestration¶

Use this feature when:

A single API endpoint must coordinate calls to multiple backend services.
You need fan-out (parallel) or fan-in (sequential dependency) execution patterns.
Clients should call one endpoint instead of orchestrating multiple APIs themselves.
Integration logic belongs at the gateway rather than in each consumer or backend.
You want to test and trace multi-step flows before or after deployment.

When Not to Use API Orchestration¶

Do not use this feature when:

A single backend call is sufficient (simple passthrough).
The flow requires complex business logic, state management, or heavy data transformation — better handled in a dedicated backend service or microservice rather than gateway orchestration alone.

Prerequisites¶

Required Access and Permissions¶

Users must have:

API Manager access.
Permission to create orchestration workflows.
Permission to modify APIs.
Permission to attach policies.

System / Technical Requirements¶

At least one API with endpoints in the My APIs section.
Backend target.url values in orchestration steps that are reachable from the gateway.
Browser access to Yappes API Manager.

API Orchestration Features¶

Under Bridge → Orchestration, you can:

Create Orchestration Flow: Define a new orchestration policy with name, description, and Shared Flow setting.
Search Workflow: Search orchestration flows by name.
Attach or Detach: Attach or detach an orchestration policy at the endpoint level.
View Workflow: Open the flow designer in read-only mode.
Edit Workflow: Modify YAML steps and save the orchestration definition.
Delete Workflow: Permanently remove an orchestration policy (detaches from all endpoints).
Check Attached Endpoints: View how many endpoints are linked to a workflow.
Test Orchestration: Run a flow against sample request data and preview execution.
Monitor Workflow Runs: View execution history, filter by workflow, and drill down into step details.

The Workflows list displays: Flow Name, Attached Endpoints, Attach or Detach, Shared, View, Edit, and Delete.

YAML Reference (Console Schema)¶

The API Manager validates orchestration YAML as follows:

Rule	Requirement
`steps`	Non-empty array.
Each step	Must have `id` and `type`.
`sequential`	`target.kind` must be `external` with `url` and `method`.
`parallel`	Non-empty `children` array.
`dependsOn`	Lists step IDs that must complete before this step runs.
`internal` targets	Not accepted by the console editor.

Optional fields on steps (from the step template):

input.params — parameter mapping for the step.
output.saveas — name to store step output.
timeout — step timeout (e.g. 1000ms).

Example orchestration YAML:

orchestration:
  name: MyFlow
  execution: mixed   # use individual when Shared Flow is on

steps:
  - id: step1
    type: sequential
    target:
      kind: external
      url: https://api.example.com/resource
      method: GET
    dependsOn: []
    input:
      params:
        id: "${context.customerId}"
    output:
      saveas: step1Result
    timeout: 1000ms

  - id: parallelGroup
    type: parallel
    dependsOn:
      - step1
    children:
      - id: step2a
        type: sequential
        target:
          kind: external
          url: https://api.example.com/orders
          method: GET
      - id: step2b
        type: sequential
        target:
          kind: external
          url: https://api.example.com/loyalty
          method: GET

Conditional Steps¶

The orchestration overview mentions conditional logic, and the step template comment lists conditional as a step type. The console editor today validates sequential and parallel steps only.

To express dependencies in the console, use sequential steps with dependsOn. Conditional execution semantics at runtime are defined by the gateway engine.

Step-by-Step Implementation¶

Creating an Orchestration Policy¶

Step 1: Navigate to Orchestration¶

From the left navigation panel, open Bridge.
Select Orchestration.
On the Workflows tab, select Create Orchestration Flow.

Step 2: Define Orchestration Details¶

Field	Required	Description
Orchestration name	Yes	Unique name; cannot be changed after creation.
Description	No	Purpose of the flow (max 500 characters).
Shared Flow	Yes	Controls single- vs multi-endpoint attachment (see below).

Shared Flow behavior:

Shared Flow	Execution mode	Attachment
Off (default)	`mixed`	Policy can be attached to multiple endpoints.
On	`individual`	Policy can be attached to only one endpoint.

When Shared Flow is enabled, the toggle is locked after the policy is attached to any endpoint.

Step 3: Create and Open Flow Designer¶

Select Create.
You are redirected to the flow designer to define orchestration steps.

Success

The orchestration policy is created. Continue with Designing the Orchestration Flow to define your steps.

Designing the Orchestration Flow¶

Step 1: Understand the Flow Designer Layout¶

The flow designer includes:

Left panel — Orchestration Steps: List of steps and Add Step button.
Right panel — Orchestration Definition: YAML editor or flow chart view.
Toolbar: Edit metadata, toggle editor/flow chart, Test Orchestration, and Save.

Step 2: Define Steps in YAML¶

Edit the orchestration YAML in the editor.
Fix any validation errors shown in the editor.

Refer to the YAML Reference (Console Schema) section for supported step types, validation rules, and a full example.

Step 3: Add Steps¶

Select Add Step to insert a step template into the YAML editor.
Update step IDs, target.url values, and dependsOn for your use case.

Step 4: Toggle Flow Chart¶

Select the flow chart icon to visualize step dependencies.
Select the editor icon to return to YAML editing.

Step 5: Save the Orchestration Definition¶

Select Save to persist the orchestration definition.

View vs Edit mode

Mode	YAML editor	Add Step	Save
View	Read-only	Disabled	Disabled
Edit	Editable	Enabled	Enabled when YAML is valid

If you change the YAML without saving, a discard changes confirmation appears when switching views, opening Test Orchestration, or navigating back.

Step 6: Edit Metadata (Optional)¶

Select the edit icon in the toolbar to update the description or Shared Flow setting.
Shared Flow cannot be changed after the policy is attached to an endpoint.

Success

The orchestration definition is saved. Attach the policy to an endpoint using one of the methods below.

Method 1: Attaching from Bridge → Orchestration¶

Orchestration policies attach at the endpoint level only (not at the whole-API level).

Step 1: Locate the Orchestration Flow¶

On the Workflows tab, find the orchestration flow you want to attach.

Step 2: Open Attach or Detach¶

Select Attach or Detach on the orchestration row.

Step 3: Choose Attach or Detach¶

Select Attach to link the policy to endpoints, or Detach to remove it.

Step 4: Select Endpoints¶

Search and select the target API endpoints.

Step 5: Confirm the Action¶

Confirm the attach or detach operation.

Refer to Attachment Rules and Constraints for Shared Flow and one-policy-per-endpoint rules.

Method 2: Attaching from API Onboarding¶

Step 1: Open My APIs¶

From the left navigation panel, open Manage APIs.
Select My APIs.

Step 2: Open an Endpoint¶

Select an API and open an endpoint.

Step 3: Open the API Orchestration Tab¶

Select the API Orchestration tab in the endpoint details panel.

Step 4: Attach a Policy¶

Select Attach API Orchestration Workflow.
Choose an orchestration policy from the list.

Step 5: Save the API¶

Select Save on the API for the attachment to take effect.

To detach, use Detach on the attached workflow section, then save the API.

Refer to Attachment Rules and Constraints for attachment constraints.

Testing an Orchestration¶

Step 1: Open Test Orchestration¶

From the flow designer, select Test Orchestration.

Step 2: Add Test Data¶

Select Add Test Data (or Edit Test Data). Select Triggered By and API, then configure endpoint and parameters:

Field	Description
Triggered By	Select the trigger type shown in the UI
API	Select the target API
Endpoint	Target endpoint
Parameters	Key-value pairs with type: headers, query, or body

Step 3: Run the Test¶

Select Test Orchestration.
The system runs the flow and retrieves tracking data for the execution.

Step 4: Review Execution Preview¶

After the test completes, review:

Flow chart of executed steps.
Per-step accordion with:
Input: source and resolved parameters
Request: HTTP method, resolved URL, headers
Response: status, headers, body, duration

Monitoring Workflow Runs¶

Step 1: Open Workflow Runs¶

Go to Bridge → Orchestration.
Select the Workflow Runs tab.

Step 2: Filter Runs¶

Use the left sidebar to search by workflow name.
Select All Workflows or a specific orchestration policy.

Step 3: View Run Details¶

The table shows workflow name, triggered by, date/time, and a View action.

Select View to open:

Flow chart merged with YAML and tracking data.
Step accordion with HTTP details (same panels as test preview).
Trigger details: API URL, method, headers, query parameters, and request body.

Attachment Rules and Constraints¶

Rule	Behavior
Attachment level	Endpoint level only — not whole API.
Shared Flow on	Policy attachable to exactly one endpoint; attaching to multiple endpoints fails.
Shared Flow toggle	Locked once the policy is attached to any endpoint.
One policy per endpoint	Only one orchestration workflow per endpoint in API onboarding.
After attach (onboarding)	Save the API for changes to take effect.
Delete policy	Deletes the policy and detaches from all attached endpoints.

Understanding the Interface¶

Section	Purpose
Bridge	Mediation and composition tools.
Orchestration → Workflows	List, create, attach, edit, and delete orchestration policies.
Orchestration → Workflow Runs	Execution history and drill-down.
Flow designer	YAML editor, flow chart, add step, save, and test.
API Orchestration tab	Attach or detach at endpoint level during API onboarding.
Bridge → Templates	Reusable orchestration workflow templates — see Templates.

Templates¶

Orchestration workflow templates let you save and reuse YAML step definitions. You can load templates in the flow designer or manage them centrally under Bridge → Templates.

See Templates for create, save, load, edit, and delete instructions.

Policy Evaluation Order¶

When a client calls an endpoint with an orchestration policy attached:

Request enters the gateway.
Security policies execute (authentication, authorization, IP rules, etc.).
Orchestration policy runs — sequential and parallel step HTTP calls execute according to the YAML definition.
Other gateway policies on the response path run as configured.
Response is returned to the client.

Exact ordering relative to transformation, throttling, or other policies may depend on your gateway configuration. Orchestration runs when the attached endpoint is invoked and operates within the gateway execution context.

Impact of Policy Changes¶

YAML changes affect every endpoint attached to that policy.
Deleting a policy detaches all endpoints and removes composed behavior for those clients.
Shared Flow cannot be changed after attach; create a new policy if you need different attachment behavior.
Test in the designer, attach to a staging endpoint, validate in Workflow Runs, then promote to production.

Example Use Case: Customer Profile Aggregation¶

A single gateway endpoint composes customer data from multiple backends:

getCustomer — sequential GET to fetch the customer record.
parallelGroup — parallel GETs for orders and loyalty, depending on getCustomer.
Client calls one endpoint; the gateway orchestrates the rest.

orchestration:
  name: CustomerProfile
  execution: mixed

steps:
  - id: getCustomer
    type: sequential
    target:
      kind: external
      url: https://api.example.com/customers/{id}
      method: GET
    dependsOn: []
    input:
      params:
        id: "${context.customerId}"

  - id: fetchRelated
    type: parallel
    dependsOn:
      - getCustomer
    children:
      - id: getOrders
        type: sequential
        target:
          kind: external
          url: https://api.example.com/orders
          method: GET
      - id: getLoyalty
        type: sequential
        target:
          kind: external
          url: https://api.example.com/loyalty
          method: GET

Verification and Testing¶

To confirm orchestration in a staging or production-like environment:

Attach the policy to a test endpoint and save the API.
Invoke the endpoint with valid credentials and a representative payload.
Open Workflow Runs and confirm a new run appears.
Drill into the run and verify per-step status codes and response bodies.
Confirm total duration and step order match expectations.

Success Indicators¶

No YAML validation errors in the designer.
Test orchestration completes with expected step results.
Live invocations appear in Workflow Runs.
All steps return expected HTTP status codes (typically 2xx).

Best Practices¶

Practice	Reason
Test before attach	Catch YAML and routing errors early.
Use descriptive flow names	Easier search and Workflow Runs filtering.
Prefer Shared Flow off for reusable flows	Attach the same composition to multiple endpoints.
Use Shared Flow on for endpoint-specific flows	Isolated single-endpoint execution.
Version flows via naming (e.g. `CustomerFlow-v2`)	Safer rollback and change tracking.
Detach before delete in production	Planned migration window for dependent clients.
Keep step IDs stable	Preserves `dependsOn` references and tracking clarity.

Troubleshooting¶

Issue	Possible Cause	Resolution
YAML save fails	Validation error	Ensure each step has `id`, `type`, valid `target.url`, and `target.method`; parallel steps need `children`.
Shared Flow locked	Policy already attached	Detach from all endpoints first, or create a new policy.
Cannot attach to multiple endpoints	Shared Flow enabled	Create the policy with Shared Flow off, or use separate policies.
Only one workflow per endpoint	By design	Detach the existing workflow before attaching another.
Test returns no tracking data	Test or endpoint misconfiguration	Verify API, endpoint, and parameter selections; check YAML validity.
Orchestration not running live	Not attached or API not saved	Attach policy and save the API.
Run not visible immediately	Tracking delay	Refresh Workflow Runs after a few seconds.
Conditional step won't save	Not validated in console	Use `sequential` with `dependsOn` instead.
Changes not reflected	API not saved after attach	Save the API from onboarding after attaching the policy.

Frequently Asked Questions¶

Does orchestration modify backend services?
No. Composition runs at the gateway; backends receive individual step calls as defined in the YAML.

Can I attach multiple orchestration policies to one endpoint?
No. Only one orchestration workflow per endpoint.

Can I attach at the API level?
No. Attachment is at the endpoint level only.

What is Shared Flow?
When enabled, the policy uses individual execution and can attach to only one endpoint. When disabled (default), it uses mixed execution and can attach to multiple endpoints.

Do I need to change client or backend code?
Clients call the single exposed endpoint. Backend services are invoked as defined in step target.url values; no orchestration-specific backend changes are required.

How is this different from Transformation Workflow?
Transformation Workflow converts payload formats (XML ↔ JSON). Orchestration composes multiple backend calls into one gateway flow.

What is the difference between console YAML and engine YAML?
The API Manager validates and stores the console schema documented above. The gateway engine may support additional fields and runtime features beyond what the console editor validates.

Pro Tip

Use Test Orchestration in the flow designer with realistic headers, query, and body parameters before attaching a policy to production endpoints. Review the execution preview and Workflow Runs drill-down to validate every step before go-live.