Engineering note

A proxy route is an application boundary

Routing, authentication and response contracts at the proxy boundary.

APIs / Integration architecture

Passthrough and application behaviour

I used YARP for operations that could retain their upstream contract. Catch-all routes avoided duplicating controllers and models for vendor filters, response fields and pagination cursors.

Specific controller routes implemented application validation and orchestration while preserving passthrough handling for adjacent operations.

API request paths

Caller request endpoint routing the selected handling path

YARP passthroughResolve the external API, remove client-supplied managed credentials, attach server-managed credentials and stream to the upstream.
Controller overrideRun application-owned validation or orchestration, acquire the required credentials and dispatch the operation.
GraphQL gatewayUse the composed schema to plan queries across the participating service subgraphs.

These are alternative request paths. A request does not pass through all three. The diagram shows responsibilities rather than every middleware component or deployment boundary.

Operation selection

A catalogue lookup can preserve upstream query parameters, cursors and response bodies. Additional filters can pass through without corresponding controller or model changes. Route configuration, credential replacement and boundary response handling remain application responsibilities.

A geographic search requires application checks on the requested area and time window before dispatch. A controller implements these rules and their error responses. Changes to that contract can require application code and test updates.

These generalised examples reflect the documented integrations. Literal controller routes take precedence over the surrounding catch-all, so integration tests must verify route selection as well as operation behaviour.

Credential handling

Proxy middleware resolves the external API from matched route metadata, removes client-supplied managed headers and attaches server-managed credentials.

Token strategies implement vendor-specific authentication. The shared token service handles caching and coordinated renewal to prevent duplicate token requests on concurrent cache misses. Controller overrides use their own validation and dispatch paths.

The credential-renewal note examines cache misses, per-upstream coordination and acquisition failures.

Failure response contracts

Response ownership at the API boundary
Failure source	Response policy	Useful check
Local validation or token acquisition	Generate the application's Problem Details response, with a trace identifier and safe public detail.	Confirm the response contract and whether dispatch was prevented.
Upstream returns an error	On a transparent passthrough, preserve the upstream status, body and relevant headers.	Simulate 400, 429 with Retry-After, and 503; inspect what the caller receives.
Forwarding fails before an upstream response	Handle the transport failure explicitly; do not describe it as a vendor response.	Cancel or interrupt the request and check the API's observable behaviour.

Upstream error bodies require an explicit disclosure policy. Preservation of the vendor contract and sanitisation of application-generated diagnostics are separate response responsibilities.

Streaming and retry constraints

Streaming avoids whole-payload buffering during forwarding. Replaying a consumed request body requires a replayable source or buffering, and automatic retries must account for the operation's semantics.

A 429 response may indicate temporary rate limiting or exhausted quota. Retry decisions depend on the upstream contract and available response information.

Telemetry exposure

Sensitive selectors embedded in URL paths can appear in request logs and locally generated error responses even when forwarding is correct.

This exposure is recorded in the adaptor documentation. A proposed mitigation is to log route templates or approved metadata instead of sensitive paths. Sanitisation must apply at the logging middleware; a later controller action cannot change an earlier log record.

Examples are generalised or synthetic and omit operational details and identifying information.

← All engineering notes