Apigee Target Servers VS. Target Endpoints

Let's break down the difference between Target Servers and Target Endpoints, complete with examples.

The Core Difference: Abstraction vs. Implementation

Think of it this way:

• Target Server: A named, reusable configuration object that defines where your backend service is (host, port, TLS settings). It's about the destination.
• Target Endpoint: An XML configuration block inside your API Proxy that defines how to call the backend. It's about the operation (the request/response). It often uses a Target Server to know where to send the request.

You can achieve the same result without Target Servers by defining the backend URL directly in the Target Endpoint. Target Servers add a layer of abstraction that provides significant benefits.

---

Target Endpoint (The "How")

A Target Endpoint is a fundamental building block of an Apigee API proxy. It's defined in an XML file (e.g., default.xml) within the proxy bundle and represents the outbound connection to your backend service.

Key Characteristics:

• Proxy-Specific: Defined within a single API proxy.
• Defines the HTTP Interaction: It contains the configuration for the actual request and response flow to the backend, including:
  • Pre-processing logic (with <PreFlow>)
  • Post-processing logic (with <PostFlow>)
  • Fault rules for backend errors
  • The crucial <HTTPTargetConnection> element which points to the actual backend.

Example 1: Target Endpoint WITHOUT a Target Server (Direct URL)

This is often called a "pass-through" or directly configured target.

<!-- File: /targets/default.xml -->
<TargetEndpoint name="default">
  <PreFlow name="PreFlow">
    <!-- You can add policies here, like adding an API key to the backend request -->
  </PreFlow>
  <HttpTargetConnection>
    <!-- The backend URL is hardcoded right here -->
    <URL>https://api.my-internal-service.com/v1/orders</URL>
  </HttpTargetConnection>
  <PostFlow name="PostFlow">
    <!-- You can add policies here to process the backend response -->
  </PostFlow>
</TargetEndpoint>

Example 2: Target Endpoint WITH a Target Server (Using Abstraction)

This endpoint doesn't know the exact URL; it knows the name of a Target Server.

<!-- File: /targets/default.xml -->
<TargetEndpoint name="default">
  <PreFlow name="PreFlow"/>
  <HttpTargetConnection>
    <!-- It references a Target Server by name -->
    <!-- The environment (e.g., 'test', 'prod') is determined at runtime -->
    <LoadBalancer>
      <Server name="target-server-orders"/>
    </LoadBalancer>
    <!-- You can still add a path to the base URL defined in the Target Server -->
    <Path>/v1/orders</Path>
  </HttpTargetConnection>
  <PostFlow name="PostFlow"/>
</TargetEndpoint>

---

Target Server (The "Where")

A Target Server is an environment-specific entity that you create and manage outside of any individual API proxy. It's a reusable definition of a backend host.

Key Characteristics:

• Environment-Specific & Reusable: Created once in an environment (e.g., test, prod) and can be used by many different API proxies.
• Defines Connection Details: It holds the low-level network information:
  • Host: The backend server's hostname or IP.
  • Port: The port number (e.g., 443 for HTTPS, 80 for HTTP).
  • SSLInfo: Configuration for TLS/SSL (e.g., whether to ignore validation errors for self-signed certs in dev).
• Enables Load Balancing: You can define multiple Target Servers with the same name to form a load balancing group.

How to Create a Target Server:
You create it via the Apigee UI (Admin -> Environments -> Target Servers) or the Management API.

Example: Creating a Target Server for Dev

• Name: target-server-orders
• Host: orders-service.dev.mycompany.net
• Port: 443
• SSL Info: Enabled (This is the default)

Example: Creating a Target Server for Prod (with Load Balancing)

You would create two or more Target Servers with the exact same name but different hosts.

• Server 1:
  • Name: target-server-orders-prod-lb
  • Host: orders-service-prod-1.mycompany.com
  • Port: 443
• Server 2:
  • Name: target-server-orders-prod-lb <!-- Same name! -->
  • Host: orders-service-prod-2.mycompany.com
  • Port: 443

Apigee will automatically load balance requests between these two hosts.

---

Side-by-Side Comparison

Feature	Target Endpoint	Target Server
Scope	API Proxy (defined inside a proxy)	Environment (defined outside proxies, reusable)
Purpose	Define the how (request/response flow, policies).	Define the where (host, port, TLS settings).
Configuration	XML file in the proxy bundle.	Admin UI or Management API.
Content	PreFlow, PostFlow, Fault Rules, <HTTPTargetConnection>.	Host, Port, SSL Info.
Load Balancing	Configures the strategy (e.g., round-robin) in the XML.	Provides the members (the actual servers) of the pool.
Example Use	Adding headers, transforming the request, handling errors.	Staging vs. Production backend URLs.

When to Use Which?

• Use a Target Endpoint (with a direct URL) when:

  • You are prototyping quickly.
  • The backend URL is simple and unlikely to change.
  • The proxy is tightly coupled to a single, specific backend.

• Use a Target Endpoint WITH a Target Server when:

  • Different Backends for Different Environments: You have a different backend URL for your test, stage, and prod environments. This is the most common and recommended reason.
  • Reusability: The same backend host is used by multiple API proxies (e.g., a shared authentication service).
  • Load Balancing: You need to distribute traffic across multiple instances of your backend.
  • Operational Decoupling: You want to change the backend host/port (e.g., during a migration) without redeploying any API proxies. You just update the Target Server configuration.

Summary

The Target Endpoint is the "what to do" when calling the backend. The Target Server is the "where to do it." By using them together, you create a clean separation of concerns, making your API proxies more portable, reusable, and easier to manage across different environments.