WebSockets in the Fern Definition

WebSockets enable a user to create a connection with a server, over which bidirectional communication can be sent.

In Fern, you can specify WebSockets in your API definition. The WebSockets will be included in both the generated SDKs and the API documentation.

WebSocket definition

Each WebSocket is defined in its own file, where it is described by the channel object. Put your WebSocket definition files in your fern folder alongside your other API definition files.

The channel object

A channel is defined by the following fields:

• auth: The authentication scheme for the WebSocket
• path: The path of the WebSocket
• headers (Optional): Any headers the WebSocket will send
• path-parameters (Optional): Any path parameters in the WebSocket path
• query-parameters (Optional): Any query parameters used in the initial request of the WebSocket
• messages (Optional): The schemas of the messages the WebSocket can send and receive once connected
  • origin: The entity that sent the message (e.g. client or server)
  • body: The schema of the message
• examples: Example WebSocket connection (Optional)

WebSocket example

1
channel:
2
  path: /chat
3
  auth: false
4
  query-parameters:
5
    model_id:
6
      type: optional<string>
7
      docs: The unique identifier of the model.
8
    model_version:
9
      type: optional<integer>
10
      docs: The version number of the model.
11
  messages:
12
    publish:
13
      origin: client
14
      body: PublishEvent
15
    subscribe:
16
      origin: server
17
      body: SubscribeEvent
18
  examples: 
19
    - query-parameters: 
20
        model_id: "123"
21
      messages: 
22
        - type: publish
23
          body:
24
            text: "Hello, world."
25
        - type: subscribe
26
          body: 
27
            id: "23823049"
28
            message: "Hello there, how are you?"
29
types:
30
  PublishEvent:
31
    docs: The input from the user to send through the WebSocket. 
32
    properties: 
33
      text: 
34
        type: string
35
        docs: The user text to send into the conversation. 
36
  SubscribeEvent:
37
    docs: The response from the server sent through the WebSocket.
38
    properties: 
39
      id: 
40
        type: string
41
        docs: The id of the message. 
42
      message:
43
        type: string
44
        docs: The message sent through the socket. 

WebSocket API Reference

WebSocket Reference

Fern renders a unique reference page for WebSockets. The Handshake section outlines the protocol for connecting with the server, while the Send and Receive sections outline the message schemas that can be sent between the client and server.

Users can connect to and use WebSockets from right within the API Reference (check one of Hume’s WebSockets here).