Upstreams and routes
Weik.io 2026.2Write where an API sends its calls in YARP's configuration, and give the gateway a credential and connection settings for the upstream. Video
Watch: Publish an API and call it, 3:55
The video publishes an API in front of an integration and deploys it to production. Then it calls the API with curl.
This part of the video couldn't be loaded.
On this page
An API version of type: proxy says where the gateway sends each call, in its routes and clusters blocks. These blocks are the configuration of YARP, the .NET reverse proxy that runs inside the gateway, so you write them as YARP’s documentation describes. Any setting YARP accepts there works on the gateway.
Routes and clusters#
apiVersion: weik.io/v1
kind: api-version
metadata: { name: v1, project: finance, api: invoices }
spec:
type: proxy
routes: # YARP RouteConfig
- RouteId: pending
Match: { Path: "/{**rest}" }
ClusterId: erp
clusters: # YARP ClusterConfig
- ClusterId: erp
LoadBalancingPolicy: RoundRobin
Destinations:
erp: { Address: "{{erp-url}}/api/invoices" }A route matches the part of the path after the API’s prefix and version, so with the prefix /invoices a call to https://api.example.com/invoices/v1/pending matches /{**rest} with rest as pending. A cluster lists the destinations a route sends to. With several destinations, the cluster balances the calls between them.
The destination’s address is a placeholder, so devtest and production send the calls to their own systems.
An integration’s HTTP route is an upstream like any other. Write its address in the cluster, such as http://integrations:8080 for an integration on the same host.
A credential for the upstream#
When the upstream needs a credential, set it in the version’s authentication block. The gateway adds it to the calls it forwards.
| Type | What the gateway does |
|---|---|
header |
Adds the headers you set, such as an API key the upstream expects |
basic |
Builds the Basic authorization header from a username and a password |
oidc |
Gets an OAuth client-credentials token from the token endpoint and sends it |
spec:
authentication:
type: oidc
parameters:
tokenEndpoint: "https://erp.example.com/token"
clientId: weikio
clientSecret: "{{erp-client-secret}}" # a project secret
scope: invoices.readThe secret stays a placeholder in the version, so each environment uses its own secret.
The gateway removes the key or token that admitted the caller before it forwards the call.
Connection settings#
The connection block sets the parts of the connection to the upstream that YARP’s configuration has no setting for:
spec:
connection:
automaticDecompression: gzip
connectTimeout: 30s| Setting | What it does |
|---|---|
allowAutoRedirect |
Follows the upstream’s redirects |
automaticDecompression |
Decompresses gzip responses |
useCookies |
Keeps the upstream’s cookies |
useProxy |
Sends the calls through the host’s proxy |
connectTimeout |
Sets how long a connection may take, 15 seconds when it’s not set |
clientCertificate |
Presents a client certificate from a secret on each TLS connection to the upstream and its token endpoint |
Store the client certificate as a secret with --as-file, either as a PEM file with the certificate chain and its key or as a PKCS#12 file. For an encrypted key, set clientCertificatePassword.
Weik.io raises a problem 30 days before the client certificate expires. A deploy with an expired certificate fails.
Where an API may send#
The gateway’s --upstream-networks limits where the APIs it serves may send calls. A platform administrator sets it on gateways that face the internet.
Retries#
YARP doesn’t retry a call, because it streams the request body and can’t send it twice. To retry calls to an upstream, put an integration in front of it.