bff-recipe

A Backend For Frontend aggregation library

API producers build endpoints the way they want. Consumers compose them the way they need. One annotation bridges the gap. No tug of war between team priorities. No custom aggregation endpoints. No wasted round trips.

Add one annotation to your Spring controllers you wish to aggregate. Send one request from your client and get your aggregated data back in one response.

You get a Spring Boot starter, a TypeScript types package, and built-in discovery & validation endpoints.

How it works

Two things happen. Backend adds one annotation per API. Frontend sends one JSON request.

@BffIngredient(recipe = "payments", name = "getAccount")
@GetMapping("/api/accounts/{accountId}")
public ResponseEntity<Account> getAccount(...) { }

@BffIngredient(recipe = "payments", name = "getInvoices")
@GetMapping("/api/invoices")
public ResponseEntity<InvoiceList> getInvoices(...) { }

@BffIngredient(recipe = "payments", name = "getPaymentMethods")
@GetMapping("/api/payment-methods")
public ResponseEntity<PaymentMethodList> getPaymentMethods(...) { }

@BffIngredient(recipe = "payments", name = "submitPayment")
@PostMapping("/api/payments")
public ResponseEntity<Confirmation> submitPayment(...) { }

POST /bff/payments
{
  "ingredients": [
    { "id": "getAccount",
      "params": { "accountId": "acc-123" } },
    { "id": "getInvoices",
      "map": { "query": {
        "billingGroupId":
          "getAccount::body::${billingGroupId}"
      }}},
    { "id": "getPaymentMethods",
      "map": { "query": {
        "customerId":
          "getAccount::body::${customerId}"
      }}}
  ]
}

The framework figures out the dependency graph, runs independent ingredients in parallel, propagates auth, and returns everything in one response. No aggregation logic to write. No new endpoints to maintain.

Example of client-side latency

A payments page needs account info, invoices, and payment methods. Assume 700ms network latency per round trip and 100ms server processing. A good frontend team will parallelize what it can — but the dependency chain still forces sequential hops:

Even with a smart frontend parallelizing what it can, the dependency chain forces multiple round trips. With bff-recipe, the same chain resolves server-side — the client sends one request and gets everything back.

Quick Start

1. Add the starter to your existing Spring Boot project.

dependencies {
    implementation 'io.github.tayyab23:bff-spring-lib:1.2.0'
}

<dependency>
    <groupId>io.github.tayyab23</groupId>
    <artifactId>bff-spring-lib</artifactId>
    <version>1.2.0</version>
</dependency>

1. Annotate any controller.

@BffIngredient
@GetMapping("/api/accounts/{accountId}")
public ResponseEntity<Account> getAccount(@PathVariable String accountId) { ... }

1. Test your new bff.

{
  "ingredients": [
    { "id": "getAccount", "params": { "accountId": "acc-123" } }
  ]
}

{
  "executionOrder": ["getAccount"],
  "results": {
    "getAccount": {
      "status": 200,
      "body": { "accountId": "acc-123", "name": "BFF" }
    }
  }
}

For Frontend Teams

Your backend team adds @BffIngredient to their controllers. You compose recipes and get typed responses. Install the type definitions — they add zero bytes to your runtime bundle.

npm install @bff-recipe/types --save-dev

import type { RecipeRequest, RecipeResponse } from '@bff-recipe/types';
import axios from 'axios';

interface Account { accountId: string; plan: string; billingGroupId: string; }
interface InvoiceList { items: { id: string; amount: number }[]; total: number; }

type PaymentsPage = { getAccount: Account; getInvoices: InvoiceList; };

const request: RecipeRequest = {
  ingredients: [
    { id: 'getAccount', params: { accountId: 'acc-123' } },
    { id: 'getInvoices', map: { query: { billingGroupId: 'getAccount::body::${billingGroupId}' } } }
  ]
};

const { data } = await axios.post<RecipeResponse<PaymentsPage>>('/bff/payments', request);

data.results.getAccount.body.plan;             // ✓ string
data.results.getInvoices.body.items[0].amount; // ✓ number
data.results.nonExistent;                      // ✗ compile error

Use import type and your bundler strips the import entirely — the types exist only at compile time. Works with fetch, Axios, ky, or any HTTP client. Full reference →

How it compares

There are real alternatives. bff-recipe indexes on minimum setup cost and maximum API delivery speed — the shortest path from existing REST endpoints to a composed frontend response. Here's an honest look at the trade-offs.

Still have questions about the design trade-offs? See the FAQ →

Two Modes

