Fern Definition

Audiences

Audiences are a useful tool for segmenting your API for different consumers. Common audiences include:

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

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

Configuration

To prevent typos, you must specify all your audiences in api.yml:

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

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

1
2
3
4
5
groups:
  external:
    audiences: # <---
      - external
    generators: ...

By default, if no audiences are specified, then all endpoints, types, and properties are passed to the generators.

Audiences for Endpoints

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

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

Audiences for Types

We can mark types for different audiences. In this example, the Email type is available to internal and beta consumers:

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

Audiences for Properties

We can mark the properties of a type for different audiences. In this example, the to property is available to beta consumers:

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