***

title: Server URL templating
description: >-
Configure server URL templating in Fern SDKs to support dynamic base URLs with
variables like region and environment.
--------------------------------------

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.

<Note>
  URL templating is currently supported for Python and Java SDK generation only.
</Note>

## 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.

<Tabs>
  <Tab title="Python">
    The generated SDK exposes an `Environment` class:

    ```python title="environment.py"
    class MyApiEnvironment:
        REGIONAL_API_SERVER = {
            "base": "https://api.example.com/v1",
            "auth": "https://auth.example.com",
        }
    ```

    SDK users can override the base URL when constructing the client:

    ```python
    from my_api import MyApiClient

    # Use the default environment
    # → https://api.example.com/v1
    client = MyApiClient()

    # Target a specific region and environment via URL variables
    # → https://api.eu-west-1.staging.example.com/v1
    client = MyApiClient(
        region="eu-west-1",
        environment="staging",
    )

    # Or provide a custom base URL
    # → https://api.us-west-2.staging.example.com/v1
    client = MyApiClient(
        base_url="https://api.us-west-2.staging.example.com/v1",
    )
    ```
  </Tab>

  <Tab title="Java">
    The generated SDK exposes an `Environment` class:

    ```java title="Environment.java"
    public final class Environment {
        public static final Environment REGIONAL_API_SERVER =
            new Environment(
                "https://api.example.com/v1",
                "https://auth.example.com"
            );
        public static Builder custom() { return new Builder(); }
    }
    ```

    The generated SDK exposes an environment enum and a builder method:

    ```java
    import com.example.api.MyApiClient;

    // Use the default environment
    // → https://api.example.com/v1
    MyApiClient client = MyApiClient.builder().build();

    // Target a specific region and environment via URL variables
    // → https://api.eu-west-1.staging.example.com/v1
    MyApiClient client = MyApiClient.builder()
        .region("eu-west-1")
        .serverUrlEnvironment("staging")
        .build();

    // Or provide a custom base URL
    // → https://api.us-west-2.staging.example.com/v1
    MyApiClient client = MyApiClient.builder()
        .url("https://api.us-west-2.staging.example.com/v1")
        .build();
    ```
  </Tab>
</Tabs>

## 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:

<Tabs>
  <Tab title="OpenAPI">
    ```yaml title="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]
    ```
  </Tab>

  <Tab title="Fern Definition">
    ```yaml title="api.yml"
    environments:
      Default:
        urls:
          Base: https://api.example.com/v1
        url-templates:
          Base: https://api.{region}.{environment}.example.com/v1
        default-urls:
          Base: https://api.example.com/v1
        variables:
          Base:
            - id: region
              default: us-east-1
              values: [us-east-1, us-west-2, eu-west-1]
            - id: environment
              default: prod
              values: [prod, staging, dev]
    default-environment: Default
    ```
  </Tab>
</Tabs>

For full configuration details, see the docs for your API definition format:

<CardGroup cols={2}>
  <Card title="OpenAPI" href="/learn/api-definitions/openapi/extensions/server-names-and-url-templating">
    Server names and URL templating extensions
  </Card>

  <Card title="Fern Definition" href="/learn/api-definitions/ferndef/api-yml/environments#url-templating">
    URL templating in environments
  </Card>
</CardGroup>