Global configuration

The api.yml configuration supports global configuration like headers and path parameters.

Global headers

You can specify headers that are meant to be included on every request:

name: api
headers:
  X-App-Id: string

When you define global headers in your api.yml, you must include them in your endpoint examples.

Global path parameters

You can specify path parameters that are meant to be included on every request:

name: api
base-path: /{userId}/{orgId}
path-parameters:
  userId: string
  orgId: string

Overriding the base path

If you have certain endpoints that don’t live at the configured base-path, you can override the base-path at the endpoint level.

service: 
  endpoints: 
    getMovie: 
      method: POST
      base-path: "override/{arg}"
      path: "movies/{movieId}"
      path-parameters: 
        arg: string

SDK variables

Use variables to declare values that SDK users set once on the client instead of passing to every endpoint call. Reference a variable from a path parameter with $<variable-name>:

name: api
variables:
  gardenId:
    type: string
    env: PLANT_GARDEN_ID
  zoneId: string

service:
  base-path: /gardens/{gardenId}/zones/{zoneId}
  endpoints:
    listPlantsInZone:
      path-parameters:
        gardenId: $gardenId
        zoneId: $zoneId
      method: GET
      path: /plants

The optional env key names an environment variable the SDK reads when the variable isn’t passed to the client. Generated SDK behavior and language support match the OpenAPI x-fern-sdk-variables extension.

Global query parameters

You can’t yet specify query parameters that are meant to be included on every request. If you’d like to see this feature, upvote this issue.

Idempotency headers

Configure idempotency headers to define which headers SDK users can specify for safe request retries. You must also mark each endpoint as idempotent for the headers to be exposed. When both are configured, Fern’s generated SDKs expose these headers as parameters for idempotent endpoint calls.

name: api
auth: bearer
idempotency-headers:
  Idempotency-Key: string
  Idempotency-Expiration: optional<integer>

Each key in idempotency-headers is the HTTP header name, and the value is the type. SDK users can then specify these headers when calling idempotent endpoints.