API Orchestration Layer Template

Use orchestration when clients need data from three or more services for a single screen, when you need to reduce mobile network round trips, or when you want to insulate clients from backend service changes. Skip orchestration for simple CRUD operations that map cleanly to a single service. The [Technical PM Handbook](/technical-pm-guide) covers architecture decision frameworks for technical PMs.

Keep business logic out of the orchestration layer. Its job is to route, aggregate, and handle failures. If you find yourself writing conditional pricing rules or eligibility checks in the gateway, that logic belongs in a downstream service. Review orchestration endpoints quarterly and extract any accumulated business logic.

Orchestration uses a central coordinator (your BFF) that calls services in a defined sequence. Choreography uses events: services react to published events independently with no central controller. Orchestration is better for synchronous request/response flows (like rendering a page). Choreography is better for async workflows (like order fulfillment) where services can process independently. Many systems use both patterns for different use cases.

Pin your orchestration layer to specific downstream API versions and upgrade deliberately. Use a service registry or configuration file that maps each downstream call to a version. Test version upgrades in staging before production. When a downstream team plans a breaking change, they should notify the orchestration layer owner so the mapping can be updated.

GraphQL is a strong fit for orchestration because clients can request exactly the fields they need, reducing over-fetching. However, GraphQL adds complexity to error handling (partial failures in a single response), caching (field-level vs. endpoint-level), and monitoring (all requests hit one URL). If your team has GraphQL experience and your clients have varied data needs, consider it. For teams starting out, REST with well-defined BFF endpoints is simpler to operate. ---