Skip to content

Upstream

Overview

Upstream is a reusable library of backend targets (primary and optional backup endpoints) bound to a gateway environment and an API type. During API onboarding, select an Upstream under Configure Upstream Servers.

With this feature, you can:

  • Create upstream targets with primary and backup URLs and ports.
  • Bind each upstream to a gateway environment and an API Type (REST or SOAP).
  • Enable TLS and attach an optional client certificate from Shared Resources.
  • Set connect and read timeouts and optional retry-on-5xx behavior.
  • Edit or delete upstreams from a single list.

Path: API Manager → Gateway Control → Upstream

Note

GraphQL, gRPC, and Async API (Websocket) are in beta and will be GA soon.

Why This Matters

  • Reusable backend targets shared across APIs of the same type.
  • TLS, timeouts, and failover endpoints live with the upstream rather than on the onboarding form.
  • Create gateway Environments before you create upstreams.
  • Do not use this page to change domains or dataplanes — that belongs in Environments.

Prerequisites

Required Access and Permissions

  • API Manager access.
  • Permission to manage Gateway Control features.

System / Technical Requirements

  • Valid organization context in the API Manager.
  • At least one gateway environment.
  • Optional: shared SSL certificates in Shared Resources if you enable TLS with a client certificate.

Upstream List

Search: Matches upstream name only.

API Types filter: All API Types, plus the API types available for your organization (for example REST, SOAP).

Click Create Upstream target to open create mode.

Column Description
Upstream Name Display name of the target
Environment Linked gateway environment
API Type REST or SOAP
Status Active or Inactive
Created Date When the upstream was created
Edit Opens Upstream / Edit Upstream target
Delete Opens Delete Upstream target

There is no View column on the list.

Status values

Status Meaning
Active Upstream target is available for use
Inactive Upstream target is deactivated

Step-by-Step Implementation

Creating an Upstream

Step 1: Navigate to Upstream

  • From the left navigation panel, open Gateway Control → Upstream.

Step 2: Open Create

  • Click Create Upstream target to open Upstream / Create Upstream target.

Step 3: Enter Basic Information

  1. Enter Upstream name (letters, numbers, and hyphens only).
  2. Select Environment.
  3. Select API Type (REST or SOAP).

Endpoint, TLS, timeout, and retry fields stay disabled until the required basic fields are complete.

Step 4: Configure End points

  1. Enter Primary URL and Port.
  2. Optionally enter Backup URL and its Port.

Use http:// or https:// for REST and SOAP.

Step 5: Configure TLS, Timeouts, and Retry

  1. Optionally enable TLS Enabled and select Client Certificate (optional) from Shared Resources.
  2. Enter Connect Timeout and Read Timeout (seconds).
  3. Optionally enable Retry on 5xx and set Retry Count.

Step 6: Save

  • Click Create.

Success

The upstream appears in the list and becomes available in My APIs → Configure Upstream Servers for APIs of the same API Type.

Editing or Deleting an Upstream

Edit

  1. From the Upstream list, click Edit.
  2. Update allowed fields. Environment and API Type are locked on edit.
  3. Click Update.

If you change fields other than the name, Update Upstream target confirms:

This upstream is already deployed and used in existing release snapshots/environments. Any changes will be synced immediately to the default environment. To apply them to other environments, create a new release snapshot and deploy it.

Rename

If you change the upstream name, Update Upstream target confirms:

You are changing the upstream name, which is used in existing release snapshots. Saving this change will invalidate those snapshots, and they can no longer be deployed. To apply the change to other environments, create a new release snapshot and deploy it. Do you want to continue?

  • Choose Yes to rename, or No to cancel.
  • After renaming, create a new release snapshot and deploy it to apply the change to other environments.

Delete

  1. From the Upstream list, click Delete.
  2. Confirm in Delete Upstream target.

Best Practices

Practice Reason
Create environments before upstreams Each upstream requires an environment
Match API Type to the APIs that will use the upstream Onboarding lists upstreams filtered by API type
Prefer name changes carefully Renaming can invalidate existing release snapshots
Create a new snapshot after upstream changes for non-default environments Default environment syncs immediately; others need snapshot + deploy

Troubleshooting

Issue Possible Cause Resolution
No environments in the selector No gateway environments Create one in Environments
Invalid Upstream name Unsupported characters Use letters, numbers, and hyphens only
Invalid URL Wrong scheme for API type Use http:// or https:// for REST and SOAP
Port validation error Port outside 1–65535 Enter a valid port
Later form sections disabled Basic Information incomplete Complete Upstream, Environment, and API Type
No certificates listed No shared SSL resources Create certificates in Shared Resources
Onboarding shows no upstreams No upstream for that API type Create an upstream with the matching API Type (No upstream created for this API type)
Update blocked with no changes Form matches saved values Change at least one field before Update
No Upstream targets match your filters Search or API Types filter is too narrow Clear search or set API Types to All API Types

Frequently Asked Questions

How do I attach a backend to an API?

Create an Upstream on this page with the same API Type as the API, then open Configure Upstream Servers during onboarding or on the API Details page (Manage APIs → My APIs), select the Upstream, and select Update.

Where do I configure TLS for the backend?

On the Upstream form under TLS / Security. Optionally attach a Client Certificate from Shared Resources.

Do upstream edits apply to every environment immediately?

Changes sync immediately to the default environment. For other environments, create a new release snapshot and deploy it from Deployment Environment.

Tip

Create Environments first, create upstreams here, then onboard from My APIs using the guide for your API type, or select them on API Details.