Audiences in Fern Definition

Audiences are a useful tool for segmenting your API for different consumers. You can configure your Fern Docs to publish documentation specific to an Audience. You can use audiences in your OpenAPI Specification, too.

Common examples of audiences include:

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

By default, if no audience is specified, it will be accessible to all consumers.

Configuration

The Fern Definition has a first-class concept for marking different endpoints, types, and properties for different audiences.

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:

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

Audiences for endpoints

To mark an endpoint for a particular consumer, add an audience with the relevant groups.

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

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

Audiences for types

Types can also be marked for different audiences.

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

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

Audiences for properties

Properties of a type can also be marked for different audiences.

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

1
Email: 
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

Filter your SDKs and docs

After marking your API elements, filter each output to the audiences you want: SDKs in generators.yml and your API Reference in docs.yml.