bff-recipe discovers ingredients one of two ways. Pick the one that fits your architecture — the runtime behavior is identical either way.

@BffIngredient(
    recipe = {"payments", "dashboard"},
    name   = "getAccount"
)
@GetMapping("/api/accounts/{accountId}")
public ResponseEntity<Account> getAccount(
    @PathVariable String accountId) { ... }

// mode: annotation (default)
// Repeat for each endpoint you want
// to include in a recipe.

bff-recipe:
  mode: config
  ingredients:
    getAccount:
      method: GET
      path: /api/accounts/{accountId}
    getInvoices:
      method: GET
      path: /api/invoices
  recipes:
    payments:
      ingredients: [getAccount, getInvoices]

Proxy Dispatch

When your APIs live in separate services — other Lambdas, ECS tasks, or third-party systems — use proxy-url to aggregate across them without writing proxy controllers. The BFF becomes a dedicated aggregation layer that forwards requests to external services.

bff-recipe:
  mode: config
  ingredients:
    getAccount:
      method: GET
      path: /api/accounts/{accountId}
    getInvoices:
      method: GET
      path: /api/invoices
    getShipping:
      method: GET
      path: /api/shipments/{orderId}
      proxy-url: ${SHIPPING_SERVICE_URL:http://localhost:8082}
  recipes:
    payments:
      proxy-url: ${API_BASE_URL:http://localhost:8080}
      ingredients: [getAccount, getInvoices, getShipping]

Resolution order

Ingredient proxy-url → Recipe proxy-url → local in-process dispatch. Same override chain philosophy as headers — each level narrows.

Mixing local and proxy

Ingredients without a proxy-url (and no recipe-level default) dispatch locally through the Spring MVC chain. You can mix both in the same recipe — some controllers in-process, others proxied to external services.

@BffIngredient

Annotation mode details. Place it on any mapped controller method.

Annotation attributes

Override chain

Settings can be specified at multiple levels. Each level can only narrow what the level above allows — never widen it.

Common Configuration

These settings apply to both modes. All are optional — the defaults work out of the box.

bff-recipe:
  enabled: true
  base-path: "/bff"
  schema:
    enabled: false          # GET /bff/{recipe}/schema
  validate:
    enabled: false          # POST /bff/{recipe}/validate
  debug:
    enabled: false
    mask-headers: ["Authorization", "X-Api-Key", "Cookie"]
  execution:
    parallel-threads: 10
    ingredient-timeout-ms: 5000
    recipe-timeout-ms: 15000
    max-ingredients: 10
  headers:
    forward:
      enabled: true
      blocked: ["Host", "Content-Length", "Connection"]
    custom:
      enabled: false
      blocked: ["Authorization", "Host"]
    mapping:
      enabled: false
      blocked-sources: ["Set-Cookie"]

Execution Model

The framework builds a DAG from your recipe, topologically sorts it into levels, and runs each level in parallel.

Level 0: [getAccount]                        ← runs alone
Level 1: [getInvoices, getPaymentMethods]    ← parallel (both depend on getAccount)
Level 2: [submitPayment]                     ← runs alone (depends on both above)

Dependencies are inferred from :: expressions automatically. Use dependsOn only for ordering without data flow.

Thread pool

Ingredients within a level run in parallel on a shared fixed thread pool. The pool is shared across all concurrent recipe requests.

Middleware & Security

Every ingredient dispatches through Spring's full MVC pipeline — not a shortcut, not a direct method call. This means your existing middleware applies per-ingredient, automatically:

Think of it as handing the backend a shopping list. The backend walks through the store, picks up each item (hitting every checkpoint along the way), and brings it all back in one bag.

Security Model

The client controls which ingredients to call and what values to pass via the map block. Here's what that means for security — and why it doesn't escalate privileges.

What the client can do

What the client cannot do

Header System

Three sources merged per ingredient, in precedence order. Server policy always wins over client intent.

{
  "id": "submitPayment",
  "headers": {
    "forward": true,
    "forwardOnly": ["Authorization"],
    "custom": { "X-Idempotency-Key": "idem-abc-123" },
    "mappings": { "getAccount.X-Trace-Id": "X-Upstream-Trace" }
  }
}

Request Format

Send a POST to /bff/{recipe}. The URL selects the recipe — no need to specify it in the body.

{
  "debug": false,
  "failFast": false,
  "headers": { "forward": true, "forwardOnly": ["Authorization"] },
  "ingredients": [
    {
      "id": "getAccount",
      "params": { "accountId": "acc-123" }
    },
    {
      "id": "getInvoices",
      "map": {
        "query": {
          "billingGroupId": "getAccount::body::${billingGroupId}",
          "limit": 10
        }
      }
    },
    {
      "id": "submitPayment",
      "dependsOn": ["getInvoices"],
      "map": {
        "body": {
          "accountId": "getAccount::body::${accountId}",
          "invoiceId": "getInvoices::body::${items[0].id}",
          "amount":    "getInvoices::body::${items[0].amount}",
          "currency":  "USD",
          "paymentMethodId": "pm-visa-4242"
        }
      },
      "headers": {
        "custom": { "X-Idempotency-Key": "idem-abc-123" }
      }
    }
  ]
}

Request fields & what the server can override

Expressions & Mapping

Values in the map block are either a reference (contains ::) or a literal (no ::).

"map": {
  "path":  { "accountId": "getAccount::body::${accountId}" },
  "query": { "billingGroupId": "getAccount::body::${billingGroupId}", "limit": 20 },
  "body":  { "invoiceId": "getInvoices::body::${items[0].id}", "note": "auto-pay" }
}

Array Operators

When one ingredient returns a list and the next ingredient needs values from that list, array operators let you collect, slice, and filter — all resolved into a single value passed to one batch call. No fan-out. No N+1.

Operator Reference

Type Coercion

Filter values are auto-detected:

Edge Cases

Real-World Example: Order Enrichment

A frontend needs an order management dashboard. The backend has three separate systems: an Order Service (returns 100 orders), a Fulfillment Service (batch shipping status), and a Payment Service (batch payment status). Each downstream system only needs a subset of the orders.

{
  "ingredients": [
    {
      "id": "getOrders",
      "params": { "customerId": "cust-42" }
    },
    {
      "id": "batchGetShipping",
      "map": {
        "body": {
          "orderIds": "getOrders::body::${orders[?status!=CANCELLED].orderId}"
        }
      }
    },
    {
      "id": "batchGetPayments",
      "map": {
        "body": {
          "orderIds": "getOrders::body::${orders[?billing.method!=FREE_TRIAL&&status in (CONFIRMED,SHIPPED)].orderId}"
        }
      }
    }
  ]
}

Execution:

Level 0: [getOrders]                              ← fetches 100 orders
Level 1: [batchGetShipping, batchGetPayments]     ← run in parallel
           ↑ receives ~90 non-cancelled IDs         ↑ receives ~60 paid+confirmed IDs

One network round trip. Three systems queried. Array operators handle the subsetting — no client-side filtering, no intermediate APIs, no N+1.

More Examples

"invoiceIds": "getInvoices::body::${items[*].id}"

"invoiceIds": "getInvoices::body::${items[?status==OVERDUE&&amount>100].id}"

"invoiceIds": "getInvoices::body::${items[?status in (OVERDUE,UNPAID)].id}"

"descriptions": "getInvoices::body::${items[?description==REG(^Pro Plan.*)].description}"

"firstPage": "getOrders::body::${orders[:10].orderId}"
"recentFive": "getOrders::body::${orders[-5:].orderId}"

"usOrders": "getOrders::body::${orders[?billing.region==US&&couponCode exists].orderId}"

Response Format

{
  "executionOrder": ["getAccount", ["getInvoices", "getPaymentMethods"], "submitPayment"],
  "results": {
    "getAccount":        { "status": 200, "body": { "accountId": "acc-123", "plan": "PRO" } },
    "getInvoices":       { "status": 200, "body": { "items": [...], "total": 249.99 } },
    "getPaymentMethods": { "status": 403, "body": { "error": "AccessDenied" } },
    "submitPayment":     { "status": 422, "body": { "error": "DependencyFailed", "message": "Skipped: dependency 'getPaymentMethods' failed" } }
  }
}

Error Handling

TypeScript Types

@bff-recipe/types gives you compile-time safety for recipe requests and responses. It ships only type definitions — zero bytes added to your runtime bundle via import type. Use it with whatever HTTP client you already have.

npm install @bff-recipe/types --save-dev

With Axios

import type { RecipeRequest, RecipeResponse } from '@bff-recipe/types';
import axios from 'axios';

// Your own types — from OpenAPI codegen, Smithy, or hand-written
interface Account { accountId: string; plan: string; billingGroupId: string; }
interface InvoiceList { items: { id: string; amount: number }[]; total: number; }

type PaymentsPage = { getAccount: Account; getInvoices: InvoiceList; };

const request: RecipeRequest = {
  ingredients: [
    { id: 'getAccount', params: { accountId: 'acc-123' } },
    { id: 'getInvoices', map: { query: { billingGroupId: 'getAccount::body::${billingGroupId}' } } }
  ]
};

const { data } = await axios.post<RecipeResponse<PaymentsPage>>('/bff/payments', request);

data.results.getAccount.body.plan;             // ✓ string
data.results.getInvoices.body.items[0].amount; // ✓ number
data.results.nonExistent;                      // ✗ compile error

With fetch

import type { RecipeRequest, RecipeResponse } from '@bff-recipe/types';

const res = await fetch('/bff/payments', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(request),
});
const data: RecipeResponse<PaymentsPage> = await res.json();

Discovery Endpoints

Both disabled by default. Enable per environment — they're protected by your existing Spring Security config.

{
  "recipe": "payments",
  "ingredients": {
    "getAccount":        { "method": "GET",  "path": "/api/accounts/{accountId}", "responseType": "Account" },
    "getInvoices":       { "method": "GET",  "path": "/api/invoices",             "responseType": "InvoiceList" },
    "submitPayment":     { "method": "POST", "path": "/api/payments",             "responseType": "PaymentConfirmation" }
  }
}

{
  "valid": false,
  "errors": [
    { "ingredient": "unknownIngredient", "error": "Ingredient 'unknownIngredient' is not registered in recipe 'payments'" }
  ]
}

Observability

Zero config. Auto-activates when the relevant library is on the classpath.

Example App

A fully working Spring Boot application demonstrating all patterns — path variables, query params, POST bodies, header forwarding, multi-recipe membership, and mock auth.

curl -X POST http://localhost:8080/bff/payments \
  -H "Authorization: Bearer demo-token" \
  -H "Content-Type: application/json" \
  -d '{
    "ingredients": [
      { "id": "getAccount", "params": { "accountId": "acc-123" } },
      { "id": "getInvoices", "map": { "query": { "billingGroupId": "getAccount::body::${billingGroupId}" } } },
      { "id": "getPaymentMethods", "map": { "query": { "customerId": "getAccount::body::${customerId}" } } }
    ]
  }'

