docs: add server URL templating documentation to SDK design section by iamnamananand996 · Pull Request #3672 · fern-api/docs

iamnamananand996 · 2026-02-18T11:54:26Z

docs: add server URL templating documentation

Summary

Adds documentation for the server URL templating feature across three areas of the docs:

New SDK guide page (guides/server-url-templating.mdx) under "SDK design" — shows Python and Java SDK usage with URL template variables (e.g., region, server_url_environment) passed as constructor/builder parameters, plus compact OpenAPI and Fern Definition setup snippets.
Expanded OpenAPI extensions page (extensions/server-names.mdx) — renamed from "Server names" to "Server names and URL templating". Added sections for multiple base URLs, x-fern-default-url extension, and URL template variable configuration with a full OpenAPI example.
Updated Fern Definition environments page (ferndef/api-yml/environments.mdx) — added a "URL templating" section documenting url-templates, default-urls, and variables configuration in api.yml.

Supporting changes:

Updated api-def.yml nav entry title and sdks.yml to include the new page
Added redirect from old /server-names to /server-names-and-url-templating
Updated cross-references in api-explorer.mdx, runnable-endpoint.mdx, and overview.md
Added x-fern-default-url as its own row in the extensions overview table

Python/Java SDK examples were verified against actual seed-generated output in fern-api/fern at seed/python-sdk/server-url-templating/ and seed/java-sdk/server-url-templating/.

Updates since last revision

Simplified SDK guide page: removed verbose environment class snippets, kept only the client usage examples showing URL variable parameters per reviewer feedback.
Added <Note> callout clarifying Python and Java only support.
Restructured page to lead with SDK behavior, then link out to full OpenAPI/Fern Definition config docs via <CardGroup> cards.
Added URL templating docs to the OpenAPI extensions page and Fern Definition environments page (previously only had the standalone SDK guide).
Updated all cross-references and added redirect for the renamed page.

Review & Testing Checklist for Human

Fern Definition api.yml format: The url-templates, default-urls, and variables config was derived from internal schema types (MultipleBaseUrlsEnvironmentSchema). Confirm this matches what users actually write — it may be an internal representation populated only during OpenAPI import.
Redirect works: Verify that /learn/api-definitions/openapi/extensions/server-names correctly redirects to /learn/api-definitions/openapi/extensions/server-names-and-url-templating. Test in the preview deployment.
Cross-reference links resolve: The following pages were updated with new link targets — verify they all render correctly:
- api-explorer.mdx
- runnable-endpoint.mdx
- overview.md (extensions table)
Preview all changed pages: Check the preview deployment for:
- SDK guide page (tabs, code blocks, card group)
- OpenAPI extensions page (renamed, expanded sections)
- Fern Definition environments page (new URL templating section)
x-server-name vs x-fern-server-name: The OpenAPI test fixture uses x-server-name at the top level and x-fern-server-name at the endpoint level. Verify the docs correctly explain when to use each (currently documented in the "Multiple base URLs" section).

Notes

Requested by: @iamnamananand996
Link to Devin run

Co-Authored-By: naman.anand@buildwithfern.com <iamnamananand996@gmail.com>

devin-ai-integration · 2026-02-18T11:54:32Z

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

Disable automatic comment and CI monitoring

github-actions · 2026-02-18T11:54:46Z

+
+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.
+
+Fern reads the standard OpenAPI `servers` block and generates SDK clients that accept these variables, falling back to sensible defaults when they are not provided.


🚫 [vale] _{reported by reviewdog 🐶}
[Microsoft.Contractions] Use 'they're' instead of 'they are'.

github-actions · 2026-02-18T11:55:30Z

🌿 Preview your docs: https://fern-preview-85a5c79b-d877-40fc-9be4-c27c92a37591.docs.buildwithfern.com/learn

Here are the markdown pages you've updated:

Co-Authored-By: naman.anand@buildwithfern.com <iamnamananand996@gmail.com>

github-actions · 2026-02-18T12:14:53Z

+
+## Language support
+
+Server URL templating is currently supported in the following generators:


⚠️ [vale] _{reported by reviewdog 🐶}
[FernStyles.Current] Avoid time-relative terms like 'currently' that become outdated

github-actions · 2026-02-25T19:31:12Z


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

+## URL templating


📝 [vale] _{reported by reviewdog 🐶}
[FernStyles.Headings] 'URL templating' should use sentence-style capitalization.

github-actions · 2026-02-25T19:31:12Z


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


⚠️ [vale] _{reported by reviewdog 🐶}
[FernStyles.Current] Avoid time-relative terms like 'currently' that become outdated

