Server URL templating | Fern Documentation

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.

TypeScript

Python

Java

Go

C#

PHP

Ruby

The generated SDK exposes an Environment object:

environments.ts

export const MyApiEnvironment = {
    RegionalApiServer: {
        base: "https://api.example.com/v1",
        auth: "https://auth.example.com",
    },
} as const;

SDK users can select an environment, set URL variables, or pass a custom base URL when constructing the client:

import { MyApiClient } from "my-api";
// Use the default environment
// → https://api.example.com/v1
const client = new MyApiClient();
// Target a specific region and environment via URL variables
// → https://api.eu-west-1.staging.example.com/v1
const client = new MyApiClient({
  region: "eu-west-1",
  serverUrlEnvironment: "staging",
});
// Or route all requests to a custom base URL
// → https://api.us-west-2.staging.example.com/v1
const client = new MyApiClient({
  baseUrl: "https://api.us-west-2.staging.example.com/v1",
});

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:

openapi.yml

servers:
  - url: https://api.{region}.{environment}.example.com/v1
    x-fern-server-name: Default
    x-fern-default-url: https://api.example.com/v1
    variables:
      region:
        default: us-east-1
        enum: [us-east-1, us-west-2, eu-west-1]
      environment:
        default: prod
        enum: [prod, staging, dev]

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