Learn how to use Target Servers in Apigee to decouple API proxies from backend URLs, enable load balancing and failover, and manage backend connectivity from a single place — with step-by-step examples.
How to Use Target Servers in Apigee: A Complete Guide for API Teams
If you've ever hard-coded a backend URL inside an Apigee API proxy, you already know the pain: an environment change, a DNS update, or a failover requirement means editing, redeploying, and re-testing every proxy that touches that backend. Target Servers exist to eliminate exactly that problem.
In this guide, you'll learn what Apigee Target Servers are, why they matter, and how to configure, load-balance, and troubleshoot them — using both the Apigee UI and the Management API.
Table of Contents
- What Are Target Servers in Apigee?
- Why Use Target Servers? (5 Real Benefits)
- How Target Servers Work Under the Hood
- How to Create a Target Server (Apigee UI)
- How to Create a Target Server (Management API)
- Using Target Servers in an API Proxy (XML Example)
- Load Balancing and Failover Across Target Servers
- Health Monitoring for Target Servers
- TLS and SSL Configuration
- Environment-Specific Target Servers and Promotion
- Common Mistakes to Avoid
- Troubleshooting Target Server Issues
- Frequently Asked Questions
What Are Target Servers in Apigee?
A Target Server in Apigee is a named, environment-scoped resource that represents the backend host (and optionally port and TLS settings) your API proxies call at runtime. Instead of embedding a literal URL such as https://api-backend.internal.example.com:8443 inside a proxy's TargetEndpoint, you reference a logical name — for example, orders-backend.
At runtime, Apigee resolves that name against the Target Servers defined in the deployed environment and routes the request accordingly.
Key characteristics:
- Environment-scoped — a Target Server is defined per environment (dev, test, prod), so the same proxy can point to different physical backends per environment without code changes.
- Zero-touch backend changes — updating a Target Server's host or port takes effect immediately for all proxies referencing it; no redeployment required.
- Load balancing built in — attach multiple Target Servers to one load balancer for round-robin routing and automatic failover.
- Centralized TLS management — SSL/TLS settings (truststores, client authentication) are stored with the Target Server, not scattered across proxies.
Why Use Target Servers? (5 Real Benefits)
1. Decouple proxies from backend infrastructure
Proxies reference a logical name, not a physical URL. When your backend moves, only the Target Server definition changes — every proxy using it picks up the change instantly.
2. Safer environment promotion
The same proxy bundle moves from dev → test → prod untouched, because the environment provides its own Target Server values. This removes the classic "it worked in staging because the URL was still pointing to dev" bug class.
3. Load balancing and failover out of the box
Apigee's LoadBalancer in the HTTPTargetConnection distributes traffic across multiple Target Servers and can route around failed backends using failure thresholds.
4. Centralized TLS policy
Store certificate verification and client-auth settings once, on the Target Server, instead of duplicating SSLInfo blocks across dozens of proxy endpoints.
5. Governance and visibility
Because Target Servers are managed resources (with their own roles/permissions), platform teams can own backend connectivity while product teams own proxy logic — a clean separation of concerns.
How Target Servers Work Under the Hood
When a request reaches a TargetEndpoint configured with <Server name="..."/>, the flow is:
- Apigee looks up the named Target Server in the environment where the proxy is deployed.
- It resolves the host and port (default 443 for HTTPS, 80 for HTTP).
- It applies any TLS settings attached to the Target Server.
- The load balancer (if configured) picks among available Target Servers and tracks failures for failover.
If the name doesn't exist in the environment, you'll get a deployment-time or runtime error — which is why consistent naming across environments is a best practice.
How to Create a Target Server (Apigee UI)
- Sign in to the Apigee UI.
- Navigate to Admin → Environments → Target Servers (in some versions: API Proxies → select environment → Target Servers).
- Select the environment (e.g.,
prod) from the environment dropdown. - Click + Target Server (or Create).
- Fill in:
- Name — the logical name proxies will reference, e.g.
orders-backend - Host — the backend hostname or IP, e.g.
10.20.30.40orapi-backend.internal.example.com - Port — e.g.
443 - Enable TLS — toggle if the backend uses HTTPS; configure truststore/keystore if needed
- Name — the logical name proxies will reference, e.g.
- Click Save (or Create).
Repeat per environment with environment-appropriate host values, keeping the same Name for easy promotion.
How to Create a Target Server (Management API)
Everything in the UI can be automated with the Apigee Management API — the right approach for infrastructure-as-code.
Create a Target Server
curl -X POST "https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/targetservers" \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -d '{ "name": "orders-backend", "host": "10.20.30.40", "port": 443, "protocol": "HTTPS", "isEnabled": true }' Update (or create) with PUT
curl -X PUT "https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/targetservers/orders-backend" \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -d '{ "name": "orders-backend", "host": "10.20.30.41", "port": 443, "protocol": "HTTPS", "isEnabled": true }' List Target Servers in an environment
curl "https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/targetservers" \ -H "Authorization: Bearer $(gcloud auth print-access-token)" Tip: Keep these calls in your CI/CD pipeline alongside proxy deployments so backend connectivity is versioned and auditable like any other infrastructure.
Using Target Servers in an API Proxy (XML Example)
Create a TargetEndpoint that references your Target Server by name:
<TargetEndpoint name="orders-backend"> <HTTPTargetConnection> <LoadBalancer> <Server name="orders-backend"/> </LoadBalancer> <Path>/v1/orders</Path> </HTTPTargetConnection> </TargetEndpoint> A few things to note:
-
<Server name="..."/>matches the Name of the Target Server — not the host. -
<Path>is optional and appends a base path to every request. - If you only have one backend, you can reference a single Target Server inside the load balancer — it's still the recommended pattern over hard-coded URLs.
Load Balancing and Failover Across Target Servers
Attach multiple Target Servers and Apigee load-balances between them:
<TargetEndpoint name="orders-cluster"> <HTTPTargetConnection> <LoadBalancer> <Server name="orders-backend-1"/> <Server name="orders-backend-2"/> <MaxFailures>5</MaxFailures> <RetryEnabled>true</RetryEnabled> </LoadBalancer> <Path>/v1</Path> </HTTPTargetConnection> </TargetEndpoint> How it behaves:
- Round-robin distribution across all listed Target Servers.
-
<MaxFailures>— after this many consecutive failed requests, the Target Server is removed from rotation. -
<RetryEnabled>— failed requests may be retried against another Target Server, subject to idempotency considerations.
Design note: Apigee's target load balancing is simple round-robin with failure-based removal — not weighted or latency-aware routing. For advanced routing (canary, geo-based), combine Target Servers with conditional RouteRule logic or an external load balancer in front of your backends.
Health Monitoring for Target Servers
Beyond failure counting, you can configure active health checks in the TargetEndpoint so Apigee proactively detects unhealthy backends:
<TargetEndpoint name="orders-cluster"> <HTTPTargetConnection> <LoadBalancer> <Server name="orders-backend-1"/> <Server name="orders-backend-2"/> </LoadBalancer> <HealthMonitor> <IsEnabled>true</IsEnabled> <IntervalInSec>30</IntervalInSec> <HTTPMonitor> <Request> <Verb>GET</Verb> <Path>/health</Path> </Request> <Response> <UseResponseCode>true</UseResponseCode> </Response> </HTTPMonitor> </HealthMonitor> </HTTPTargetConnection> </TargetEndpoint> With this in place, backends failing the /health check are taken out of rotation before they burn through real user requests.
TLS and SSL Configuration
When your backend requires HTTPS (or mutual TLS), configure TLS on the Target Server itself — either in the UI or via the API:
{ "name": "orders-backend", "host": "api-backend.internal.example.com", "port": 443, "protocol": "HTTPS", "isEnabled": true, "sSLInfo": { "enabled": true, "trustStore": "ref://my-truststore-ref", "keyStore": "ref://my-keystore-ref", "keyAlias": "backend-client-cert", "clientAuthEnabled": true } } Benefits of TLS-on-Target-Server:
- Update certificates once, even when dozens of proxies use the backend.
- Enable mutual TLS centrally without touching proxy code.
- Rotate truststores/keystores independently of proxy deployments.
Environment-Specific Target Servers and Promotion
The canonical promotion pattern looks like this:
| Environment | Target Server Name | Host |
|---|---|---|
| dev | orders-backend | 10.0.1.10 |
| test | orders-backend | 10.1.1.10 |
| prod | orders-backend | prod-lb.example.com |
Rules of thumb:
- Keep the name identical across environments — only host/port/TLS differ.
- Provision Target Servers via the Management API in your environment bootstrap pipeline.
- Treat Target Server changes as infrastructure changes: review, version, and audit them.
- For genuinely dynamic routing (per-tenant backends, feature-flagged endpoints), combine Target Servers with runtime flow variables and set
target.urlin an AssignMessage policy instead.
Common Mistakes to Avoid
- Hard-coding URLs in
TargetEndpointwhen a Target Server exists — you lose failover, centralized TLS, and zero-downtime backend changes. - Inconsistent naming across environments —
orders-backendin dev andorders-backend-prodin prod breaks promotion; use identical names. - Forgetting to create the Target Server in a new environment — deployment succeeds, but runtime calls fail with target resolution errors.
- Assuming weighted or latency-based balancing — Apigee's balancer is round-robin with failure removal only.
- Enabling retries blindly — retrying non-idempotent POSTs can duplicate operations; pair
RetryEnabledwith idempotency keys or restrict retries to safe methods. - No health checks on critical backends — rely on failure counts alone and users absorb the first N failures.
Troubleshooting Target Server Issues
| Symptom | Likely Cause | Fix |
|---|---|---|
| Target resolution error | Target Server missing in deployed environment | Create it with the exact referenced name |
| TLS handshake failures | Wrong/missing truststore or keystore reference | Verify sSLInfo and referenced keystore resources exist in the environment |
| All traffic pinned to one backend | Other Target Servers failing health/failure threshold | Check backend logs; verify MaxFailures isn't tripped |
| Intermittent 503s under load | Backends saturated or health check interval too aggressive | Tune IntervalInSec, scale backends, check Apigee trace sessions |
| Changes not taking effect | Updated wrong environment or stale proxy bundle | Verify with a Trace session; confirm you edited the correct environment |
Trace is your best friend: run a Trace session in the Apigee UI, watch which Target Server is selected, and inspect the full request/response to the backend.
Frequently Asked Questions
What is a Target Server in Apigee?
A named, environment-scoped resource representing a backend host (plus port and TLS settings) that API proxies reference instead of hard-coded URLs, enabling centralized management, load balancing, and failover.
Can a Target Server point to a load balancer?
Yes — the host can be any hostname or IP that Apigee can resolve and reach, including an external load balancer's address. Both patterns are common.
Do Target Server changes require proxy redeployment?
No. Updating a Target Server (host, port, TLS) takes effect immediately for all proxies referencing it in that environment.
How many Target Servers can be attached to one load balancer?
There's no practical small limit; teams commonly attach 2–10. Remember balancing is round-robin, so extremely large pools rarely add value over a pool fronted by a dedicated load balancer.
Can I change the target dynamically at runtime?
For per-request routing logic, use an AssignMessage policy to set the target.url flow variable — or use multiple RouteRules — alongside static Target Servers for the well-known backends.
The Bottom Line
Apigee Target Servers turn backend connectivity from scattered hard-coded URLs into a managed, environment-aware resource. Adopt three habits and you'll avoid most integration pain:
- Never hard-code backend URLs in proxy endpoints — always reference Target Servers.
- Keep names identical across environments so promotion is a pure configuration concern.
- Provision via the Management API so backend connectivity is versioned, reviewable, and automated.
Your proxies become simpler, your environments become consistent, and your on-call pages get quieter.