github-actions · 2026-02-25T19:31:12Z

+
+`x-fern-server-name` is also used alongside URL template variables, as shown below.
+
+## URL templating and `x-fern-default-url`


📝 [vale] _{reported by reviewdog 🐶}
[FernStyles.Headings] 'URL templating and ******************' should use sentence-style capitalization.

github-actions · 2026-02-25T19:31:12Z

+
+## URL templating and `x-fern-default-url`
+
+<Note>URL template variables and `x-fern-default-url` are currently supported for Python and Java SDK generation only.</Note>


⚠️ [vale] _{reported by reviewdog 🐶}
[FernStyles.Current] Avoid time-relative terms like 'currently' that become outdated

github-actions · 2026-02-25T19:31:12Z

+
+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>


⚠️ [vale] _{reported by reviewdog 🐶}
[FernStyles.Current] Avoid time-relative terms like 'currently' that become outdated

github-actions · 2026-02-25T19:31:12Z

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


📝 [vale] _{reported by reviewdog 🐶}
[Microsoft.URLFormat] Use 'of' (not 'for') to describe the relationship of the word URL to a resource.

devin-ai-integration

Devin Review found 1 potential issue.

View 5 additional findings in Devin Review.

devin-ai-integration · 2026-02-25T19:43:54Z

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


🟡 New page missing required <Markdown src="/snippets/agent-directive.mdx"/> directive

The new file fern/products/sdks/guides/server-url-templating.mdx is missing the required <Markdown src="/snippets/agent-directive.mdx"/> agent directive snippet after the front matter.

Convention violation details

The repository's AGENTS.md explicitly states:

Every new .mdx page created under fern/pages/ or fern/products/ must include the agent directive snippet. Add the following line after the closing --- of the front matter.

Every other .mdx file in the same directory (fern/products/sdks/guides/) includes this directive — e.g., generated-sdk.mdx, configure-readme.mdx, customize-method-names.mdx, etc. (12 out of 12 existing files). The new server-url-templating.mdx is the only file missing it.

The directive should be added on line 5 (after the closing --- of the front matter), like:

--- <Markdown src="/snippets/agent-directive.mdx"/>

Impact: The page will be missing whatever agent directive content is injected by this snippet, creating an inconsistency with all other pages in the documentation.

Suggested change

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.

<Markdown src="/snippets/agent-directive.mdx"/>

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.

Was this helpful? React with 👍 or 👎 to provide feedback.

Co-Authored-By: naman.anand@buildwithfern.com <iamnamananand996@gmail.com>

…/git-manager.devin.ai/proxy/github.com/fern-api/docs into devin/1771415548-server-url-templating-docs

…ble usage" This reverts commit 81c3d75.

Add a Python Environment class example and update the Python usage to use the environment parameter (was server_url_environment) and show how to pass a custom base_url. Also add a Java builder example demonstrating .url(...) to supply a custom base URL. These edits clarify how SDK users can override the generated default server URLs.

…/github.com/fern-api/docs into devin/1771415548-server-url-templating-docs

Replace hard-coded .url(...) example with .region("eu-west-1") and .serverUrlEnvironment("staging") to demonstrate server URL templating by region and environment. Updated fern/products/sdks/guides/server-url-templating.mdx.

Replace 'Or provide a custom base URL' with a clearer note: 'Target a specific region and environment via URL variables' in the Python and Java snippets of the server-url-templating guide (fern/products/sdks/guides/server-url-templating.mdx). This improves clarity about using region and environment parameters when constructing MyApiClient.

Insert a Java code example for an Environment class into the server URL templating SDK guide, demonstrating a REGIONAL_API_SERVER constant and a custom() builder. Improves clarity about how the generated SDK exposes environment configuration.

Add inline comments demonstrating the resolved base URLs for default, region+environment, and custom base URL cases in the Python and Java examples in fern/products/sdks/guides/server-url-templating.mdx. These examples clarify what URL the SDK will use in each configuration.

docs: add server URL templating documentation to SDK design section

2fce774

Co-Authored-By: naman.anand@buildwithfern.com <iamnamananand996@gmail.com>

devin-ai-integration Bot assigned iamnamananand996 Feb 18, 2026

github-actions Bot reviewed Feb 18, 2026

View reviewed changes

devin-ai-integration Bot and others added 2 commits February 18, 2026 12:01

fix: address vale lint - use contraction 'they're'

6eebf58

Co-Authored-By: naman.anand@buildwithfern.com <iamnamananand996@gmail.com>

fix: limit language support to Python and Java only

