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

Audiences for SDKs

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:

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

Audiences with docs

If generating Fern Docs, update your docs.yml configuration to include your audiences.

The following example shows how to configure your docs.yml to publish documentation for the customers audience:

1
navigation:
2
  - api: API Reference
3
    audiences:
4
      - customers