Skip to content

Commit d76dcb5

Browse files
devalogdevalog
authored
Move content into Filter Your Endpoints guide (#88)
1 parent b776d2c commit d76dcb5

File tree

1 file changed

+230
-1
lines changed

1 file changed

+230
-1
lines changed

‎fern/products/sdks/guides/filter-your-endpoints-audiences.mdx‎

Lines changed: 230 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,235 @@ description: Guide to filtering your API endpoints using audiences.
55

66
<Markdown src="/snippets/pro-callout.mdx"/>
77

8+
Use audiences to generate tailored SDKs for different groups of API consumers. Common examples of audiences include:
9+
- Internal consumers (e.g., frontend developers who use the API)
10+
- Beta testers
11+
- Customers
12+
813
Learn how to use audiences to filter which endpoints are included in your SDKs and documentation.
914

10-
<Warning>Docs are coming soon for this page.<br/><br/>Please [book a demo](https://buildwithfern.com/book-demo) or [reach out to us](https://buildwithfern.com/book-demo) to get set up with this feature. </Warning>
15+
16+
## Configuring audiences
17+
18+
For both the Fern Definition and OpenAPI spec, configuring audiences involves:
19+
1. Marking your API elements with audience tags.
20+
1. Applying filters in `generators.yml`. Without filtering configuration, all endpoints will
21+
be included in your SDK regardless of their audience tags.
22+
23+
24+
<AccordionGroup>
25+
<Accordion title="Fern Definition">
26+
27+
Configuring audiences in a Fern Definition involves:
28+
29+
1. Explicitly defining audiences in `api.yml`.
30+
1. Configuring audiences for specific endpoints, types, and properties.
31+
1. Apply audience filters to your SDK so only certain endpoints are passed to the generators.
32+
33+
<Steps>
34+
### Defining audiences
35+
36+
Audiences are explicitly declared in Fern Definition.
37+
To use audiences in your Fern Definition, add them to `api.yml`.
38+
39+
In the example below, we have created audiences for `internal`, `beta`, and `customer` groups:
40+
41+
```yaml title='api.yml' {2-5}
42+
name: api
43+
audiences:
44+
- internal
45+
- beta
46+
- customers
47+
```
48+
### Apply audiences to your endpoints, types, and properties
49+
50+
Once you've defined audiences, mark endpoints, types, or properties for a
51+
particular consumer by adding an `audience` with the relevant groups.
52+
53+
<AccordionGroup>
54+
<Accordion title="Endpoints">
55+
56+
In this example, the `sendEmail` endpoint is only available to internal consumers:
57+
58+
```yaml title='user.yml' {6-7}
59+
service:
60+
base-path: /users
61+
auth: true
62+
endpoints:
63+
sendEmail:
64+
audiences:
65+
- internal
66+
path: /send-email
67+
...
68+
```
69+
</Accordion>
70+
<Accordion title="Types">
71+
72+
Types can also be marked for different audiences.
73+
74+
In this example, the `Email` type is available to internal and beta consumers:
75+
76+
```yaml title='user.yml' {5-7}
77+
Email:
78+
properties:
79+
subject: string
80+
body: optional<string>
81+
audiences:
82+
- internal
83+
- beta
84+
```
85+
</Accordion>
86+
<Accordion title="Properties">
87+
In this example, the `to` property is available to beta consumers only:
88+
89+
```yaml title='user.yml' {8-9}
90+
Email:
91+
properties:
92+
subject: string
93+
body: optional<string>
94+
to:
95+
type: string
96+
docs: The recipient of the email
97+
audiences:
98+
- beta
99+
```
100+
</Accordion>
101+
</AccordionGroup>
102+
103+
### Set up SDK filters in `generators.yml`
104+
105+
In `generators.yml`, you can apply audience filters so that only certain
106+
endpoints are passed to the generators.
107+
108+
The following example configures the SDKs to filter for `customers`:
109+
110+
```yaml title='generators.yml' {3-4}
111+
groups:
112+
external:
113+
audiences:
114+
- customers
115+
generators:
116+
...
117+
```
118+
### Generate your SDK
119+
120+
```bash
121+
fern generate --group sdk
122+
```
123+
</Steps>
124+
</Accordion>
125+
<Accordion title="OpenAPI">
126+
127+
Configuring audiences in an OpenAPI spec involves:
128+
129+
1. Configuring audience extensions for specific servers, endpoints, schemas, and properties.
130+
1. Apply audience filters to your SDK so only certain endpoints are passed to the generators.
131+
132+
<Note>
133+
Unlike the Fern Definition, OpenAPI doesn't have a central audience declaration.
134+
</Note>
135+
136+
<Steps>
137+
### Define audiences
138+
139+
OpenAPI uses `x-fern-audiences` to filter to servers, endpoints, schemas and properties.
140+
141+
<AccordionGroup>
142+
<Accordion title="Servers">
143+
To mark a server with a particular audience, add the `x-fern-server-name` and `x-fern-audiences` extension to the relevant server.
144+
145+
In the example below, the `Production` server is only available to public consumers:
146+
147+
```yaml title="openapi.yml" {3-5}
148+
servers:
149+
- url: https://api.com
150+
x-fern-server-name: Production
151+
x-fern-audiences:
152+
- public
153+
```
154+
</Accordion>
155+
<Accordion title="Endpoints">
156+
To mark an endpoint with a particular audience, add the `x-fern-audiences` extension to the relevant endpoint.
157+
158+
In the example below, the `POST /users/sendEmail` endpoint is only available to public consumers:
159+
160+
```yaml title="openapi.yml" {4-5}
161+
paths:
162+
/users/sendEmail:
163+
post:
164+
x-fern-audiences:
165+
- public
166+
operationId: send_email
167+
```
168+
</Accordion>
169+
<Accordion title="Schemas">
170+
Schemas can be marked for different audiences, as well.
171+
172+
In this example, the `Email` type is available to both public and beta customers.
173+
174+
```yaml title="openapi.yml" {13-15}
175+
components:
176+
schemas:
177+
Email:
178+
title: Email
179+
type: object
180+
properties:
181+
subject:
182+
type: string
183+
body:
184+
type: string
185+
to:
186+
type: string
187+
x-fern-audiences:
188+
- public
189+
- beta
190+
```
191+
</Accordion>
192+
<Accordion title="Properties">
193+
In this example, the `to` property is available to beta customers only.
194+
195+
```yaml title="openapi.yml" {13-17}
196+
components:
197+
schemas:
198+
Email:
199+
title: Email
200+
type: object
201+
properties:
202+
subject:
203+
type: string
204+
body:
205+
type: string
206+
to:
207+
type: string
208+
x-fern-audiences:
209+
- beta
210+
```
211+
</Accordion>
212+
213+
</AccordionGroup>
214+
215+
### Set up SDK filters in `generators.yml`
216+
217+
In `generators.yml`, you can apply audience filters so that only certain
218+
endpoints are passed to the generators.
219+
220+
The following example configures the SDK to filter to the `public` audience:
221+
222+
```yaml title="generators.yml" {3-4}
223+
groups:
224+
sdks:
225+
audiences:
226+
- public
227+
generators:
228+
...
229+
```
230+
231+
### Generate your SDK
232+
233+
```bash
234+
fern generate --group sdk
235+
```
236+
237+
</Steps>
238+
</Accordion>
239+
</AccordionGroup>

0 commit comments

Comments
 (0)