Skip to content

docs: document user-agent template behavior with platform headers #6487

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
devin-ai-integration wants to merge 1 commit into
base: main
Choose a base branch
from
+39 −4
Open

docs: document user-agent template behavior with platform headers #6487

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 12 additions & 1 deletion fern/products/sdks/generators/csharp/configuration.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -96,7 +96,7 @@ When enabled, the generated SDK omits the `X-Fern-Language`, `X-Fern-SDK-Name`,
</ParamField>

<ParamField path="include-platform-headers" type="boolean" default="false" required={false} toc={true}>
When enabled, the generated SDK sends a single structured `User-Agent` header of the form `{sdkName}/{version} ({os}; {arch}) {runtime}/{runtimeVersion}` (for example, `my-sdk/1.2.0 (linux; x86_64) dotnet/8.0.4`), carrying SDK, operating system, architecture, and runtime information in place of the default `User-Agent` and discrete platform headers. If `omit-fern-headers` is enabled, no `User-Agent` or platform headers are sent and this option has no effect.
When enabled, the generated SDK sends a single structured `User-Agent` header of the form `{sdkName}/{version} ({os}; {arch}) {runtime}/{runtimeVersion}` (for example, `my-sdk/1.2.0 (linux; x86_64) dotnet/8.0.4`), carrying SDK, operating system, architecture, and runtime information in place of the default `User-Agent` and discrete platform headers. A configured [`user-agent`](#user-agent) template supplies the leading product token. If `omit-fern-headers` is enabled, no `User-Agent` or platform headers are sent and this option has no effect.
</ParamField>

<ParamField path="package-id" type="string" required={false} toc={true}>
Expand All @@ -122,3 +122,14 @@ When enabled, places core SDK classes (like base client classes and utilities) i
<ParamField path="use-discriminated-unions" type="boolean" required={false} toc={true}>
When enabled, generates discriminated union types for API responses that can contain multiple different object types. This provides type-safe handling of polymorphic responses.
</ParamField>

<ParamField path="user-agent" type="string" default="{packageName}/{version}" required={false} toc={true}>
Sets a custom `User-Agent` header template for requests sent by the generated SDK. The template is resolved at generation time and supports the `{packageName}`, `{version}`, `{language}`, `{generatorVersion}`, `{organization}`, and `{apiName}` placeholders.

```yaml title="generators.yml"
config:
user-agent: "plantstore-dotnet-sdk/{version}"
```

This configuration sends `User-Agent: plantstore-dotnet-sdk/0.1.0`. With [`include-platform-headers`](#include-platform-headers) enabled, the resolved template becomes the product token of the structured header, followed by the platform and runtime segments: `User-Agent: plantstore-dotnet-sdk/0.1.0 (linux; x86_64) dotnet/8.0.4`. A resolved value whose trailing segment isn't a version, such as `plantstore/sdk-dotnet`, is used as-is and no version segment is added.
</ParamField>
4 changes: 3 additions & 1 deletion fern/products/sdks/generators/java/configuration.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -110,7 +110,7 @@ When enabled, the generated SDK omits the `X-Fern-Language`, `X-Fern-SDK-Name`,
</ParamField>

<ParamField path="includePlatformHeaders" type="boolean" default="false" required={false} toc={true}>
When enabled, the generated SDK sends a single structured `User-Agent` header of the form `{sdkName}/{version} ({os}; {arch}) {runtime}/{runtimeVersion}` (for example, `com.fern.sdk/0.0.1 (linux; x86_64) Java/17.0.13`), carrying SDK, operating system, architecture, and runtime information in place of the default `User-Agent` and discrete platform headers. If `omit-fern-headers` is enabled, no `User-Agent` or platform headers are sent and this option has no effect.
When enabled, the generated SDK sends a single structured `User-Agent` header of the form `{sdkName}/{version} ({os}; {arch}) {runtime}/{runtimeVersion}` (for example, `com.fern.sdk/0.0.1 (linux; x86_64) Java/17.0.13`), carrying SDK, operating system, architecture, and runtime information in place of the default `User-Agent` and discrete platform headers. A configured [`user-agent`](#user-agent) template supplies the leading product token. If `omit-fern-headers` is enabled, no `User-Agent` or platform headers are sent and this option has no effect.
</ParamField>

<ParamField path="package-layout" type="'nested' | 'flat'" default="nested" required={false} toc={true}>
Expand Down Expand Up @@ -159,6 +159,8 @@ groups:
```

With this configuration, an organization named `plantstore` with an API named `plants` generates an SDK that sends `User-Agent: plantstore-plants/0.1.0 (java)`.

With [`includePlatformHeaders`](#includeplatformheaders) enabled, the resolved template becomes the product token of the structured header, followed by the platform and runtime segments: a template of `plantstore-plants/{version}` sends `User-Agent: plantstore-plants/0.1.0 (linux; x86_64) Java/17.0.13`. A resolved value whose trailing segment isn't a version, such as `plantstore/sdk-java`, is used as-is and no version segment is added.
</ParamField>

<ParamField path="wrapped-aliases" type="boolean" default="false" required={false} toc={true}>
Expand Down
13 changes: 12 additions & 1 deletion fern/products/sdks/generators/python/configuration.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -181,7 +181,7 @@ When enabled, the generated SDK omits the `X-Fern-Language`, `X-Fern-SDK-Name`,
</ParamField>

<ParamField path="include_platform_headers" type="bool" default="false" required={false} toc={true}>
When enabled, the generated SDK sends a single structured `User-Agent` header of the form `{sdkName}/{version} ({os}; {arch}) {runtime}/{runtimeVersion}` (for example, `fern_examples/0.0.1 (linux; x86_64) Python/3.11.0`), carrying SDK, operating system, architecture, and runtime information in place of the default `User-Agent` and discrete platform headers. If `omit_fern_headers` is enabled, no `User-Agent` or platform headers are sent and this option has no effect.
When enabled, the generated SDK sends a single structured `User-Agent` header of the form `{sdkName}/{version} ({os}; {arch}) {runtime}/{runtimeVersion}` (for example, `fern_examples/0.0.1 (linux; x86_64) Python/3.11.0`), carrying SDK, operating system, architecture, and runtime information in place of the default `User-Agent` and discrete platform headers. A configured [`user-agent`](#user-agent) template supplies the leading product token. If `omit_fern_headers` is enabled, no `User-Agent` or platform headers are sent and this option has no effect.
</ParamField>

<ParamField path="pyproject_python_version" type="string" default="^3.10" required={false} toc={true}>
Expand Down Expand Up @@ -219,6 +219,17 @@ When enabled, skips code formatting (like black) on the generated Python code.
Sets the client timeout in seconds, or `infinity` to disable timeouts.
</ParamField>

<ParamField path="user-agent" type="string" default="{packageName}/{version}" required={false} toc={true}>
Sets a custom `User-Agent` header template for requests sent by the generated SDK. Unlike the other Python options, this key is hyphenated. The template is resolved at generation time and supports the `{packageName}`, `{version}`, `{language}`, `{generatorVersion}`, `{organization}`, and `{apiName}` placeholders.

```yaml title="generators.yml"
config:
user-agent: "plantstore-python-sdk/{version}"
```

This configuration sends `User-Agent: plantstore-python-sdk/0.1.0`. With [`include_platform_headers`](#include_platform_headers) enabled, the resolved template becomes the product token of the structured header, followed by the platform and runtime segments: `User-Agent: plantstore-python-sdk/0.1.0 (linux; x86_64) Python/3.11.0`. A resolved value whose trailing segment isn't a version, such as `plantstore/sdk-python`, is used as-is and no version segment is added.
</ParamField>

<ParamField path="use_api_name_in_package" type="bool" default="false" required={false} toc={true}>
When enabled, includes the API name as part of the package structure and naming.
</ParamField>
Expand Down
13 changes: 12 additions & 1 deletion fern/products/sdks/generators/typescript/configuration.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -406,7 +406,7 @@ When enabled, the generated SDK omits the `X-Fern-Language`, `X-Fern-SDK-Name`,
</ParamField>

<ParamField path="includePlatformHeaders" type="boolean" default="false" toc={true}>
When enabled, the generated SDK sends a single structured `User-Agent` header of the form `{sdkName}/{version} ({os}; {arch}) {runtime}/{runtimeVersion}` (for example, `my-sdk/0.0.1 (linux; x86_64) Node/20.11.0`), carrying SDK, operating system, architecture, and runtime information in place of the default `User-Agent` and discrete platform headers. If `omitFernHeaders` is enabled, no `User-Agent` or platform headers are sent and this option has no effect.
When enabled, the generated SDK sends a single structured `User-Agent` header of the form `{sdkName}/{version} ({os}; {arch}) {runtime}/{runtimeVersion}` (for example, `my-sdk/0.0.1 (linux; x86_64) Node/20.11.0`), carrying SDK, operating system, architecture, and runtime information in place of the default `User-Agent` and discrete platform headers. A configured [`user-agent`](#user-agent) template supplies the leading product token. If `omitFernHeaders` is enabled, no `User-Agent` or platform headers are sent and this option has no effect.
</ParamField>

<ParamField path="outputSourceFiles" type="boolean" default="true" toc={true}>
Expand Down Expand Up @@ -526,6 +526,17 @@ The default is `web`.
When `treatUnknownAsAny` is enabled, [unknown types from Fern are generated into TypeScript using `any` instead of the `unknown` type](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-0.html#new-unknown-top-type).
</ParamField>

<ParamField path="user-agent" type="string" default="{packageName}/{version}" required={false} toc={true}>
Sets a custom `User-Agent` header template for requests sent by the generated SDK. Unlike the other TypeScript options, this key is hyphenated. The template is resolved at generation time and supports the `{packageName}`, `{version}`, `{language}`, `{generatorVersion}`, `{organization}`, and `{apiName}` placeholders.

```yaml title="generators.yml"
config:
user-agent: "plantstore-node-sdk/{version}"
```

This configuration sends `User-Agent: plantstore-node-sdk/0.1.0`. With [`includePlatformHeaders`](#includeplatformheaders) enabled, the resolved template becomes the product token of the structured header, followed by the platform and runtime segments: `User-Agent: plantstore-node-sdk/0.1.0 (linux; x86_64) Node/20.11.0`. A resolved value whose trailing segment isn't a version, such as `@plantstore/sdk`, is used as-is and no version segment is added.
</ParamField>

<ParamField path="useBigInt" type="boolean" default="false" toc={true}>
When `useBigInt` is set to `true`, a customized JSON serializer & deserializer is used that will preserve the precision of `bigint`'s, as opposed to the native `JSON.stringify` and `JSON.parse` function which converts `bigint`'s to number's losing precision.

Expand Down
Loading