Use audiences to filter your API

Use x-fern-audiences to filter to relevant operations, channels and message schemas

Use audiences to filter your API

Use x-fern-audiences to filter to relevant operations, channels and message schemas

Team and Enterprise feature

This feature is available only for the Team and Enterprise plans. To get started, reach out to support@buildwithfern.com.

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-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.

Team and Enterprise feature

This feature is available only for the Team and Enterprise plans. To get started, reach out to support@buildwithfern.com.

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-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.

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

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

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

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

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