Ludovic Marie
0a1d3a7534
docs/api/ gets one page per surface other programs build on (mods, shaders, agent control, servers, the launcher, data formats), each with an overview measured from the source, the guide, the generated reference, examples, its stability, what is not there yet and a changelog, plus the policy every API follows (docs/api/stability.md): a version per API, semver lines, experimental / preview / stable, deprecation windows, compatibility tests and the level of every part today. The website gets a "Build on Horizon" page (website/docs/apis.md) that summarises them and links the repository's pages. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
61 lines
3.0 KiB
Markdown
61 lines
3.0 KiB
Markdown
# Server API
|
|
|
|
What a host, a panel or a bot can do with a Horizon server: the `horizon-server` commands, `server.toml` and the
|
|
control API. How to host: [hosting.md](../hosting.md); the design: [server.md](../server.md).
|
|
|
|
## Overview
|
|
|
|
`horizon-server` sets up a server folder, runs the game as a dedicated server under a supervisor (restarts on a crash,
|
|
backups on a schedule, updates with a rollback), and lets other programs manage it through a local HTTP API with a
|
|
token. The web panel uses that API.
|
|
|
|
| | Count |
|
|
| --- | --- |
|
|
| Commands | 22 (`init`, `run`, `start`, `stop`, `restart`, `status`, `cmd`, `logs`, `backup`, `backups`, `restore`, `service`, `panel`, `update`, `rollback`, `config`, `config set`, `import`, `op`, `deop`, `whitelist`, `version`) |
|
|
| `server.toml` keys | 22 in 6 sections, plus `[properties]` for any other vanilla key |
|
|
| Control API endpoints | 11 under `/api/v1` |
|
|
|
|
## Guide
|
|
|
|
1. `horizon-server init` in an empty folder, then `horizon-server start` ([hosting.md](../hosting.md)).
|
|
2. From a script: `horizon-server status --json`, `horizon-server cmd say hi`, `horizon-server backup`.
|
|
3. From a program: read `.horizon/api.json` (address and token), then `GET /api/v1/status` with
|
|
`Authorization: Bearer <token>`.
|
|
|
|
## Reference
|
|
|
|
[server-reference.md](server-reference.md), generated from `horizon-server`'s source: the help text, every
|
|
`server.toml` key with its default and the `server.properties` key it writes, and every endpoint.
|
|
|
|
## Examples
|
|
|
|
```sh
|
|
token=$(jq -r .token .horizon/api.json); address=$(jq -r .address .horizon/api.json)
|
|
curl -s -H "Authorization: Bearer $token" "http://$address/api/v1/status"
|
|
curl -s -H "Authorization: Bearer $token" -d '{"line": "list"}' "http://$address/api/v1/command"
|
|
```
|
|
|
|
## Stability
|
|
|
|
Stable ([stability.md](stability.md)): the commands, `server.toml`'s keys and `/api/v1`. A new key or endpoint is an
|
|
addition; a change to one starts `/api/v2`, served beside `/api/v1`.
|
|
|
|
## Not there yet
|
|
|
|
- **Players**: list with ping and position, kick, ban and pardon, op and deop, the whitelist, as endpoints (today only
|
|
through `cmd` and the files).
|
|
- **Console stream**: the log as a stream (server-sent events) rather than `logs?since=N` polling; chat, joins, leaves,
|
|
deaths and crashes as typed events.
|
|
- **Metrics**: a plain-text metrics endpoint any monitoring tool can scrape (TPS, MSPT percentiles, players, chunks,
|
|
entities, RAM, CPU), from the samples `status` already takes.
|
|
- **Backups**: delete and download one; restore a single dimension.
|
|
- **Server mods**: list, turn on and off, and their settings, once the mod API runs on the server
|
|
([mods.md](mods.md)).
|
|
- **An MCP server** for the same endpoints, so a host's agent manages the server as it manages the game.
|
|
- **Compatibility tests**: golden replies per endpoint, and a `server.toml` from each release line.
|
|
|
|
## Changelog
|
|
|
|
- `api::ROUTES` lists the endpoints; the reference is generated from it.
|
|
- `/api/v1`: status, metrics, logs, command, stop, restart, backups, restore, update, panel login.
|