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
name: api 
2
audiences: 
3
  - internal 
4
  - beta 

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

1
groups:
2
  external:
3
    audiences: # <---
4
      - external
5
    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
service:
2
  base-path: /users
3
  auth: true
4
  endpoints:
5
    sendEmail:
6
      audiences: # <---
7
        - internal
8
      path: /send-email
9
      ...

Audiences for Types

We can mark types 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

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

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