Skip to content
Weik.ioDocs
2026.2
Try Weik.io

Upstreams and routes

Weik.io 2026.2

Write 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.

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#

finance/apis/invoices.yaml
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.read

The 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.

Sign in to the live demo

Sign in with the shared viewer account. It can open every screen of the example projects but can't change anything.

E-mail
viewer@demo.weik.io
Password
try-weikio-live-demo
Open the live demo