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:

1
name: api
2
headers:
3
  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:

1
name: api
2
base-path: /{userId}/{orgId}
3
path-parameters:
4
  userId: string
5
  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.

1
service: 
2
  endpoints: 
3
    getMovie: 
4
      method: POST
5
      base-path: "override/{arg}"
6
      path: "movies/{movieId}"
7
      path-parameters: 
8
        arg: string

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.

1
name: api
2
auth: bearer
3
idempotency-headers:
4
  Idempotency-Key: string
5
  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.