Migrating to Proxy Hopper

Migration approach

Proxy Hopper requires a single code change: instead of calling the third-party API directly, point your HTTP client at Proxy Hopper and add the X-Proxy-Hopper-Target header. The migration is typically done per-client or per-service and can be rolled out incrementally.

Migrating from direct API calls

Before:

import requests

resp = requests.get(
    "https://api.example.com/v1/search",
    params={"q": "test"},
    headers={"Authorization": "Bearer api_key"},
)

After:

import requests

session = requests.Session()
session.headers["X-Proxy-Hopper-Target"] = "https://api.example.com"

resp = session.get(
    "http://proxy-hopper:8080/v1/search",
    params={"q": "test"},
    headers={"Authorization": "Bearer api_key"},   # your upstream API key — kept as-is
)

Your upstream API credentials (Authorization, X-API-Key, etc.) are passed through to the destination unchanged. Only X-Proxy-Hopper-* headers are consumed and stripped by Proxy Hopper.

Migrating from a standard HTTP proxy

If your application was previously using an HTTP proxy via environment variables or proxy settings, the migration is straightforward. Before (proxy via requests proxy settings):

proxies = {"https": "http://old-proxy:8080"}
resp = requests.get("https://api.example.com/v1/data", proxies=proxies)

After (Proxy Hopper via header):

session = requests.Session()
session.headers["X-Proxy-Hopper-Target"] = "https://api.example.com"
resp = session.get("http://proxy-hopper:8080/v1/data")

The key differences:

Remove proxy settings from your client configuration
Set X-Proxy-Hopper-Target on the session
Change the base URL to point at Proxy Hopper

Migrating multiple API integrations

For applications that call several different APIs, use one session per API:

maps_session = requests.Session()
maps_session.headers["X-Proxy-Hopper-Target"] = "https://maps.googleapis.com"

analytics_session = requests.Session()
analytics_session.headers["X-Proxy-Hopper-Target"] = "https://analytics-api.example.com"

Or use a helper to create sessions:

PROXY_HOPPER = "http://proxy-hopper:8080"

def proxy_session(target: str, api_key: str | None = None) -> requests.Session:
    session = requests.Session()
    session.headers["X-Proxy-Hopper-Target"] = target
    if api_key:
        session.headers["X-Proxy-Hopper-Auth"] = f"Bearer {api_key}"
    return session

maps = proxy_session("https://maps.googleapis.com")
analytics = proxy_session("https://analytics-api.example.com", api_key="ph_mykey")

httpx migration

# Before
import httpx
client = httpx.Client()
resp = client.get("https://api.example.com/v1/data")

# After
client = httpx.Client(
    base_url="http://proxy-hopper:8080",
    headers={"X-Proxy-Hopper-Target": "https://api.example.com"},
)
resp = client.get("/v1/data")

aiohttp migration

# Before
async with aiohttp.ClientSession() as session:
    async with session.get("https://api.example.com/v1/data") as resp:
        data = await resp.json()

# After
async with aiohttp.ClientSession(
    headers={"X-Proxy-Hopper-Target": "https://api.example.com"}
) as session:
    async with session.get("http://proxy-hopper:8080/v1/data") as resp:
        data = await resp.json()

Verifying the migration

Check the Proxy Hopper logs — you should see requests being dispatched for your target
Verify responses are as expected
Check Prometheus metrics (if enabled) — proxy_hopper_requests_total should show new requests

# Quick check — confirm requests are going through Proxy Hopper
curl -H "X-Proxy-Hopper-Target: https://httpbin.org" http://proxy-hopper:8080/get

Non-idempotent requests

If you have POST, PUT, PATCH, or DELETE calls, set retries to 0 to avoid duplicate actions on failure:

resp = session.post(
    "http://proxy-hopper:8080/v1/orders",
    json=payload,
    headers={"X-Proxy-Hopper-Retries": "0"},
)

Getting Started

Concepts

For Administrators

For Developers

For Contributors

Migrating to Proxy Hopper

Migration approach

Migrating from direct API calls

Migrating from a standard HTTP proxy

Migrating multiple API integrations

httpx migration

aiohttp migration

Verifying the migration

Non-idempotent requests

​Migration approach

​Migrating from direct API calls

​Migrating from a standard HTTP proxy

​Migrating multiple API integrations

​httpx migration

​aiohttp migration

​Verifying the migration

​Non-idempotent requests

Migration approach

Migrating from direct API calls

Migrating from a standard HTTP proxy

Migrating multiple API integrations

httpx migration

aiohttp migration

Verifying the migration

Non-idempotent requests