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.

Server URL templating is supported for TypeScript, Python, Java, Go, C#, PHP, and Ruby SDK generation.

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, set URL variables through client options, or pass custom URL strings. Variable names that conflict with existing client options use a serverUrl prefix in the language’s casing convention, such as serverUrlEnvironment.

1
export const MyApiEnvironment = {
2
    RegionalApiServer: {
3
        base: "https://api.example.com/v1",
4
        auth: "https://auth.example.com",
5
    },
6
} as const;

1
import { MyApiClient } from "my-api";
2
3
// Use the default environment
4
// → https://api.example.com/v1
5
const client = new MyApiClient();
6
7
// Target a specific region and environment via URL variables
8
// → https://api.eu-west-1.staging.example.com/v1
9
const client = new MyApiClient({
10
  region: "eu-west-1",
11
  serverUrlEnvironment: "staging",
12
});
13
14
// Or route all requests to a custom base URL
15
// → https://api.us-west-2.staging.example.com/v1
16
const client = new MyApiClient({
17
  baseUrl: "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 when SDK users 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.