Deep Dives

Filter Your Endpoints (Audiences)

Pro Feature

This feature is only available on paid plans. Please schedule a demo or email us to get started.

Use audiences to generate tailored SDKs for different groups of API consumers. Common examples of audiences include:

  • Internal consumers (e.g., frontend developers who use the API)
  • Beta testers
  • Customers

Learn how to use audiences to filter which endpoints are included in your SDKs and documentation.

Configuring audiences

For both the Fern Definition and OpenAPI spec, configuring audiences involves:

  1. Marking your API elements with audience tags.
  2. Applying filters in generators.yml. Without filtering configuration, all endpoints will be included in your SDK regardless of their audience tags.

Configuring audiences in a Fern Definition involves:

  1. Explicitly defining audiences in api.yml.
  2. Configuring audiences for specific endpoints, types, and properties.
  3. Apply audience filters to your SDK so only certain endpoints are passed to the generators.
1

Defining audiences

Audiences are explicitly declared in Fern Definition. To use audiences in your Fern Definition, add them to api.yml.

In the example below, we have created audiences for internal, beta, and customer groups:

api.yml
1name: api 
2audiences: 
3  - internal 
4  - beta 
5  - customers
2

Apply audiences to your endpoints, types, and properties

Once you’ve defined audiences, mark endpoints, types, or properties for a particular consumer by adding an audience with the relevant groups.

In this example, the sendEmail endpoint is only available to internal consumers:

user.yml
1service:
2  base-path: /users
3  auth: true
4  endpoints:
5    sendEmail:
6      audiences:
7        - internal
8      path: /send-email
9      ...

Types can also be marked for different audiences.

In this example, the Email type is available to internal and beta consumers:

user.yml
1Email: 
2  properties:
3    subject: string
4    body: optional<string>
5  audiences: 
6    - internal
7    - beta

In this example, the to property is available to beta consumers only:

user.yml
1Email: 
2  properties:
3    subject: string
4    body: optional<string>
5    to: 
6      type: string
7      docs: The recipient of the email
8      audiences: 
9        - beta
3

Set up SDK filters in generators.yml

In generators.yml, you can apply audience filters so that only certain endpoints are passed to the generators.

The following example configures the SDKs to filter for customers:

generators.yml
1groups:
2  external:
3    audiences:
4      - customers
5    generators: 
6    ...
4

Generate your SDK

$fern generate --group sdk

Configuring audiences in an OpenAPI spec involves:

  1. Configuring audience extensions for specific servers, endpoints, schemas, and properties.
  2. Apply audience filters to your SDK so only certain endpoints are passed to the generators.

Unlike the Fern Definition, OpenAPI doesn’t have a central audience declaration.

1

Define audiences

OpenAPI uses x-fern-audiences to filter to servers, endpoints, schemas and properties.

To mark a server with a particular audience, add the x-fern-server-name and x-fern-audiences extension to the relevant server.

In the example below, the Production server is only available to public consumers:

openapi.yml
1servers:
2  - url: https://api.com
3    x-fern-server-name: Production
4    x-fern-audiences:
5      - public

To mark an endpoint with a particular audience, add the x-fern-audiences extension to the relevant endpoint.

In the example below, the POST /users/sendEmail endpoint is only available to public consumers:

openapi.yml
1paths:
2  /users/sendEmail:
3    post:
4      x-fern-audiences:
5        - public
6      operationId: send_email

Schemas can be marked for different audiences, as well.

In this example, the Email type is available to both public and beta customers.

openapi.yml
1components:
2  schemas:
3    Email:
4      title: Email
5      type: object
6      properties:
7        subject:
8          type: string
9        body:
10          type: string
11        to:
12          type: string
13      x-fern-audiences:
14        - public
15        - beta

In this example, the to property is available to beta customers only.

openapi.yml
1components:
2  schemas:
3    Email:
4      title: Email
5      type: object
6      properties:
7        subject:
8          type: string
9        body:
10          type: string
11        to:
12          type: string
13          x-fern-audiences:
14            - beta
2

Set up SDK filters in generators.yml

In generators.yml, you can apply audience filters so that only certain endpoints are passed to the generators.

The following example configures the SDK to filter to the public audience:

generators.yml
1groups:
2  sdks:
3    audiences:
4      - public
5    generators:
6    ...
3

Generate your SDK

$fern generate --group sdk