6.1 REST API Endpoints

REST API Endpoints

v0.2 contract for corpus_ipc_server (Axum 0.8, feature server). Sources: src/server.rs, docs/rest-api.md, contract tests in tests/server_contract.rs.

Endpoints

Endpoint	Request body	Success 200 body	Error statuses
POST /initialize	{"model_path": string?} ({} ok)	{"ok": true, "message": "initialized"}	400, 415, 422, 502, 500
POST /process	{"inputs": [f32, ...]}	{"ok": true, "output": [f32, ...]}	400, 409, 415, 422, 502, 500
POST /save_state	{"model_path": string}	{"ok": true, "message": "state saved"}	400, 409, 415, 422, 502, 500
POST /reset	none	{"ok": true, "message": "reset"}	502, 500

Other methods → 405. Unknown paths → 404. save_state is backend-specific; current backends treat it as a successful no-op.

Error envelope

Non-2xx JSON bodies:

{"ok": false, "error": {"code": "<code>", "message": "<detail>"}}

Status	code	Meaning
400	bad_request	Malformed JSON / unreadable body
415	unsupported_media_type	Missing or non-JSON Content-Type on body endpoints
422	invalid_input	Schema/validation failure or BackendError::InvalidInput
409	not_initialized	/process or /save_state before /initialize or after /reset
502	backend_error	Other BackendError variants
500	internal_error	e.g. poisoned backend mutex

Mapping helpers: json_rejection, backend_error, ApiError in src/server.rs.

Lifecycle

• /process and /save_state require AppState.initialized == true (set after successful /initialize, cleared after successful /reset).
• /reset is idempotent; both shipped backends clear initialized state, so the next /process needs /initialize again (required for connection-oriented ZMQ).
• /initialize is idempotent on success.

Migration from 0.1 REST

The 0.1 surface answered application results with HTTP 200 and {"ok": false, "message"} on backend errors. v0.2 is not wire-compatible with that: real status classes, nested error object, and success bodies gain "ok": true (/process includes output). Request bodies for /process are unchanged.