5c8063c

Co-Authored-By: naman.anand@buildwithfern.com <iamnamananand996@gmail.com>

github-actions Bot reviewed Feb 18, 2026

View reviewed changes

devalog and others added 2 commits February 25, 2026 14:06

restructure

a81ea6c

Merge branch 'main' into devin/1771415548-server-url-templating-docs

c8626c2

github-actions Bot reviewed Feb 25, 2026

View reviewed changes

devin-ai-integration Bot reviewed Feb 25, 2026

View reviewed changes

devin-ai-integration Bot and others added 9 commits February 25, 2026 19:50

fix: simplify Python and Java examples to just show URL variable usage

81c3d75

Co-Authored-By: naman.anand@buildwithfern.com <iamnamananand996@gmail.com>

Merge branch 'devin/1771415548-server-url-templating-docs' of https:/…

e645bd5

…/git-manager.devin.ai/proxy/github.com/fern-api/docs into devin/1771415548-server-url-templating-docs

Revert "fix: simplify Python and Java examples to just show URL varia…

883880a

…ble usage" This reverts commit 81c3d75.

Merge branch 'devin/1771415548-server-url-templating-docs' of https:/…

77259cd

…/github.com/fern-api/docs into devin/1771415548-server-url-templating-docs

Use region and serverUrlEnvironment in example

375e32b

Replace hard-coded .url(...) example with .region("eu-west-1") and .serverUrlEnvironment("staging") to demonstrate server URL templating by region and environment. Updated fern/products/sdks/guides/server-url-templating.mdx.

Add Environment.java example to SDK guide

eaebeb5

Insert a Java code example for an Environment class into the server URL templating SDK guide, demonstrating a REGIONAL_API_SERVER constant and a custom() builder. Improves clarity about how the generated SDK exposes environment configuration.

devalog approved these changes Feb 25, 2026

View reviewed changes

iamnamananand996 merged commit c2a53e9 into main Feb 25, 2026
2 checks passed

iamnamananand996 deleted the devin/1771415548-server-url-templating-docs branch February 25, 2026 20:24

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: add server URL templating documentation to SDK design section#3672

docs: add server URL templating documentation to SDK design section#3672
iamnamananand996 merged 14 commits intomainfrom
devin/1771415548-server-url-templating-docs

iamnamananand996 commented Feb 18, 2026 •

edited by devin-ai-integration Bot

Loading

Uh oh!

devin-ai-integration Bot commented Feb 18, 2026

Uh oh!

github-actions Bot Feb 18, 2026

Uh oh!

github-actions Bot commented Feb 18, 2026 •

edited

Loading

Uh oh!

github-actions Bot Feb 18, 2026

Uh oh!

github-actions Bot Feb 25, 2026

Uh oh!

github-actions Bot Feb 25, 2026

Uh oh!

github-actions Bot Feb 25, 2026

Uh oh!

github-actions Bot Feb 25, 2026

Uh oh!

github-actions Bot Feb 25, 2026

Uh oh!

github-actions Bot Feb 25, 2026

Uh oh!

devin-ai-integration Bot left a comment

Uh oh!

devin-ai-integration Bot Feb 25, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants


		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.

		Fern reads the standard OpenAPI `servers` block and generates SDK clients that accept these variables, falling back to sensible defaults when they are not provided.


		## Language support

		Server URL templating is currently supported in the following generators:


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

		## URL templating


		## URL templating

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


		`x-fern-server-name` is also used alongside URL template variables, as shown below.

		## URL templating and `x-fern-default-url`


		## URL templating and `x-fern-default-url`

		<Note>URL template variables and `x-fern-default-url` are currently supported for Python and Java SDK generation only.</Note>


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

Conversation

iamnamananand996 commented Feb 18, 2026 • edited by devin-ai-integration Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

docs: add server URL templating documentation

Summary

Updates since last revision

Review & Testing Checklist for Human

Notes

Uh oh!

devin-ai-integration Bot commented Feb 18, 2026

🤖 Devin AI Engineer

Uh oh!

github-actions Bot Feb 18, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Feb 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot Feb 18, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Feb 25, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Feb 25, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Feb 25, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Feb 25, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Feb 25, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Feb 25, 2026

Choose a reason for hiding this comment

Uh oh!

devin-ai-integration Bot left a comment

Choose a reason for hiding this comment

Uh oh!

devin-ai-integration Bot Feb 25, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

iamnamananand996 commented Feb 18, 2026 •

edited by devin-ai-integration Bot

Loading

github-actions Bot commented Feb 18, 2026 •

edited

Loading