Use audiences to filter your API

Audiences are a useful tool for segmenting your event-driven API for different consumers. Common examples of audiences include public and beta.

Remember to filter your SDKs and Docs after specifying audiences. If no audiences are specified, nothing will be filtered.

SDKs

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

generators.yml

1 groups:
2   sdks:
3     audiences:
4       - public
5     generators:
6       - name: fernapi/fern-typescript-node-sdk
7         version: 0.8.8

Docs

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

docs.yml

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

Filter operations

Add x-fern-audiences to operations to control which operations are included for specific audiences:

asyncapi.yml

1 operations:
2   sendPublicNotification:
3     action: send
4     channel:
5       $ref: '#/channels/public~1notifications'
6     x-fern-audiences:
7       - public
8   sendBetaAlert:
9     action: send
10     channel:
11       $ref: '#/channels/beta~1alerts'
12     x-fern-audiences:
13       - beta

Filter channels

You can also filter entire channels by audience:

asyncapi.yml

1 channels:
2   public/events:
3     address: public/events
4     messages:
5       PublicEvent:
6         $ref: '#/components/messages/PublicEvent'
7     x-fern-audiences:
8       - public
9   internal/events:
10     address: internal/events
11     messages:
12       InternalEvent:
13         $ref: '#/components/messages/InternalEvent'
14     x-fern-audiences:
15       - internal

Filter message schemas

Filter specific message schemas to different audiences:

asyncapi.yml

1 components:
2   messages:
3     PublicUserEvent:
4       contentType: application/json
5       payload:
6         $ref: '#/components/schemas/PublicUser'
7       x-fern-audiences:
8         - public
9     AdminUserEvent:
10       contentType: application/json
11       payload:
12         $ref: '#/components/schemas/AdminUser'
13       x-fern-audiences:
14         - admin
15   schemas:
16     PublicUser:
17       type: object
18       properties:
19         id:
20           type: string
21         name:
22           type: string
23         email:
24           type: string
25       x-fern-audiences:
26         - public
27     AdminUser:
28       allOf:
29         - $ref: '#/components/schemas/PublicUser'
30         - type: object
31           properties:
32             role:
33               type: string
34             permissions:
35               type: array
36               items:
37                 type: string
38       x-fern-audiences:
39         - admin

Filter schema properties

You can filter individual properties within schemas:

asyncapi.yml

1 components:
2   schemas:
3     UserEvent:
4       type: object
5       properties:
6         id:
7           type: string
8         email:
9           type: string
10           x-fern-audiences:
11             - internal
12         publicName:
13           type: string
14           x-fern-audiences:
15             - public
16         internalNotes:
17           type: string
18           x-fern-audiences:
19             - internal

This allows you to have different views of the same event schema for different audiences, showing only the relevant information to each consumer.