Building a WebSocket Server with FastAPI: A Beginner’s Guide

WebSocket communication is a crucial aspect of modern web development, enabling real-time, bidirectional data transfer between clients and servers. In this beginner-friendly guide, we’ll explore how to set up a WebSocket server using the FastAPI web framework and the websockets library. FastAPI’s simplicity and automatic documentation generation make it an excellent choice for junior developers looking to dive into WebSocket development.

Prerequisites

Before we begin, ensure you have the following prerequisites in place:

• Python installed (version 3.7 or higher).
• A basic understanding of Python and web development concepts.

Let’s get started!

Setting Up the FastAPI App

FastAPI is a modern Python web framework known for its speed and ease of use. We’ll use it to create a WebSocket server.

First, create a virtual environment to keep your project dependencies isolated. Open your terminal and run:

python -m venv websocket-env

Activate the virtual environment:

• On Windows:

websocket-env\Scripts\activate

• On macOS and Linux:

source websocket-env/bin/activate

Now, install the required libraries:

pip install fastapi uvicorn websockets

Let’s create a FastAPI app:

from fastapi import FastAPI, WebSocket

app = FastAPI()

@app.websocket("/ws")
async def websocket_endpoint(websocket: WebSocket):
    await websocket.accept()
    while True:
        data = await websocket.receive_text()
        await websocket.send_text(f"You sent: {data}")

In this code snippet, we import FastAPI and websockets and create an instance of the FastAPI app. We define a WebSocket route using the @app.websocket decorator, which listens for incoming WebSocket connections at the /ws endpoint.

Handling WebSocket Connections

The websocket_endpoint function handles WebSocket connections. Here’s how it works:

• await websocket.accept(): This line accepts the WebSocket connection and allows bidirectional communication.
• The function then enters a loop to continuously receive messages using await websocket.receive_text() and send responses using await websocket.send_text().

Running the WebSocket Server

To run the FastAPI application with the WebSocket server, use the uvicorn command:

uvicorn your_app_module_name:app --host 0.0.0.0 --port 8000 --reload

Replace your_app_module_name with the name of your Python script containing the FastAPI app. The server will be accessible at ws://localhost:8000/ws.

Testing the WebSocket Server

To test your WebSocket server, you can create a WebSocket client using JavaScript’s WebSocket API or use any WebSocket client tool. Here’s a simple JavaScript example:

const socket = new WebSocket("ws://localhost:8000/ws");

socket.onopen = () => {
  socket.send("Hello, WebSocket Server!");
};

socket.onmessage = (event) => {
  console.log("Server says: " + event.data);
};

// Close the WebSocket connection when done
socket.onclose = () => {
  console.log("WebSocket connection closed.");
};

This client connects to the WebSocket server, sends a message, and logs the server’s response.

Conclusion

Congratulations! You’ve successfully set up a WebSocket server using FastAPI and websockets. WebSocket communication is a powerful tool for building real-time applications, and FastAPI’s simplicity makes it accessible even for junior developers.

Remember, practice is key to mastering any technology. Experiment with different WebSocket features and explore more advanced use cases. Happy coding!