OpenRPCExtensions

Use audiences to filter your API

Use x-fern-audiences to filter to relevant methods, parameters and schemas

Audiences are a useful tool for segmenting your JSON-RPC 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.

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

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

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

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

Filter methods

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

openrpc.yml
1methods:
2  - name: public.getInfo
3    summary: Get public API information
4    description: Publicly available information about the API
5    x-fern-audiences:
6      - public
7    params: []
8    result:
9      name: info
10      schema:
11        $ref: '#/components/schemas/ApiInfo'
12  - name: admin.getUsers
13    summary: Get all users (admin only)
14    x-fern-audiences:
15      - admin
16    params:
17      - name: limit
18        schema:
19          type: integer
20          default: 100
21    result:
22      name: users
23      schema:
24        type: array
25        items:
26          $ref: '#/components/schemas/User'

Filter method parameters

You can filter specific parameters within methods:

openrpc.yml
1methods:
2  - name: user.create
3    summary: Create a new user
4    params:
5      - name: userData
6        schema:
7          type: object
8          properties:
9            email:
10              type: string
11              format: email
12            name:
13              type: string
14            adminNotes:
15              type: string
16              x-fern-audiences:
17                - admin
18            internalId:
19              type: string
20              x-fern-audiences:
21                - internal
22          required:
23            - email
24            - name
25        required: true
26    result:
27      name: user
28      schema:
29        $ref: '#/components/schemas/User'

Filter schemas

Filter entire schemas to different audiences:

openrpc.yml
1components:
2  schemas:
3    PublicUser:
4      type: object
5      x-fern-audiences:
6        - public
7      properties:
8        id:
9          type: string
10        name:
11          type: string
12        email:
13          type: string
14      required:
15        - id
16        - name
17        - email
18    AdminUser:
19      allOf:
20        - $ref: '#/components/schemas/PublicUser'
21        - type: object
22          x-fern-audiences:
23            - admin
24          properties:
25            role:
26              type: string
27            permissions:
28              type: array
29              items:
30                type: string
31            createdAt:
32              type: string
33              format: date-time
34            lastLoginAt:
35              type: string
36              format: date-time

Filter schema properties

You can filter individual properties within schemas:

openrpc.yml
1components:
2  schemas:
3    Order:
4      type: object
5      properties:
6        id:
7          type: string
8        amount:
9          type: number
10          x-fern-audiences:
11            - public
12        internalCost:
13          type: number
14          x-fern-audiences:
15            - internal
16        debugInfo:
17          type: object
18          x-fern-audiences:
19            - debug
20        customerInfo:
21          type: object
22          properties:
23            id:
24              type: string
25            email:
26              type: string
27              x-fern-audiences:
28                - admin

Filter error responses

Filter error information based on audience:

openrpc.yml
1methods:
2  - name: payment.process
3    summary: Process a payment
4    params:
5      - name: paymentData
6        schema:
7          $ref: '#/components/schemas/PaymentRequest'
8    errors:
9      - code: -32001
10        message: Payment failed
11        x-fern-audiences:
12          - public
13        data:
14          type: object
15          properties:
16            error:
17              type: string
18              const: "Payment could not be processed"
19      - code: -32001
20        message: Payment failed
21        x-fern-audiences:
22          - admin
23        data:
24          type: object
25          properties:
26            error:
27              type: string
28            errorCode:
29              type: string
30            gatewayResponse:
31              type: object
32            debugTrace:
33              type: string

Server-level filtering

Apply audience filtering at the server level:

openrpc.yml
1servers:
2  - name: public-api
3    url: https://api.example.com/rpc
4    x-fern-audiences:
5      - public
6    description: Public API server
7  - name: admin-api
8    url: https://admin-api.example.com/rpc
9    x-fern-audiences:
10      - admin
11    description: Admin API server with additional privileges

Conditional method availability

Use audiences to make methods available only in certain contexts:

openrpc.yml
1methods:
2  - name: debug.getSystemInfo
3    summary: Get system debug information
4    description: Internal system information for debugging
5    x-fern-audiences:
6      - debug
7    params: []
8    result:
9      name: systemInfo
10      schema:
11        type: object
12        additionalProperties: true
13  - name: beta.advancedSearch
14    summary: Advanced search functionality
15    x-fern-audiences:
16      - beta
17    params:
18      - name: query
19        schema:
20          type: object
21          properties:
22            text:
23              type: string
24            filters:
25              type: object
26              additionalProperties: true
27    result:
28      name: results
29      schema:
30        $ref: '#/components/schemas/SearchResults'
31  - name: internal.resetCache
32    summary: Reset internal caches
33    x-fern-audiences:
34      - internal
35    params:
36      - name: cacheType
37        schema:
38          type: string
39          enum: [user, product, session, all]
40    # Notification - no result expected

This allows you to create different views of the same JSON-RPC API for different types of consumers, ensuring each audience only sees the methods and data relevant to their use case.