HTTP API Facade v2

Expose a stable HTTP contract in front of provider-specific Workflows so callers do not depend on Connection details, provider schemas, or internal orchestration.

Structure

Use one root HTTP receive Step, input validation, a domain Sub-Workflow, and one root HTTP respond Step. Keep provider-specific mappings in the domain Workflow and translate its result into a stable public response.

Define route placeholders and body fields deliberately. Return consistent success, validation, not-found, conflict, and dependency-error objects with appropriate status codes.

Security and browser access

Use an API Key scoped to the target Environment and assigned Workflow. Configure browser origins on the Environment; do not author platform-managed CORS headers in the response. Keep provider credentials in Connections.

Lifecycle

Treat the HTTP request/response shape as a versioned contract. Coordinate changes to the facade and Sub-Workflow, export OpenAPI for consumers, and promote through Environments with compatible Connection values.

Test invalid input, authorization, duplicate routes, provider timeout, cancellation, and large or streamed bodies as applicable.

Example: an order-status contract

Suppose clients need GET /orders/{orderId} while the provider uses a different identifier and field names. Define the facade's successful JSON response as {"orderId":"A100","status":"Dispatched"}. The domain Sub-Workflow looks up the provider record and maps its fields to those two public fields.

For an unknown order, return HTTP 404 with an authored body such as {"code":"order_not_found","orderId":"A100"}. These are example application contracts, not automatic platform responses. Map the chosen status and body into the single root respond Step.

Test a known and unknown order. The caller should receive the same public field names regardless of the provider's schema, and neither result should expose Connection values or raw provider diagnostics.

See also

See Publish a Workflow as an HTTP Endpoint, HTTP Workflow Request and Response, and Factor a Large Workflow.