net_backend

API reference

The complete HTTP + WebSocket + JSON API of a net_backend_server server, for clients that talk to it directly: web pages, JavaScript / TypeScript, C#, GDScript, Python, anything with an HTTP and a WebSocket library.

Rust clients have ready-made libraries that already speak everything below:

Your client is… Use
a Rust app net_backend_client + net_backend_protocol
a Bevy game bevy_net_backend + net_backend_protocol
anything else this document

1. Overview#

A net_backend_server is a game backend you run yourself. Every server built with the framework speaks the same API; which parts are present depends on the modules the server registers. The reference server (the one the repository's deployment files install) registers all of them:

Module What it adds
core GET /v1/info, /healthz, /readyz, the WebSocket endpoint /v1/ws, the API documents
auth accounts, logins (email + password, Steam), tokens, sessions, email verification, password reset, roles, admin routes
storage per-player JSON objects (save slots, settings) with versions
chat public rooms, direct messages, history, presence, moderation

GET /v1/info lists the modules a server runs. A game's own server may add its own routes and WebSocket kinds on top; they follow the same conventions and appear in the server's API documents.

Base URL#

Throughout this document the server is https://your-server.example. Every API path starts with /v1/ (two health routes do not). WebSocket: wss://your-server.example/v1/ws.

Production servers run behind a reverse proxy that terminates TLS: use https:// and wss://.

Versioning#

  • Paths: /v1 is stable. Within /v1 no route, field or WebSocket kind is renamed or removed; new ones may be added. A breaking change would get /v2.
  • Protocol version: an integer, currently 1. A client may name the version it speaks in the x-net-backend-protocol header (HTTP requests and the WebSocket handshake) or in the protocol field of the WebSocket auth message. Without it the server assumes 1. Every HTTP answer (except CORS preflights) carries the server's own version in the same header, and GET /v1/info lists the accepted range:
json
{"protocol":1,"min_protocol":1,"modules":["auth","chat","storage"]}
  • An unsupported version is refused with unsupported_protocol and the details {"supported_min":1,"supported_max":1}: HTTP 400 on normal routes; on /v1/ws never 400 (see Version mismatch).

Machine-readable documents#

Document Where What
OpenAPI 3.1 GET /v1/openapi.json every documented HTTP route with its request and answer schemas; feed it to an OpenAPI generator for typed clients (TypeScript, C#, …)
AsyncAPI 3.0 GET /v1/asyncapi.json the WebSocket endpoint: the envelope, auth / auth.ok / auth.failed, every request kind with its answer, every push, the close codes (also as x-close-codes)
Browser UI GET /v1/docs an interactive viewer of the OpenAPI document, only when the operator enables it

The operator decides whether the documents are public (openapi.enabled, on by default). The admin routes are left out of the OpenAPI document unless the operator lists them (admin_in_openapi in the auth and storage module settings). This document covers all of them.

Health#

Route Answer
GET /healthz 200 {"status":"ok"} while the process runs (liveness)
GET /readyz 200 {"status":"ready"} when the database answers; 503 (error body) while shutting down or when the database is unreachable (readiness)

Generated from API.md (repository commit e25edb9, file sha256 3db87f7bba70).