Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/floriansalvi/HEIG-VD_Ocha-api/llms.txt

Use this file to discover all available pages before exploring further.

The Ocha API includes a WebSocket server that runs on the same port as the HTTP API. This lets clients receive real-time push events — for example, when an administrator creates a new product — without polling REST endpoints. The WebSocket server is built with the ws library and is attached directly to the Node.js HTTP server.

​
Server details

The WebSocket server shares the HTTP server’s port. The port is read from the PORT environment variable (default 5001 as documented in the environment reference).
DetailValue
Protocolws:// (upgrade from HTTP)
Default port5001
Environment varPORT
Connection URLws://localhost:5001
Because the WebSocket server shares a port with the HTTP API, no additional firewall rules or port mappings are required beyond what is already open for the REST API.

​
Connection handshake

When a client successfully connects, the server immediately sends a welcome message: 
{ "message": "Connecté au WebSocket" }
All messages from the server are JSON strings. Parse them with JSON.parse() after receiving.

​
Broadcast events

The server can push events to all connected clients. Currently one event type is defined:

​
new_product

Broadcast whenever an administrator creates a new product via POST /api/v1/products. The payload contains the full product document as persisted to the database. 
{
  "type": "new_product",
  "product": {
    "_id": "64f1c2e9a1b2c3d4e5f12345",
    "slug": "matcha-latte",
    "name": "Matcha Latte",
    "category": "drinks",
    "description": "Delicious matcha latte with a hint of sweetness.",
    "basePriceCHF": 5.00,
    "isActive": true,
    "image": "https://res.cloudinary.com/example/image/upload/products/matcha-latte.webp"
  }
}

​
JavaScript client example

The example below connects to the WebSocket server and logs all incoming events to the console. In a browser or Node.js environment, use the built-in WebSocket global (or the ws package for Node.js). 
const socket = new WebSocket("ws://localhost:5001");

socket.addEventListener("open", () => {
  console.log("WebSocket connection established");
});

socket.addEventListener("message", (event) => {
  const data = JSON.parse(event.data);

  // Welcome message on connect
  if (data.message) {
    console.log("Server:", data.message);
    return;
  }

  // Handle broadcast events
  switch (data.type) {
    case "new_product":
      console.log("New product added:", data.product.name);
      break;
    default:
      console.log("Unknown event:", data);
  }
});

socket.addEventListener("close", () => {
  console.log("WebSocket connection closed");
});

socket.addEventListener("error", (err) => {
  console.error("WebSocket error:", err);
});
1

Open a WebSocket connection

Create a WebSocket instance pointing to ws://localhost:5001 (replace the host and port with your server’s address in production).
2

Receive the welcome message

The server sends { "message": "Connecté au WebSocket" } immediately after the connection is accepted.
3

Listen for broadcast events

Parse incoming messages as JSON and branch on the type field to handle each event kind.
4

Handle connection lifecycle

Implement close and error listeners to detect disconnections and implement reconnect logic as needed.

​
Testing with Postman

Postman supports WebSocket connections natively. Open File → New → WebSocket, enter ws://localhost:5001 as the URL, and click Connect. You will see the welcome message appear in the message log immediately. Trigger a new_product event by creating a product through the REST API (requires an admin token) and observe the broadcast appear in Postman in real time.

​
Next steps

Create a product

Trigger a new_product WebSocket broadcast by creating a product as an admin.

Roles and permissions

Learn which endpoints require admin access, including product creation.

Build docs developers (and LLMs) love

Get started for freeTalk to us