Environments

Fern Definition isn’t recommended for new customers and Fern isn’t accepting feature requests for this format. It remains supported for existing users.

You can specify the environments where your server is deployed.

Single URL environments

api.yml

1 name: api
2 environments:
3   Production: https://www.yoursite.com
4   Staging:
5     docs: This staging environment is helpful for testing!
6     url: https://www.staging.yoursite.com

Multiple URLs per environment

You can specify multiple URLs per environment. This is helpful if you have a microservice architecture, and you want a single SDK to interact with multiple servers.

api.yml

1 environments:
2   Production:
3     urls:
4       Auth: https://auth.yoursite.com
5       Plants: https://plants.yoursite.com
6   Staging:
7     urls:
8       Auth: https://auth.staging.yoursite.com
9       Plants: https://plants.staging.yoursite.com

If you choose to use this feature, you must specify a url for each service you define:

auth.yml

1 service:
2   url: Auth
3   base-path: /auth
4   ...

Default environment

You can also provide a default environment:

api.yml

1 name: api
2 environments:
3   Production: https://www.yoursite.com
4   Staging:
5     docs: This staging environment is helpful for testing!
6     url: https://www.staging.yoursite.com
7 default-environment: Production

By providing a default environment, the generated SDK will be setup to hit that URL out-of-the-box.

URL templating

URL templating is currently supported for Python and Java SDK generation only.

For APIs deployed across multiple regions or environments, you can define URL templates with variable placeholders that SDK users customize at runtime. To set this up:

