Server URL templating

Server URL templating lets you define base URLs with variable placeholders (e.g., {region}, {environment}) that SDK users can customize at runtime. This is useful for APIs deployed across multiple regions, environments, or custom domains.

Generated SDK behavior

Fern generates an environments module that exposes the default URLs for each named server. SDK users can select a pre-defined environment or pass custom URL strings.

1
class MyApiEnvironment:
2
    REGIONAL_API_SERVER = {
3
        "base": "https://api.example.com/v1",
4
        "auth": "https://auth.example.com",
5
    }

1
from my_api import MyApiClient
2
3
# Use the default environment
4
# → https://api.example.com/v1
5
client = MyApiClient()
6
7
# Target a specific region and environment via URL variables
8
# → https://api.eu-west-1.staging.example.com/v1
9
client = MyApiClient(
10
    region="eu-west-1",
11
    environment="staging",
12
)
13
14
# Or provide a custom base URL
15
# → https://api.us-west-2.staging.example.com/v1
16
client = MyApiClient(
17
    base_url="https://api.us-west-2.staging.example.com/v1",
18
)

Setting up server URL templating

Define URL template variables in your API definition and provide a static fallback URL for SDK users who don’t customize variables:

1
servers:
2
  - url: https://api.{region}.{environment}.example.com/v1
3
    x-fern-server-name: Default
4
    x-fern-default-url: https://api.example.com/v1
5
    variables:
6
      region:
7
        default: us-east-1
8
        enum: [us-east-1, us-west-2, eu-west-1]
9
      environment:
10
        default: prod
11
        enum: [prod, staging, dev]

For full configuration details, see Server names and URL templating in OpenAPI.