rs2 / restspace

1.4 How this manual is organized & prerequisites

Who this is for

You're comfortable with the things a mid-range front-end developer uses daily:

  • HTTP — methods, status codes, headers, request/response.
  • JSON — reading and writing it; the rough idea of JSON Schema helps but isn't required.
  • A little JavaScript — enough to write a fetch call and an async function. You'll need this only when you reach custom services (Part 8).

You do not need Rust, WebAssembly, or any systems-programming background. Where those appear (the optional Wasm engine), they're clearly marked as advanced and skippable.

A command line is assumed. Examples use PowerShell on Windows where shell specifics matter (RS2's primary development platform), but the HTTP calls translate directly to curl, fetch, or any HTTP client.

How to read it

The manual is built as a progressive path: each part assumes the ones before it. On a first pass, read front-to-back through at least Part 5 — by then you can build a real, authenticated backend. Parts 6–8 add power (queries, composition, custom code) and can be taken as you need them. Parts 9–11 and the appendices are reference material you'll return to.

Part You'll be able to…
1 — Orientation Explain what RS2 is and how its pieces fit (you're here)
2 — Getting Started Run a node and serve your first request
3 — Core Concepts Reason about messages, mounts, stores, and capabilities
4 — Storing Files and Data Use file/data and choose safe storage backends
5 — Auth & Access Control Add login, roles, and CORS
6 — Querying and Rendering Data Expose stored queries and render JSX templates
7 — Pipelines Compose flows, wrappers, webhooks, and schedules
8 — Custom Services Write/deploy code and integrate external providers
9 — HTTP API & Cross-Cutting Handle errors, idempotency, caching, limits
10 — Operating a Node Configure, log, manage infras, and run a deployment
11 — Migrating from v1 Bring an existing Restspace config across
Appendices Look up config keys, error codes, and CLI verbs

Conventions used throughout

  • Paths like /data/orders/ada are URLs relative to your node's address (e.g. http://127.0.0.1:3100). The host part is omitted for brevity.
  • Config snippets are JSON fragments from a tenant config or a mount's config block unless stated otherwise.
  • Request/response examples show the method and path, and sometimes the status and key headers (ETag, Location, X-Trace-Id).
  • Notes marked Advanced can be skipped on a first read.

This manual teaches you to use a running RS2 node. Two neighboring documents serve different audiences:

  • The operator skill (rs2-skill) is a concise reference for driving an existing server — handy once you know the concepts here.
  • The PRD and architecture notes (docs/agents/) explain why the runtime is built the way it is, for people working on the runtime itself.

Appendix F lists these and other pointers.

With the mental model in hand, Part 2 gets a node running and walks through your first request.

← Previous: 1.3 What you can build · Manual home · Next: Part 2 — Getting Started →