Define your static base URLs under urls — these appear in the generated environments enum.
Add url-templates with {variable} placeholders (e.g., https://api.{region}.example.com/v1) for each service. Fern exposes these as configurable parameters in the SDK.
Provide default-urls as concrete fallbacks so SDK users get a working client out of the box without supplying variables.
List the available variables for each service, each with an id, a default value, and an optional values list to constrain allowed options.

api.yml

1 environments:
2   RegionalApiServer:
3     urls:
4       Base: https://api.example.com/v1
5       Auth: https://auth.example.com
6     url-templates:
7       Base: https://api.{region}.{environment}.example.com/v1
8       Auth: https://auth.{region}.example.com
9     default-urls:
10       Base: https://api.example.com/v1
11       Auth: https://auth.example.com
12     variables:
13       Base:
14         - id: region
15           default: us-east-1
16           values:
17             - us-east-1
18             - us-west-2
19             - eu-west-1
20         - id: environment
21           default: prod
22           values:
23             - prod
24             - staging
25             - dev
26       Auth:
27         - id: region
28           default: us-east-1
29           values:
30             - us-east-1
31             - us-west-2
32             - eu-west-1
33 default-environment: RegionalApiServer

Base path

If you would like all of your endpoints to be prefixed with a path, use base-path.

In the example below, every endpoint is prefixed with a /v1:

api.yml

1 name: api
2 base-path: /v1

Audiences

If you have listed environments that you want to filter, you can leverage audiences.

api.yml

1 audiences:
2   - public
3 
4 environments:
5   Dev: 
6     url: https://api.dev.buildwithfern.com
7   Prod: 
8     url: https://api.buildwithfern.com
9     audiences:
10       - external

Fern Definition isn’t recommended for new customers and Fern isn’t accepting feature requests for this format. It remains supported for existing users.

You can specify the environments where your server is deployed.

Single URL environments

api.yml

1 name: api
2 environments:
3   Production: https://www.yoursite.com
4   Staging:
5     docs: This staging environment is helpful for testing!
6     url: https://www.staging.yoursite.com

Multiple URLs per environment

You can specify multiple URLs per environment. This is helpful if you have a microservice architecture, and you want a single SDK to interact with multiple servers.

api.yml

1 environments:
2   Production:
3     urls:
4       Auth: https://auth.yoursite.com
5       Plants: https://plants.yoursite.com
6   Staging:
7     urls:
8       Auth: https://auth.staging.yoursite.com
9       Plants: https://plants.staging.yoursite.com

If you choose to use this feature, you must specify a url for each service you define:

auth.yml

1 service:
2   url: Auth
3   base-path: /auth
4   ...

Default environment

You can also provide a default environment:

api.yml

1 name: api
2 environments:
3   Production: https://www.yoursite.com
4   Staging:
5     docs: This staging environment is helpful for testing!
6     url: https://www.staging.yoursite.com
7 default-environment: Production

By providing a default environment, the generated SDK will be setup to hit that URL out-of-the-box.

URL templating

URL templating is currently supported for Python and Java SDK generation only.

For APIs deployed across multiple regions or environments, you can define URL templates with variable placeholders that SDK users customize at runtime. To set this up:

Define your static base URLs under urls — these appear in the generated environments enum.
Add url-templates with {variable} placeholders (e.g., https://api.{region}.example.com/v1) for each service. Fern exposes these as configurable parameters in the SDK.
Provide default-urls as concrete fallbacks so SDK users get a working client out of the box without supplying variables.
List the available variables for each service, each with an id, a default value, and an optional values list to constrain allowed options.

api.yml

1 environments:
2   RegionalApiServer:
3     urls:
4       Base: https://api.example.com/v1
5       Auth: https://auth.example.com
6     url-templates:
7       Base: https://api.{region}.{environment}.example.com/v1
8       Auth: https://auth.{region}.example.com
9     default-urls:
10       Base: https://api.example.com/v1
11       Auth: https://auth.example.com
12     variables:
13       Base:
14         - id: region
15           default: us-east-1
16           values:
17             - us-east-1
18             - us-west-2
19             - eu-west-1
20         - id: environment
21           default: prod
22           values:
23             - prod
24             - staging
25             - dev
26       Auth:
27         - id: region
28           default: us-east-1
29           values:
30             - us-east-1
31             - us-west-2
32             - eu-west-1
33 default-environment: RegionalApiServer

Base path

If you would like all of your endpoints to be prefixed with a path, use base-path.

In the example below, every endpoint is prefixed with a /v1:

api.yml

1 name: api
2 base-path: /v1

Audiences

If you have listed environments that you want to filter, you can leverage audiences.

api.yml

1 audiences:
2   - public
3 
4 environments:
5   Dev: 
6     url: https://api.dev.buildwithfern.com
7   Prod: 
8     url: https://api.buildwithfern.com
9     audiences:
10       - external

1	name: api
2	environments:
3	Production: https://www.yoursite.com
4	Staging:
5	docs: This staging environment is helpful for testing!
6	url: https://www.staging.yoursite.com

1	environments:
2	Production:
3	urls:
4	Auth: https://auth.yoursite.com
5	Plants: https://plants.yoursite.com
6	Staging:
7	urls:
8	Auth: https://auth.staging.yoursite.com
9	Plants: https://plants.staging.yoursite.com

1	environments:
2	RegionalApiServer:
3	urls:
4	Base: https://api.example.com/v1
5	Auth: https://auth.example.com
6	url-templates:
7	Base: https://api.{region}.{environment}.example.com/v1
8	Auth: https://auth.{region}.example.com
9	default-urls:
10	Base: https://api.example.com/v1
11	Auth: https://auth.example.com
12	variables:
13	Base:
14	- id: region
15	default: us-east-1
16	values:
17	- us-east-1
18	- us-west-2
19	- eu-west-1
20	- id: environment
21	default: prod
22	values:
23	- prod
24	- staging
25	- dev
26	Auth:
27	- id: region
28	default: us-east-1
29	values:
30	- us-east-1
31	- us-west-2
32	- eu-west-1
33	default-environment: RegionalApiServer

1	audiences:
2	- public
3
4	environments:
5	Dev:
6	url: https://api.dev.buildwithfern.com
7	Prod:
8	url: https://api.buildwithfern.com
9	audiences:
10	- external