Anti-Patterns

An aggregation layer is powerful — and easy to misuse. These are the patterns to avoid, including ones that bff-recipe can accidentally enable if you're not careful.

One aggregation for all

One recipe with 10 ingredients that returns everything for every screen. It starts as a convenience and becomes unmaintainable. Different screens need different data — use named recipes (payments, dashboard, checkout) to keep each one focused.

Chatty Ingredients

12 ingredients in a recipe where each depends on the previous one. You've moved the waterfall from the client to the server — the latency is the same, you just can't see it anymore. If your DAG is a straight line, your APIs weren't designed for aggregation.

Business Logic in the Map Block

Trying to use array operators as a transformation engine — filtering, slicing, and reshaping data that should be the API's responsibility. The map block moves data between ingredients. If you're writing complex compound filters to work around an API that returns too much, fix the API.

Skipping Batch Endpoints

You have an API that returns 50 order IDs and another API that accepts one order ID at a time. Don't build 50 ingredients. Build a batch endpoint (POST /api/orders/details) that accepts a list, then use [*] to collect the IDs and pass them in one call.

Leaking Internal Structure

Enabling the schema endpoint in production and exposing your internal API paths, parameter names, and response types to the public internet. The schema endpoint is a development tool.

Ignoring Idempotency on Writes

Including a submitPayment ingredient in a recipe without idempotency protection. If the client retries the recipe on a network timeout, the payment gets submitted twice. Every mutating ingredient should support an idempotency key.

Premature Normalization

Refusing to duplicate data across ingredient responses in the name of DRY. An API response is not your source of truth — your database is. If the order detail response needs the customer name embedded, embed it. Don't force the client to join data from two ingredients.

Synchronous Heavy Lifting

Putting a long-running operation (report generation, bulk export) as an ingredient. The recipe has a timeout, and a 30-second ingredient blocks the entire recipe. Heavy operations should be async.

When You Actually Want SSR

Your frontend team builds increasingly complex recipes, parses the JSON response, maps it into components, and renders a page — every time. If the end result is always a fully rendered page and not an interactive SPA that manages state, you're doing server-side rendering with extra steps.

BFF aggregation is the right tool when you have a rich client that needs raw JSON from multiple APIs in one round trip — SPAs, mobile apps, or any client that manages its own state and renders interactively. It's the wrong tool when the real problem is "we want the server to render the page."

FAQ — Design Decisions

These are deliberate constraints, not missing features. Each one keeps the library simple and the aggregation layer free of business logic.