robsonkades/agent-skills/api-gateway-and-bff

API Gateway and BFF

An edge is a contract with clients and services, not a place to collect every concern. Use this skill to choose its responsibilities, review an existing composition, or implement a justified slice. Retaining an adequate API and ingress is a valid outcome. A BFF serves a client experience; its name does not authorize another deployable.

Discover the constraint before the topology

Inspect a representative client journey, actual request/response contracts, consumer versions, gateway routes/filters, backend entry points, deployment paths and ownership. Collect the evidence that can change the choice:

• Which client requirements differ: payload, interaction sequence, bandwidth, offline

behavior, release cadence, browser session or accessibility needs? A different UI framework alone does not establish a different backend contract.

• Which calls are sequential, which are independent, and what measured latency, bytes

or client complexity needs to change? Count downstream calls as well as browser calls.

• Which service owns each business decision, object/tenant authorization and mutation?

Include internal callers and direct access paths that bypass the gateway.

• Which policies already exist at CDN, ingress, gateway, mesh, client and service?

Find effective authentication, header handling, timeouts, retries and admission limits.

• Who deploys, supports and evolves the edge? Can a client-specific change ship without

coordinating unrelated clients? How long do old mobile or partner clients remain live?

For Java/Spring work, inspect toolchains, resolved Boot/Cloud/Framework/Security versions, the actual HTTP clients and Servlet/reactive execution model before selecting APIs. This architectural skill declares no universal Java or Spring baseline. Reference mechanisms are version-qualified; adopting it never implies an upgrade or new dependency.

Separate found facts, agreed contracts and hypotheses. If journey evidence is absent, propose the smallest useful trace or contract comparison; do not claim latency savings. If partial responses, trust or ownership are unspecified, identify the consequential gap and keep that choice conditional while completing independent analysis. Ask only what repository evidence cannot settle. A local route repair need not reopen the whole design.

Choose the owner and the smallest useful boundary

A gateway and BFF may share a process, be separate, or be unnecessary. Decide using change ownership, failure isolation, runtime compatibility and operational cost. A shared gateway plus optional BFFs is one topology, not a required chain. Keep route configuration owned and reviewable; unrestricted dynamic destinations can turn a gateway into an open proxy.

Write a compact responsibility matrix for the affected path: concern, authoritative owner, enforcement location, bypass behavior and verification. Place reusable entry policy at the agreed edge; client-specific shaping/composition at the BFF; domain rules, authoritative state and object/tenant checks at the owning operation. Early rejection at the edge can supplement those checks. It cannot make a bypassing caller safe by itself.

The BFF may map data, sequence presentation reads and own client-session state. It must not become the only place that enforces stock reservation, credit limits or payment authorization. Forward a business command to its owner; durable multi-step business coordination needs an explicit application/process owner and recovery contract. Do not implement it as a series of gateway filters.

For contract evolution, use rpc-and-api-contracts when needed; for coarse service operations and DTO boundaries, use remote-facade-and-dto. Replica eligibility/selection belongs to load-balancing-and-routing. Detailed fan-out mechanisms belong to scatter-gather, and retry ownership/budgets to retries-and-backoff. These are optional handoffs for the relevant decision, not prerequisites for every edge task.

When a composed read needs a projection, a freshness contract or query recovery, use cross-service-query-design for that read-path decision; keep client representation and edge failure behavior here. When the task changes trust boundaries, workload identity or delegated authority, use service-identity-and-trust for that architecture; retain the edge's enforcement and propagation contract below. Neither handoff is required for an unrelated route or presentation change.

Make composition and trust explicit

For each composed endpoint, identify mandatory and optional contributions, the consistency meaning, maximum fan-out, response bytes and end-to-end deadline. Reserve time to authorize, transform and send the answer. Bound downstream concurrency and queueing as well as wait time; preserve existing sufficient limits. A timeout on each call does not bound all work when calls run sequentially, retry or wait for a connection.

Specify what happens when a required contribution fails and what an optional absence means. Do not replace unavailable data with an empty list, zero price or a business approval. Expose missing/stale state in the contracted representation; distinguish authorization denial from transient failure internally without leaking unauthorized existence externally. Validate the client renderer against that contract, not just the BFF's HTTP status. Cancellation should release local work/resources; it does not prove a remote effect stopped.

Authenticate the relevant caller at each trust boundary and identify what represents the workload, end user and tenant. Relay a token only when its intended resource, scope and delegation contract permit that receiver. An authenticated gateway, forwarded header or valid signature alone does not authorize an operation. Strip client-supplied identity and proxy headers at the appropriate untrusted boundary before setting trusted values; document how the receiving service verifies their origin and rejects alternate paths. Never weaken audience validation to make relay work. Session-cookie BFFs also need browser/CSRF controls; CORS is not authorization.

When designing partial responses, an identity hop, cache policy or hostile-path tests, read composition and trust contracts. When implementing with Spring, choosing Gateway WebFlux versus MVC, or reviewing TokenRelay, read Spring integration. Keep framework-specific security wiring with the appropriate specialist; the existing spring-security-for-apis covers Servlet APIs and does not cover WebFlux. Use spring-http-clients for outbound wiring.

Deliver and verify the affected slice

For design, deliver the selected boundary or no-change, rejected viable alternative, responsibility matrix, changed client/edge/service contract and the check that could disprove the choice. For review, attach evidence and consequence to each finding; do not require code changes to finish a requested review. For implementation, change the route/controller, consumer behavior, downstream contract tests and operational settings needed for the slice. Reuse the project's conventions and managed components.

Keep boundary DTOs deliberate; do not expose JPA entities or downstream exception details. Avoid shared business-model libraries that force every client/BFF to release together. Preserve old clients for the declared compatibility window. Name who changes each contract, how routes are activated, and how traffic can return to the previous path without losing session validity or duplicating commands. Shadow only side-effect-free traffic with an approved data policy; ordinary traffic mirroring can repeat mutations.

Choose validation by the changed claim:

• Representation: exercise old/new consumers, missing versus empty contributions,

required failure and optional degradation; verify both payload and client behavior. For conditional reads, check the final view's validators and 304 handling through the effective filters; a downstream conditional response may describe only one contribution.

• Trust: test forged user/tenant/proxy headers, wrong audience, cross-tenant object

access, and direct service access. The receiving operation must enforce its policy.

• Resource bounds: stall a dependency or exhaust its pool, exceed fan-out/body limits,

and disconnect a client. Observe attempts, in-flight work, cleanup and terminal results. Test cancellation effects rather than inferring them from a cancelled future.

• Operations: observe latency/error/completeness by route and client contract with

bounded labels; separate dependency time, pool wait, edge work and response size. Keep credentials and personal payloads out of logs. A rise in partial responses can hide behind healthy HTTP success metrics. Compare representative client journeys before claiming an improvement; fewer client round trips alone is not a performance result.

Scale the output to the task. End with implemented or proposed changes, checks actually run, failures and remaining evidence. Configuration inspection, a written scenario and a deployed failure drill establish different things. Never report one as proof of another.