netfishing-discovery-server/docs/API.md

Discovery API v1

The API stores public room advertisements as short-lived leases. It does not proxy or relay game traffic. NETfishing continues to connect to the returned host and UDP port through ENet.

All request and response bodies use application/json. Production clients must use HTTPS.

GET /health

Returns service status and the number of active, unexpired room leases.

GET /v1/rooms

Lists active rooms. Optional exact-match filters:

• game_version
• protocol_version

The response contains rooms and the server's ttl_seconds.

POST /v1/rooms

Creates a room lease. The service derives the advertised address from the connection rather than trusting an address supplied by the game client.

{
  "room_name": "Pond Friends",
  "port": 7777,
  "current_players": 0,
  "max_players": 8,
  "game_version": "0.6.4-alpha",
  "protocol_version": 3
}

current_players may be zero for an empty dedicated server. A player-hosted room normally includes its host in this count.

The 201 response includes the public room and a secret lease_token. The host retains that token only for the current hosting session.

The service applies configured global and per-observed-address active-room limits. Exceeding one returns 429 room_limit; expired leases stop counting automatically.

PUT /v1/rooms/{room_id}

Renews and updates a room lease. Send the complete room payload and:

Authorization: Bearer <lease_token>

Hosts should heartbeat well before the configured TTL, initially every 15 seconds for a 45-second lease. A missing heartbeat causes automatic removal without requiring a disconnect callback.

DELETE /v1/rooms/{room_id}

Removes a room immediately. Requires the same bearer token. A clean host shutdown should call this, but TTL expiry remains authoritative for crashes and lost connectivity.

Error shape

{
  "error": {
    "code": "invalid_room",
    "message": "port must be between 1 and 65535"
  }
}

Trust boundary

• The observed source IP is authoritative for a room's public address.
• X-Forwarded-For is honored only when the immediate peer belongs to an explicitly configured trusted proxy CIDR.
• Lease tokens authorize update and deletion but are never included in public listings.
• The service is an ephemeral directory, not a source of gameplay authority.